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. Useprimary
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, usedp8
.
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
andsecondary
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 elementfor 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 internalstate. |
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 | |||
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 |