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

Variant	When to use
Basic	Default. Will suit the majority of actions on a page.
Primary	Use for the most important action on a page, like a Save data button in a form. Only use one primary button on a page.
Secondary	Use for less important actions, usually in combination with other buttons. Can be applied to Destructive.
Destructive	Only 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.

Size	When to use
small	Compact interfaces and secondary actions.
medium	Default. The standard size that should be used in most cases.
large	Simple 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

Dropdown button

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

• Toggled on
• Toggled off

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

Name	Type	Default	Required	Description
children	node			Component to render inside the button
className	string			A className that will be passed to the <button> element
dataTest	string	'dhis2-uicore-button'		A string that will be applied as a data-test attribute on the button element for identification during testing
destructive	boolean			Applies 'destructive' button appearance, implying a dangerous action.
disabled	boolean			Applies a greyed-out appearance and makes the button non-interactive
icon	element			An icon element to display inside the button
initialFocus	boolean			Use this variant to capture the initial focus on the page.
large	custom			Makes the button large. Mutually exclusive with small
loading	boolean			Sets the button into a loading state
name	string			Sets name attribute on button element. Gets passed as part of the first argument to callbacks (see onClick).
primary	boolean			Applies 'primary' button appearance, implying the most important action.
secondary	boolean			Applies 'secondary' button appearance.
small	custom			Makes the button small. Mutually exclusive with large prop
tabIndex	string			Tab index for focusing the button with a keyboard
toggled	boolean			Changes appearance of button to an on/off state
type	'submit' │ 'reset' │ 'button'	'button'		Sets type attribute on <button> element
value	string			Value associated with the button. Gets passed as part of the first argument to callbacks (see onClick).
onBlur	function			Callback to trigger on de-focus (blur). Called with same args as onClick
onClick	function			Callback to trigger on click. Called with args ({ value, name }, event)
onFocus	function			Callback to trigger on focus. Called with same args as onClick
onKeyDown	function			Callback 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

Name	Type	Default	Required	Description
children	node
className	string
dataTest	string	'dhis2-uicore-buttonstrip'
end	custom			Horizontal alignment for buttons. Mutually exclusive with middle prop
middle	custom			Horizontal alignment. Mutually exclusive with end prop

DropdownButton

Usage

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

import { DropdownButton } from '@dhis2/ui'

Props

Name	Type	Default	Required	Description
children	node			Children to render inside the buton
className	string
component	element			Component to show/hide when button is clicked
dataTest	string	'dhis2-uicore-dropdownbutton'
destructive	boolean			Applies 'destructive' button appearance, implying a dangerous action.
disabled	boolean			Make the button non-interactive
icon	element
initialFocus	boolean			Grants button initial focus on the page
large	custom			Button size. Mutually exclusive with small prop
name	string
open	boolean			Controls popper visibility. When implementing this prop the component becomes a controlled component
primary	boolean			Applies 'primary' button appearance, implying the most important action.
secondary	boolean			Applies 'secondary' button appearance.
small	custom			Button size. Mutually exclusive with large prop
tabIndex	string
type	'submit' │ 'reset' │ 'button'			Type of button. Can take advantage of different default behavior
value	string
onClick	custom(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

Name	Type	Default	Required	Description
children	string
className	string
component	element			Component to render when the dropdown is opened
dataTest	string	'dhis2-uicore-splitbutton'
destructive	boolean			Applies 'destructive' button appearance, implying a dangerous action.
disabled	boolean			Disables the button and makes it uninteractive
icon	element			An icon to add inside the button
initialFocus	boolean			Grants the button the initial focus
large	custom			Changes button size. Mutually exclusive with small prop
name	string
open	boolean			Controls popper visibility. When implementing this prop the component becomes a controlled component
primary	boolean			Applies 'primary' button appearance, implying the most important action.
secondary	boolean			Applies 'secondary' button appearance.
small	custom			Changes button size. Mutually exclusive with large prop
tabIndex	string
type	'submit' │ 'reset' │ 'button'			Type of button. Applied to html button element
value	string			Value associated with the button. Passed in object to onClick handler
onClick	function			Callback triggered when the main button is clicked. Called with signature ({ name: string, value: string, open: bool }, event)
onToggle	custom(function)			Callback triggered when the dropdown is toggled (by clicking the chevron, pressing Escape, or clicking the backdrop). Called with signature ({ name: string, value: string, open: bool }, event). Required if open prop is used (controlled component).