14.3.0 [Current] 13.3.1 [Past] 12.7.4 [Past]

Button

import Button from '@concur/nui-widgets/lib/Buttons/Button';

Buttons are used to communicate and trigger an action, when interacted with. If the user is being redirected to another page in or outside of the application use a link instead of a button.

Best Practices

Look to Button Patterns (Coming soon!) for best practices regarding button placement on pages, dialogs, tours, and wizards.

• Use a distinct button for every unique action a user can perform.
• Button text should:
  • Clearly communicate the action that will occur.
  • Be concise, ideally 1 to 2 words. For buttons with 2 words, button text should contain a verb and a noun (e.g. “Submit Report” or “Select Trip”) so the action is clear without additional descriptive text. In the rare event longer button text is needed, use Title Case.
• Button text should NOT:
  • Be generic or vague (e.g. “Ok”)
  • Have the same button text as other buttons on the page. Some screen readers allow users to view buttons in a list, so be as descriptive as possible.

Button Variations

There are 4 button variations that we use to differentiate meaning.

Primary and Default Buttons

Primary and Default buttons are used to convey the most important action on a page or dialog. For this reason, they are solid so that it is visually dominant when on a complex page or toolbar.

• A Primary button is only to be used to illustrate the end of a major workflow (e.g. Submit Report)
• A Default button (also called our “workhorse button”) is used to convey action throughout a majority of the experiences.

Create Buttons

A Create button is reserved for special use cases where the action is specifically to create something new. There is no muted version of this button.

Link Buttons

A Link button is typically used to convey secondary actions. While buttons links visually look like a text link, they retain the same padding, margin, and expected keyboard trigger behavior as a primary button.

Muted Buttons

Muted buttons are used in to convey low priority actions. They should never be used by themselves.

<ButtonToolbar muted>
    <Button>Default</Button>
    <Button type='primary'>Primary</Button>
    <Button type='create'>Create</Button>
    <Button type='link'>Link</Button>
</ButtonToolbar>

<ButtonToolbar muted>
    <Button muted>Default</Button>
    <Button muted type='primary'>Primary</Button>
    <Button muted type='link'>Link</Button>
</ButtonToolbar>

Disabled Buttons

Set the disabled property to change the button’s state to disabled.

<ButtonToolbar muted>
    <Button disabled>Default</Button>
    <Button disabled type='primary'>Primary</Button>
    <Button disabled type='create'>Create</Button>
</ButtonToolbar>

Disabled Buttons (Focusable)

Set the allowFocusOnDisable property to true, along with the disabled property. This allows a button to receive focus when it is disabled by keeping it in the tab cycle. This is good practice for accessibility, as it prevents the button from being hidden from assistive technologies (like screen readers). Further, if allowFocusOnDisable is true, then the disabledMessage and enabledMessage properties MUST also be set to a localized string. These messages should be such that they help users of accessible technologies understand the button’s state changes.

<ButtonToolbar muted>
    <Button
        allowFocusOnDisable
        disabled
        disabledMessage='This action is restricted to some users'
        enabledMessage='Press button to perform action' >
        Default
    </Button>
    <Button
        allowFocusOnDisable
        disabled
        disabledMessage='This action is restricted to some users'
        enabledMessage='Press button to perform action'
        type='primary'>
        Primary
    </Button>
    <Button
        allowFocusOnDisable
        disabled
        disabledMessage='This action is restricted to some users'
        enabledMessage='Press button to perform action'
        type='create'>
        Create
    </Button>
</ButtonToolbar>

Button Sizes

There are 3 supported button sizes: ‘lg’ (default), ‘md’ and ‘sm’. The large size is recommended for all NUI experiences. Use the size property to set the appropriate size.

<Button>Large</Button>

<Button size='md'>Medium</Button>

<Button size='sm'>Small</Button>

Usage

Properties

Callbacks

Accessibility

• Never nest an action (such as button or link) within another action. Screen readers are not able to place focus on nested actions, therefore are not read to users.
• CoreUI helps assistive technology read a button, by building the following into the default component:
  • Keyboard users expect to trigger a button with the enter AND space keys. This differs from links, in that they expected behavior is to trigger using only the Enter key.
  • 4.5:1 color contrast is met in active, hover, and focus states for primary buttons, button links, and muted buttons. It is not necessary to meet color contrast requirements in disabled button states.

Resources

• UX Planet, Button UX Design: Best Practices, Types, and States
• Smashing Magazine, How to Design Better Buttons
• Medium, Buttons in Design Systems
• WCAG 2.0 Guidelines for Disabled Buttons and Controls