Skip to content
Design Tokens for Mesh have just been released!
Check out the design tokens now
Mesh icon
    DesignDevelopAnalyticsFeedback
    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}>
  <UtilityButtonTitle>Compare plans</UtilityButtonTitle>
  <UtilityButtonSubTitle>Find the right plan</UtilityButtonSubTitle>
</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

    PropTypeDefaultDescription
    iconcomponentAn 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.
    showBorderbooleantrueOption to display a border.
    selectedbooleanfalseOption to change utility button state to selected state. Adds border and Updated Title color when its true
    disabledbooleanfalseOption to identicate the disabled state of the utility button
    showActionIconbooleantrueOption to display the chevron.
    actionIconcomponentChevronRightSystemIconAn 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.
    hrefstringAdd a link to the button. Note that the component is rendered as an <a> tag in the DOM.
    onClickfunctionIf the component is required to carried out some complex functionality other than linking
    componentstring or nodeWhat to render the utility button as. Should be either a button or a. If onClick is not supplied, will defaults to a
    children (required)nodeShould include a UtilityButton.Title and optionally a UtilityButton.SubTitle

    UtilityButton.Title & UtilityButton.SubTitle

    PropTypeDefaultDescription
    truncatebooleanfalseOption to truncate the title and subtitle. Given this component is a CTA truncating the label is not recommended.
    children (required)stringThe 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="default" mode="alt">
  <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}>
        <UtilityButtonSubTitle>Find the right plan</UtilityButtonSubTitle>
        <UtilityButtonTitle>Compare plans</UtilityButtonTitle>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#">
        <UtilityButtonSubTitle>Need help?</UtilityButtonSubTitle>
        <UtilityButtonTitle>Talk to nib</UtilityButtonTitle>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#">
        <UtilityButtonSubTitle>Had treatment?</UtilityButtonSubTitle>
        <UtilityButtonTitle>Make a claim</UtilityButtonTitle>
      </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}>
        <UtilityButtonSubTitle>Find the right plan</UtilityButtonSubTitle>
        <UtilityButtonTitle>Compare plans</UtilityButtonTitle>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#" icon={ConversationGraphicIcon}>
        <UtilityButtonSubTitle>Need help?</UtilityButtonSubTitle>
        <UtilityButtonTitle>Talk to nib</UtilityButtonTitle>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#" icon={HospitalGraphicIcon}>
        <UtilityButtonSubTitle>Had treatment?</UtilityButtonSubTitle>
        <UtilityButtonTitle>Make a claim</UtilityButtonTitle>
      </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}>
        <UtilityButtonSubTitle>Find the right plan</UtilityButtonSubTitle>
        <UtilityButtonTitle>Compare plans</UtilityButtonTitle>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#" icon={ConversationGraphicIcon} actionIcon={DownloadSystemIcon}>
        <UtilityButtonSubTitle>Need help?</UtilityButtonSubTitle>
        <UtilityButtonTitle>Talk to nib</UtilityButtonTitle>
      </UtilityButton>
    </Column>
    <Column flex width="1/3">
      <UtilityButton href="#" icon={HospitalGraphicIcon} actionIcon={DownloadSystemIcon}>
        <UtilityButtonSubTitle>Had treatment?</UtilityButtonSubTitle>
        <UtilityButtonTitle>Make a claim</UtilityButtonTitle>
      </UtilityButton>
    </Column>
  </Columns>
</Box>
    Edit this page