Stable

Utility Button

UtilityButton acts as inline page navigation and should always be used in groups of two or more, compared to the Button component which is designed to work as a standalone element and performs the role of a call-to-action (CTA).

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/utility-button

Note: You will also need to install the peerDependencies @nib/icons and @nib-components/theme.

Usage

jsx

import UtilityButton from '@nib/utility-button';

Interactive demo

UtilityButton is a compound component with two sub-components: UtilityButton.Title and UtilityButton.SubTitle.

jsx

<UtilityButton href="#" icon={ConversationGraphicIcon}>
  <UtilityButton.Title>Compare plans</UtilityButton.Title>
  <UtilityButton.SubTitle>Find the right plan</UtilityButton.SubTitle>
</UtilityButton>

<UtilityButton href="#" icon={ConversationGraphicIcon}>
  <UtilityButton.Title>Compare plans</UtilityButton.Title>
  <UtilityButton.SubTitle>Find the right plan</UtilityButton.SubTitle>
</UtilityButton>

Note: If you are using this component within a React Server Component (like the NextJS 13 App Router), it is suggested to import UtilityButtonTitle and UtilityButtonSubTitle individually.

jsx

import UtilityButton, {UtilityButtonTitle, UtilityButtonSubTitle} from '@nib/utility-button';
import {DentalGraphicIcon, DownloadSystemIcon} from '@nib/icons';

() => (
  <UtilityButton icon={DentalGraphicIcon} actionIcon={DownloadSystemIcon}>
    <UtilityButtonTitle>Required title</UtilityButtonTitle>
    <UtilityButtonSubTitle>Optional subtitle</UtilityButtonSubTitle>
  </UtilityButton>
);

Props

UtilityButton

Prop	Type	Default	Description
`icon`	component		An icon to be displayed on the left of the button, to communicate the context or intent of the button. Must be a graphic icon from the @nib/icons package.
`showBorder`	boolean	`true`	Option to display a border.
`selected`	boolean	`false`	Option to change utility button state to selected state. Adds border and Updated Title color when its `true`
`disabled`	boolean	`false`	Option to identicate the disabled state of the utility button
`showActionIcon`	boolean	`true`	Option to display the chevron.
`actionIcon`	component	`ChevronRightSystemIcon`	An icon to be displayed on the right of the button, to communicate the function of the `UtilityButton`. Must be a system icon from the @nib/icons package.
`href`	string		Add a link to the button. Note that the component is rendered as an `<a>` tag in the DOM.
`onClick`	function		If the component is required to carried out some complex functionality other than linking
`component`	string or node		What to render the utility button as. Should be either a `button` or `a`. If `onClick` is not supplied, will defaults to `a`
`children` (required)	node		Should include a `UtilityButton.Title` and optionally a `UtilityButton.SubTitle`

UtilityButton.Title & UtilityButton.SubTitle

Prop	Type	Default	Description
`truncate`	boolean	`false`	Option to truncate the title and subtitle. Given this component is a CTA truncating the label is not recommended.
`children` (required)	string		The text for the utility button.

Usage

Single UtilityButtons should not be used

If you require a single button, then use the Button component.

Props used on one UtilityButton should be carried through to all other UtilityButtons within the group. So for example, if an icon is included in one UtilityButton, then all UtilityButtons should include an icon. All UtilityButtons used in a group should be uniform.

Be conscious of the number of UtilityButton components you have in a group and the impact that has on available space for the title/subtitle. Within our Container component we've found that 4 - 5 is the most that can comfortably fit. If using icons, this drops down to 3 - 4. If including close to the maximum number of utility buttons be sure to set collapseBelow on the Columns component to xl or xxl.

A UtilityButton should be used on either a White or Lightest background. When the UtilityButton is placed on a White background, then border should be shown.

Multiple utility buttons

jsx

<Box padding={4} background="lightest">
  <Columns space={6} collapseBelow="md">
    <Column flex width="1/3">
      <UtilityButton href="#">
        <UtilityButton.SubTitle>Find the right plan</UtilityButton.SubTitle>
        <UtilityButton.Title>Compare plans</UtilityButton.Title>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#">
        <UtilityButton.SubTitle>Need help?</UtilityButton.SubTitle>
        <UtilityButton.Title>Talk to nib</UtilityButton.Title>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#">
        <UtilityButton.SubTitle>Had treatment?</UtilityButton.SubTitle>
        <UtilityButton.Title>Make a claim</UtilityButton.Title>
      </UtilityButton>
    </Column>
  </Columns>
</Box>

<Box padding={4} background="lightest">
  <Columns space={6} collapseBelow="md">
    <Column flex width="1/3">
      <UtilityButton href="#">
        <UtilityButton.SubTitle>Find the right plan</UtilityButton.SubTitle>
        <UtilityButton.Title>Compare plans</UtilityButton.Title>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#">
        <UtilityButton.SubTitle>Need help?</UtilityButton.SubTitle>
        <UtilityButton.Title>Talk to nib</UtilityButton.Title>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#">
        <UtilityButton.SubTitle>Had treatment?</UtilityButton.SubTitle>
        <UtilityButton.Title>Make a claim</UtilityButton.Title>
      </UtilityButton>
    </Column>
  </Columns>
</Box>

Utility buttons with selected state

jsx

<Box padding={4}>
  <Columns space={6} collapseBelow="md">
    <Column flex width="1/3">
      <UtilityButton href="#" selected={true}>
        <UtilityButton.SubTitle>Find the right plan</UtilityButton.SubTitle>
        <UtilityButton.Title>Compare plans</UtilityButton.Title>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#">
        <UtilityButton.SubTitle>Need help?</UtilityButton.SubTitle>
        <UtilityButton.Title>Talk to nib</UtilityButton.Title>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#">
        <UtilityButton.SubTitle>Had treatment?</UtilityButton.SubTitle>
        <UtilityButton.Title>Make a claim</UtilityButton.Title>
      </UtilityButton>
    </Column>
  </Columns>
</Box>

<Box padding={4}>
  <Columns space={6} collapseBelow="md">
    <Column flex width="1/3">
      <UtilityButton href="#" selected={true}>
        <UtilityButton.SubTitle>Find the right plan</UtilityButton.SubTitle>
        <UtilityButton.Title>Compare plans</UtilityButton.Title>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#">
        <UtilityButton.SubTitle>Need help?</UtilityButton.SubTitle>
        <UtilityButton.Title>Talk to nib</UtilityButton.Title>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#">
        <UtilityButton.SubTitle>Had treatment?</UtilityButton.SubTitle>
        <UtilityButton.Title>Make a claim</UtilityButton.Title>
      </UtilityButton>
    </Column>
  </Columns>
</Box>

Multiple utility buttons with icons

jsx

<Box padding={4}>
  <Columns space={6} collapseBelow="md">
    <Column flex width="1/3">
      <UtilityButton href="#" icon={HealthManagementGraphicIcon}>
        <UtilityButton.SubTitle>Find the right plan</UtilityButton.SubTitle>
        <UtilityButton.Title>Compare plans</UtilityButton.Title>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#" icon={ConversationGraphicIcon}>
        <UtilityButton.SubTitle>Need help?</UtilityButton.SubTitle>
        <UtilityButton.Title>Talk to nib</UtilityButton.Title>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#" icon={HospitalGraphicIcon}>
        <UtilityButton.SubTitle>Had treatment?</UtilityButton.SubTitle>
        <UtilityButton.Title>Make a claim</UtilityButton.Title>
      </UtilityButton>
    </Column>
  </Columns>
</Box>

<Box padding={4}>
  <Columns space={6} collapseBelow="md">
    <Column flex width="1/3">
      <UtilityButton href="#" icon={HealthManagementGraphicIcon}>
        <UtilityButton.SubTitle>Find the right plan</UtilityButton.SubTitle>
        <UtilityButton.Title>Compare plans</UtilityButton.Title>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#" icon={ConversationGraphicIcon}>
        <UtilityButton.SubTitle>Need help?</UtilityButton.SubTitle>
        <UtilityButton.Title>Talk to nib</UtilityButton.Title>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#" icon={HospitalGraphicIcon}>
        <UtilityButton.SubTitle>Had treatment?</UtilityButton.SubTitle>
        <UtilityButton.Title>Make a claim</UtilityButton.Title>
      </UtilityButton>
    </Column>
  </Columns>
</Box>

Note: The Columns and Column with the flex prop is how we achieve equal heights for the utility buttons when the content lengths differ.

Multiple utility buttons with icons and actionIcons

jsx

<Box padding={4}>
  <Columns space={6} collapseBelow="md">
    <Column flex width="1/3">
      <UtilityButton href="#" icon={HealthManagementGraphicIcon} actionIcon={DownloadSystemIcon}>
        <UtilityButton.SubTitle>Find the right plan</UtilityButton.SubTitle>
        <UtilityButton.Title>Compare plans</UtilityButton.Title>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#" icon={ConversationGraphicIcon} actionIcon={DownloadSystemIcon}>
        <UtilityButton.SubTitle>Need help?</UtilityButton.SubTitle>
        <UtilityButton.Title>Talk to nib</UtilityButton.Title>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#" icon={HospitalGraphicIcon} actionIcon={DownloadSystemIcon}>
        <UtilityButton.SubTitle>Had treatment?</UtilityButton.SubTitle>
        <UtilityButton.Title>Make a claim</UtilityButton.Title>
      </UtilityButton>
    </Column>
  </Columns>
</Box>

<Box padding={4}>
  <Columns space={6} collapseBelow="md">
    <Column flex width="1/3">
      <UtilityButton href="#" icon={HealthManagementGraphicIcon} actionIcon={DownloadSystemIcon}>
        <UtilityButton.SubTitle>Find the right plan</UtilityButton.SubTitle>
        <UtilityButton.Title>Compare plans</UtilityButton.Title>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#" icon={ConversationGraphicIcon} actionIcon={DownloadSystemIcon}>
        <UtilityButton.SubTitle>Need help?</UtilityButton.SubTitle>
        <UtilityButton.Title>Talk to nib</UtilityButton.Title>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#" icon={HospitalGraphicIcon} actionIcon={DownloadSystemIcon}>
        <UtilityButton.SubTitle>Had treatment?</UtilityButton.SubTitle>
        <UtilityButton.Title>Make a claim</UtilityButton.Title>
      </UtilityButton>
    </Column>
  </Columns>
</Box>

Button

Edit this page

Utility Button

Installation

Usage

Interactive demo

Props

UtilityButton

UtilityButton.Title & UtilityButton.SubTitle

Usage

Single UtilityButtons should not be used

Multiple utility buttons

Utility buttons with selected state

Multiple utility buttons with icons

Multiple utility buttons with icons and actionIcons

Related components