---
title: "Button"
description: "Buttons are used to trigger actions. There are different button variants that are used for different types of actions."
url: https://developers.dhis2.org/docs/ui/components/button
source: https://github.com/dhis2/developer-portal/edit/main/docs/ui/components/button.md
---

# Button

Buttons are used to trigger actions. There are different button variants that are used for different types of actions.
[Interactive demo: button--basic](https://developers.dhis2.org/demo/?path=/story/button--basic)

## 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

[Interactive demo: button--basic](https://developers.dhis2.org/demo/?path=/story/button--basic)

```jsx
<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

[Interactive demo: button--primary](https://developers.dhis2.org/demo/?path=/story/button--primary)

```jsx
<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

[Interactive demo: button--secondary](https://developers.dhis2.org/demo/?path=/story/button--secondary)

```jsx
<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

[Interactive demo: button--destructive](https://developers.dhis2.org/demo/?path=/story/button--destructive)

```jsx
<Button destructive>Destructive button</Button>
```

[Interactive demo: button--destructive-secondary](https://developers.dhis2.org/demo/?path=/story/button--destructive-secondary)

```jsx
<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

[Interactive demo: dropdown-button--default](https://developers.dhis2.org/demo/?path=/story/dropdown-button--default)

```jsx
<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

[Interactive demo: split-button--default](https://developers.dhis2.org/demo/?path=/story/split-button--default)

```jsx
<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**

        [Interactive demo: button--toggled](https://developers.dhis2.org/demo/?path=/story/button--toggled)

**Toggled off**

        [Interactive demo: button--toggled](https://developers.dhis2.org/demo/?path=/story/button--toggled)

```jsx
<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

[Interactive demo: button--icon](https://developers.dhis2.org/demo/?path=/story/button--icon)

```jsx
<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

[Interactive demo: button--disabled](https://developers.dhis2.org/demo/?path=/story/button--disabled)

```jsx
<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

[Interactive demo: button--loading](https://developers.dhis2.org/demo/?path=/story/button--loading)

```jsx
<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  

```js
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<br/>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.<br/>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.<br/>Gets passed as part of the first argument to callbacks (see `onClick`).|
|onBlur|function|||Callback to trigger on de-focus (blur).<br/>Called with same args as `onClick`|
|onClick|function|||Callback to trigger on click.<br/>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  

```js
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  

```js
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.<br/>Called with signature `({ name: string, value: string, open: bool }, event)`<br/>Is required when using the `open` prop to override the internal<br/>state.|

### SplitButton

#### Usage

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

```js
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.<br/>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).<br/>Called with signature `({ name: string, value: string, open: bool }, event)`.<br/>Required if `open` prop is used (controlled component).|
