Skip to main content

Button

Buttons are used to trigger actions. There are different button variants that are used for different types of actions.

Demo

Usage

When to use

  • Trigger an action. Interacting with a button should always trigger an action.

When not to use

  • Navigation. Don't use a button for actions that are only navigational, like moving to a different screen in an app. Use a link instead.

Variants

Quick reference

VariantWhen to use
BasicDefault. Will suit the majority of actions on a page.
PrimaryUse for the most important action on a page, like a Save data button in a form. Only use one primary button on a page.
SecondaryUse for less important actions, usually in combination with other buttons. Can be applied to Destructive.
DestructiveOnly for primary-type actions that will delete or destroy something. Don't use several on a single page.

Basic

Demo
<Button basic>Basic button</Button>
  • A basic button is the default button to use. It suits the majority of use cases.
  • Don't use a basic button for the most important action on the page. Use primary instead.

Primary

Demo
<Button primary>Primary button</Button>
  • Only use for the most important action on a page, like Save data in a form.
  • Only use one primary button per page, otherwise it's not clear what the main action is.
  • A page doesn't need to have a primary button if there isn't a clear main action.

Secondary

Demo
<Button secondary>Secondary button</Button>
  • Use for actions that are used less often. Using secondary buttons reduces amount of elements on a page competing for a user's attention.
  • Use as a passive alternative to primary actions, like Cancel as a passive alternative to Save.
  • Don't use if there's only one action on the page.

Destructive

Demo
<Button destructive>Destructive button</Button>
Demo
<Button destructive secondary>
Destructive secondary button
</Button>
  • Only use for primary-type actions that will destroy data.
  • Don't use if the action will only remove an item from the current context.
  • Only use a one destructive button per page.
  • Destructive secondary can be used more than once per page for less important destructive actions.

Format

Content

  • Button labels should be clear and concise.
  • It should be clear what will happen when triggering the button. Save data is clearer than just Save, for example.
  • Use an action verb for labels. Avoid ambiguous labels like "OK".
  • Check the A-Z glossary ==link== and communication guidelines ==link== for more tips for writing useful labels.

Size

Buttons are available in different sizes. Use the size that matches the usage guidelines.

SizeWhen to use
smallCompact interfaces and secondary actions.
mediumDefault. The standard size that should be used in most cases.
largeSimple interfaces with only one or two main actions.

Spacing

  • As a general rule, leave at least dp4 spacing around a button. For interfaces with more space, use dp8.

Options

Demo
<DropdownButton>Dropdown button</DropdownButton>
  • A dropdown button offers several actions in a small space. Clicking the button opens a menu with several actions.
  • Use to replace a group of buttons where space is limited.
  • A dropdown button label should make it clear there are more options inside, like Actions.

Split button

Demo
<SplitButton>Split button</SplitButton>
  • A split button offers a main action and a dropdown of several other actions. Clicking the main button triggers an action. Clicking the split arrow opens a menu with several actions.
  • Use when there is a main action and several secondary actions, like a main action of Save and secondary actions of Save and add another and Save and open.
  • Use when space is limited. Otherwise, show buttons for all the actions.
  • Don't use when there isn't an obvious main action.

Toggle button

Demo
<div className="stacked-examples-horizontal">
<Button icon={<IconCheckmark24 />}></Button>
<Button icon={<IconCheckmark24 />} toggled></Button>
</div>
  • Represents an on/off state.
  • Use a toggle button when an option can be turned on or off, and a checkbox ==link== isn't suitable, like in a toolbar.
  • Toggle buttons can be used with basic and secondary variants.
  • If the button doesn't have a text label, show a tooltip ==link== on hover and focus that tells the user what's being toggled.

Icon

Demo
<div className="stacked-examples-horizontal">
<Button icon={<IconCheckmark24 />}>Mark as complete</Button>
<Button icon={<IconCheckmark24 />}></Button>
</div>
  • Buttons can have an optional icon alongside the text label.
  • Buttons can show only an icon.
  • Icons with a text label are useful for providing more information about the action. Users scanning an interface might recognize an icon quicker than text.
  • Buttons with only an icon need to show a tooltip ==link== on hover and focus that tells the user what the button action is.
  • Regular size buttons use 24px icons. Buttons size small use 16px icons.

State: Disabled

Demo
<Button disabled>Enroll in program</Button>
  • Use a disabled state when the button action can't be triggered.
  • Show a tooltip ==link== on hover, or help text, that tells the user why the action can't be triggered.
  • Don't change the button label between disabled and enabled states.
  • If a button action won't ever be enabled in the current context, consider removing it instead.

State: Loading

Demo
<Button loading>Loading…</Button>
  • Use a loading state after a user triggers that button.
  • Change the button label to tell the user what's happening. For example, after clicking a Start job button, the loading state label could be Starting job….
  • If triggering other actions on the page should be prevented, consider showing a blocking loader ==link== instead.

API Reference

Button

Usage

To use Button, you can import the component from the @dhis2/ui library

import { Button } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennodeComponent to render inside the button
classNamestringA className that will be passed to the <button> element
dataTeststring'dhis2-uicore-button'A string that will be applied as a data-test attribute on the button element
for identification during testing
destructivebooleanApplies 'destructive' button appearance, implying a dangerous action.
disabledbooleanApplies a greyed-out appearance and makes the button non-interactive
iconelementAn icon element to display inside the button
initialFocusbooleanUse this variant to capture the initial focus on the page.
largecustomMakes the button large. Mutually exclusive with small
loadingbooleanSets the button into a loading state
namestringSets name attribute on button element.
Gets passed as part of the first argument to callbacks (see onClick).
primarybooleanApplies 'primary' button appearance, implying the most important action.
secondarybooleanApplies 'secondary' button appearance.
smallcustomMakes the button small. Mutually exclusive with large prop
tabIndexstringTab index for focusing the button with a keyboard
toggledbooleanChanges appearance of button to an on/off state
type'submit' │ 'reset' │ 'button''button'Sets type attribute on <button> element
valuestringValue associated with the button.
Gets passed as part of the first argument to callbacks (see onClick).
onBlurfunctionCallback to trigger on de-focus (blur).
Called with same args as onClick
onClickfunctionCallback to trigger on click.
Called with args ({ value, name }, event)
onFocusfunctionCallback to trigger on focus. Called with same args as onClick
onKeyDownfunctionCallback to trigger on key-down. Called with same args as onClick

ButtonStrip

Usage

To use ButtonStrip, you can import the component from the @dhis2/ui library

import { ButtonStrip } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennode
classNamestring
dataTeststring'dhis2-uicore-buttonstrip'
endcustomHorizontal alignment for buttons. Mutually exclusive with middle prop
middlecustomHorizontal alignment. Mutually exclusive with end prop

Usage

To use DropdownButton, you can import the component from the @dhis2/ui library

import { DropdownButton } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennodeChildren to render inside the buton
classNamestring
componentelementComponent to show/hide when button is clicked
dataTeststring'dhis2-uicore-dropdownbutton'
destructivebooleanApplies 'destructive' button appearance, implying a dangerous action.
disabledbooleanMake the button non-interactive
iconelement
initialFocusbooleanGrants button initial focus on the page
largecustomButton size. Mutually exclusive with small prop
namestring
openbooleanControls popper visibility. When implementing this prop the component becomes a controlled component
primarybooleanApplies 'primary' button appearance, implying the most important action.
secondarybooleanApplies 'secondary' button appearance.
smallcustomButton size. Mutually exclusive with large prop
tabIndexstring
type'submit' │ 'reset' │ 'button'Type of button. Can take advantage of different default behavior
valuestring
onClickcustom(function)Callback triggered on click.
Called with signature ({ name: string, value: string, open: bool }, event)
Is required when using the open prop to override the internal
state.

SplitButton

Usage

To use SplitButton, you can import the component from the @dhis2/ui library

import { SplitButton } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrenstring
classNamestring
componentelementComponent to render when the dropdown is opened
dataTeststring'dhis2-uicore-splitbutton'
destructivebooleanApplies 'destructive' button appearance, implying a dangerous action.
disabledbooleanDisables the button and makes it uninteractive
iconelementAn icon to add inside the button
initialFocusbooleanGrants the button the initial focus
largecustomChanges button size. Mutually exclusive with small prop
namestring
primarybooleanApplies 'primary' button appearance, implying the most important action.
secondarybooleanApplies 'secondary' button appearance.
smallcustomChanges button size. Mutually exclusive with large prop
tabIndexstring
type'submit' │ 'reset' │ 'button'Type of button. Applied to html button element
valuestringValue associated with the button. Passed in object to onClick handler
onClickfunction