Skip to content
Mesh icon
    DesignDevelopAnalyticsFeedback
    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>
</>

    Props

    PropTypeDefaultDescription
    iconcomponentAn icon to be displayed next to the label of the button. Must be a valid icon defined in @nib/icons.
    iconPlacementstringendThe placement of the icon next to the label. Must be one of ['left', 'right', 'start', 'end'].
    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.

    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:

    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:

    Edit this page