Stable

Button

Buttons highlight actions a user can take. There is flexibility to choose from multiple styles, sizes and configurations depending on your goal.

GitHub, opens in a new tab·Storybook, opens in a new tab·Playroom, opens in a new tab·Figma, opens in a new tab

Installation

bash

npm install @nib-components/button

Usage

jsx

import {PrimaryButton, SecondaryButton, TertiaryButton} from '@nib-components/button';

Interactive demo

jsx

<>
  <Inline space={2}>
    <PrimaryButton>Primary</PrimaryButton>
    <SecondaryButton>Secondary</SecondaryButton>
    <TertiaryButton>Tertiary</TertiaryButton>
    <DestructiveButton>Destructive</DestructiveButton>
  </Inline>
</>

<>
  <Inline space={2}>
    <PrimaryButton>Primary</PrimaryButton>
    <SecondaryButton>Secondary</SecondaryButton>
    <TertiaryButton>Tertiary</TertiaryButton>
    <DestructiveButton>Destructive</DestructiveButton>
  </Inline>
</>

Props

Prop	Type	Default	Description
`icon`	component		An icon to be displayed next to the label of the button. Must be a valid icon defined in `@nib/icons`.
`iconPlacement`	string	`end`	The placement of the icon next to the label. Must be one of `['left', 'right', 'start', 'end']`.
`size`	string or object	`'medium'`	The size of the button. Must be one of `'small'`, `'medium'`, or `'large'`. An object of breakpoints can be defined to responsively set this prop. E.g. `size={{xs: 'large', md: 'medium'}}`
`large`	boolean	`false`	To set the button size to be larger than normal. This prop will seen be deprecated. Please use `size='large'` instead.
`small`	boolean	`false`	To set the button size to be smaller than normal. This prop will seen be deprecated. Please use `size='small'` instead.
`fullWidth`	boolean or object	`false`	To set the button to span the full width of its container. An object of breakpoints can be defined to responsively set this prop. E.g. `fullWidth={{xs: true, md: false}}`
`component`	string or component	`'button'`	The underlying component of the button. Can be overriden to be an anchor tag, `Link` component, etc.
`isLoading`	boolean	`false`	To add a spinner to the button when in a loading state.
`href`	string		Add a link to the button. This will force the base component to be an `a` tag in the DOM.

Variations

Primary buttons

Use the primary button for the main call to action on a page. Primary buttons should only appear once per page.

Secondary buttons

Use secondary buttons for secondary actions on a page. Avoid too many secondary buttons on a page as it can make it hard for the user to know what to do next. Instead simplify the page if possible.

Tertiary buttons

Tertiary buttons are provided to enable a versatile and meaningful hierarchy of user actions within a particular flow or context.

A tertiary button should generally only appear grouped with one or more adjacent primary or secondary buttons, and denote actions that are a diversion from the intended or desired 'primary' interaction of its context.

Example uses for Tertiary buttons might include 'Cancel', 'Edit' or 'Learn More'. Where tertiary actions might erase, undo or halt user-led input or progress.

Destructive buttons

Use destructive buttons for cancel/delete actions on a page.

Unstyled button

UnstyledButton provides a generic HTML button element, with our standard focus ring. This is useful for wrapping icons and other inert elements to add interactive behaviours. UnstyledButton has only padding props available for configuration as mentioned below:

Prop	Type	Default	Description
`padding`, `paddingVertical`, `paddingHorizontal`, `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft`	number or object		A size from our spacing scale. Can be made responsive by passing an object of breakpoints. Value(s) must be one of `1...10`.

Buttons as links

By default our button components use the <button> element, but this is not the only option. Buttons can also be used to link users to other pages or different sites altogether, whilst retaining the desired button styling. It is important to use the right semantic element for your use case.

If clicking on the element will perform an action on the page, use <button>.
If clicking on the element will navigate the user to a new page then use <a>.

jsx

<PrimaryButton href="/health-insurance" component="a">
  Go to my account
</PrimaryButton>

<SecondaryButton onClick={handleSubmit}>
  Submit
</SecondaryButton>

Labels

Button labels express the action that will occur when the button is pressed. Labels should use sentence-style capitalisation and be short and concise - ideally no more than 3 words.

Use action words such as “Delete” and “Save” and avoid generic words such as “Yes” and “No”.

Placement

Order

When using multiple buttons, the primary button appears to the right and secondary button appears to the left. Complying with the order ensures consistency across our products.

Alignment in forms

Align buttons to the left in forms so that they align with form controls. On mobile, buttons are full-width to provide a greater touch region for user.

Button alignment on large screens:

What's your name?

What's your message?

Full-width buttons on mobile screens and tight spaces:

What's your name?

What's your message?

Icon usage

Use icons in buttons to clarify an action or draw more attention to a button. It's important to use icons in buttons sparingly and only when they help the user. Colour the icon the same as the label text.

Refer to the iconography guidelines for more details on icon usage.

Directional icon

Directional icons should only be used on the right of the button label.

Directional icons on the right of the label:

Decorative icon

In all other instances, icons should be placed to the left of the button label.

Non-directional and decorative icons on the left of the label:

Edit this page