Skip to content
Stable

Button

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

Installation

bash
npm install @nib-components/button

Usage

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

Interactive demo

jsx

Props

PropTypeDefaultDescription
colorstring'light' for PrimaryButton, 'dark' for SecondaryButton and TertiaryButtonThe button color. Must be one of [light, dark, destructive]. Note: light and dark are currently only used with the nib theme.
iconcomponentAn icon to be displayed next to the label of the button. Must be a valid icon defined in @nib/icons.
iconPlacementstringrightThe placement of the icon next to the label. Must be one of ['left', 'right'].
sizestring 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'}}
largebooleanfalseTo set the button size to be larger than normal. This prop will seen be deprecated. Please use size='large' instead.
smallbooleanfalseTo set the button size to be smaller than normal. This prop will seen be deprecated. Please use size='small' instead.
fullWidthboolean or objectfalseTo 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}}
componentstring or component'button'The underlying component of the button. Can be overriden to be an anchor tag, Link component, etc.
isLoadingbooleanfalseTo add a spinner to the button when in a loading state.
hrefstringAdd 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, we recommend using the Destructive button color prop to communicate those actions.

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:

PropTypeDefaultDescription
padding, paddingVertical, paddingHorizontal, paddingTop, paddingRight, paddingBottom, paddingLeftnumber or objectA size from our spacing scale. Can be made responsive by passing an object of breakpoints. Value(s) must be one of 1...10.

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:

Full-width buttons on mobile screens and tight spaces:

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: