React UI
Edit page
Home
Getting Started
Customize
Foundation
Components: UI
Alert Badge Button
Basic Usage General Guidelines Priorities Sizes Buttons with Icons Buttons with Badges States API ButtonGroup Card CheckboxField Modal Radio ScrollView SelectField Table TextArea TextField Toggle
Components: Layouts
CSS Helpers
Readme

# Button

Buttons allow users to take actions.

##
Basic Usage

To implement the Button component, you need to import it first:

    import { Button } from '@react-ui-org/react-ui';

And use it:

<Button label="My button" />

    <Button label="My button" />

See
API for all available options.

## General Guidelines

- Use
  short yet comprehensible labels to make buttons fit small screens.

- Since buttons are there to take actions, use a verb to make it obvious what your buttons do.

- Don't overwhelm your UI with too many high-emphasis actions. There should always be one but chances are that having more of them is not necessary.

## Priorities

There are three visual priorities of buttons to choose from, from highest to lowest:

1. default
2. outline
3. flat

All priorities come in following color variants:

- brand colors: primary, secondary
- selected UI colors: success, warning, danger (based on error color, uses a different name because error button doesn't make much sense)
- dark color

To complete the list, there is also a link priority which is reserved for special cases.

### Default

The default, high-emphasis priority should be used for primary actions of your app. Use it sparingly but remember there should always be one on a screen.

<Button label="Primary" /> <Button label="Secondary" variant="secondary" /> <Button label="Success" variant="success" /> <Button label="Warning" variant="warning" /> <Button label="Danger" variant="danger" /> <Button label="Dark" variant="dark" />

    <Button label="Primary" /><Button label="Secondary" variant="secondary" /><Button label="Success" variant="success" /><Button label="Warning" variant="warning" /><Button label="Danger" variant="danger" /><Button label="Dark" variant="dark" />

Default, unconfigured button comes in medium size, default visual priority, and primary color variant.

### Outline

Medium-emphasis buttons. They are designed to contain actions that are important but not primary in your app.

<Button priority="outline" label="Primary" /> <Button priority="outline" label="Secondary" variant="secondary" /> <Button priority="outline" label="Success" variant="success" /> <Button priority="outline" label="Warning" variant="warning" /> <Button priority="outline" label="Danger" variant="danger" /> <Button priority="outline" label="Dark" variant="dark" />

    <Button priority="outline" label="Primary" /><Button priority="outline" label="Secondary" variant="secondary" /><Button priority="outline" label="Success" variant="success" /><Button priority="outline" label="Warning" variant="warning" /><Button priority="outline" label="Danger" variant="danger" /><Button priority="outline" label="Dark" variant="dark" />

### Flat

Flat buttons are designed for less pronounced actions to help maintain focus on the content.

<Button priority="flat" label="Primary" /> <Button priority="flat" label="Secondary" variant="secondary" /> <Button priority="flat" label="Success" variant="success" /> <Button priority="flat" label="Warning" variant="warning" /> <Button priority="flat" label="Danger" variant="danger" /> <Button priority="flat" label="Dark" variant="dark" />

    <Button priority="flat" label="Primary" /><Button priority="flat" label="Secondary" variant="secondary" /><Button priority="flat" label="Success" variant="success" /><Button priority="flat" label="Warning" variant="warning" /><Button priority="flat" label="Danger" variant="danger" /><Button priority="flat" label="Dark" variant="dark" />

### Link

Link button is more a workaround than a priority level. Use it for what needs to appear as navigation to users but where a button must be used due to technical reasons. Under normal circumstances, you should always use a link HTML element
`<a href="…">` for navigation.

⚠️ Avoid using link buttons for actions, choose flat or outline priority instead. This is because users expect navigation to happen when clicking on something what looks like a link.

<Button label="Link that needs to be implemented as button" priority="link" />

    <Button label="Link that needs to be implemented as button" priority="link" />

## Sizes

Aside from the default (medium) size, two additional sizes are available: small and large.

<Button label="Small" size="small" /> <Button label="Medium" /> <Button label="Large" size="large" />

    <Button label="Small" size="small" /><Button label="Medium" /><Button label="Large" size="large" />

Block buttons span the full width of a parent:

<Button label="Block button" block />

    <Button label="Block button" block />

## Buttons with Icons

To improve clarity or to draw attention to the action, icons can be added before or after the button's label.

👉 Please note there are no icons pre-packed in React UI. Visit Icons to see how it works.

<Button label="Icon before label" beforeLabel={<Icon icon="star" />} /> <Button label="Icon after label" afterLabel={<Icon icon="star" />} /> <Button label="Link button with icon" beforeLabel={<Icon icon="star" />} priority="link" />

    <Button label="Icon before label" beforeLabel={<Icon icon="star" />} /><Button label="Icon after label" afterLabel={<Icon icon="star" />} /><Button  label="Link button with icon"  beforeLabel={<Icon icon="star" />}  priority="link"/>

### Icon Buttons

For clear and simple actions, buttons can visually consist just of an icon. Label remains mandatory to keep the button accessible. Icon buttons can optionally enhance on desktop and display the label once there is enough room for it.

<Button label="Icon button" labelVisibility="none" afterLabel={<Icon icon="pencil" />} /> <Button label="Icon button with label visible on desktop" labelVisibility="desktop" beforeLabel={<Icon icon="pencil" />} />

    <Button  label="Icon button"  labelVisibility="none"  afterLabel={<Icon icon="pencil" />}/><Button  label="Icon button with label visible on desktop"  labelVisibility="desktop"  beforeLabel={<Icon icon="pencil" />}/>

## Buttons with Badges

A Badge can be added to buttons to provide additional information or to draw user's attention.

<Button label="Badge before" beforeLabel={<Badge label={3} type="light" priority="outline" />} /> <Button label="Badge before, on top" startCorner={<Badge label={3} />} /> <Button label="Badge after, on top" endCorner={<Badge label={3} />} priority="outline" /> <Button label="Badge after" afterLabel={<Badge label="new" type="warning" />} priority="outline" />

    <Button  label="Badge before"  beforeLabel={<Badge label={3} type="light" priority="outline" />}/><Button label="Badge before, on top" startCorner={<Badge label={3} />} /><Button  label="Badge after, on top"  endCorner={<Badge label={3} />}  priority="outline"/><Button  label="Badge after"  afterLabel={<Badge label="new" type="warning" />}  priority="outline"/>

### Icon Buttons with a Badge

Badges play nicely with icon buttons, too:

<Button label="Icon button with badge" labelVisibility="none" priority="outline" beforeLabel={<Icon icon="warning-sign" />} startCorner={<Badge label={3} type="warning" />} /> <Button label="Icon button with badge" labelVisibility="desktop" priority="outline" beforeLabel={<Icon icon="warning-sign" />} startCorner={<Badge label={3} type="error" />} />

    <Button  label="Icon button with badge"  labelVisibility="none"  priority="outline"  beforeLabel={<Icon icon="warning-sign" />}  startCorner={<Badge label={3} type="warning" />}/><Button  label="Icon button with badge"  labelVisibility="desktop"  priority="outline"  beforeLabel={<Icon icon="warning-sign" />}  startCorner={<Badge label={3} type="error" />}/>

## States

### Disabled State

Disabled state makes the action unavailable.

<Button label="Disabled default button" disabled /> <Button label="Disabled outline button" priority="outline" disabled /> <Button label="Disabled flat button" priority="flat" disabled />

    <Button label="Disabled default button" disabled /><Button label="Disabled outline button" priority="outline" disabled /><Button label="Disabled flat button" priority="flat" disabled />

### Loading State

When an action triggers an asynchronous process on background, the button's loading state can be indicated by showing a loading icon. Buttons in loading state are automatically made disabled to prevent unwanted interaction.

<Button label="Button in loading state" loadingIcon={ <span className="d-inline-flex animation-spin-counterclockwise"> <Icon icon="loading" /> </span> } /> <Button label="Icon button in loading state" labelVisibility="none" beforeLabel={<Icon icon="pencil" />} loadingIcon={ <span className="d-inline-flex animation-spin-counterclockwise"> <Icon icon="loading" /> </span> } /> <Button label="Icon button with badge, loading" labelVisibility="desktop" beforeLabel={<Icon icon="pencil" />} loadingIcon={ <span className="d-inline-flex animation-spin-counterclockwise"> <Icon icon="loading" /> </span> } startCorner={<Badge label={3} type="error" />} /> <Button label="Icon after label, loading" afterLabel={<Icon icon="up" />} loadingIcon={ <span className="d-inline-flex animation-spin-counterclockwise"> <Icon icon="loading" /> </span> } />

    <Button  label="Button in loading state"  loadingIcon={    <span className="d-inline-flex animation-spin-counterclockwise">      <Icon icon="loading" />    </span>  }/><Button  label="Icon button in loading state"  labelVisibility="none"  beforeLabel={<Icon icon="pencil" />}  loadingIcon={    <span className="d-inline-flex animation-spin-counterclockwise">      <Icon icon="loading" />    </span>  }/><Button  label="Icon button with badge, loading"  labelVisibility="desktop"  beforeLabel={<Icon icon="pencil" />}  loadingIcon={    <span className="d-inline-flex animation-spin-counterclockwise">      <Icon icon="loading" />    </span>  }  startCorner={<Badge label={3} type="error" />}/><Button  label="Icon after label, loading"  afterLabel={<Icon icon="up" />}  loadingIcon={    <span className="d-inline-flex animation-spin-counterclockwise">      <Icon icon="loading" />    </span>  }/>

👉 Visit the Helpers section to see how the icon animation is made.

## API

In addition to the options below, you can add any custom attributes that do not interfere with the API, and they will be passed to the `button` HTML element. This is useful mainly to improve component's accessibility.

afterLabel
node
null
beforeLabel
node
null
block
bool
false
clickHandler
func
null
disabled
bool
false
endCorner
node
null
forwardedRef
Function │ { "current": "any" }
undefined
grouped
bool
false
id
string
undefined
label
string
required
labelVisibility
'all' │ 'desktop' │ 'none'
'all'
loadingIcon
node
null
priority
'default' │ 'outline' │ 'flat' │ 'link'
'default'
size
'small' │ 'medium' │ 'large'
'medium'
startCorner
node
null
type
'button' │ 'submit'
'button'
variant
'primary' │ 'secondary' │ 'success' │ 'warning' │ 'danger' │ 'dark'
'primary'

Next: ButtonGroup →