Button

Solid buttons visually guide users to the primary action we want them to take.

<bolt-button type="solid">Button label</bolt-button>

Outline (a.k.a., "standard") buttons are often placed in close proximity of the primary action button.

• Standard buttons should be used for actions that apply to the entire screen, such as canceling changes a user has made.

<bolt-button>Button label</bolt-button>

Ghost (a.k.a., "contextual inline") buttons should be used for triggering actions that take place on the current screen, such as removing an item from a list.

<bolt-button type="ghost">Button label</bolt-button>

<bolt-button disabled>Button label</bolt-button>

The default button color automatically adapts to both local background context and global theme.

<div class="bolt-background-darkBlue">
    <bolt-button>Button on dark blue</bolt-button>
</div>

Theme colors adjust with the global theme to preserve a semantic hierarchy of color options, while ensuring minimum contrast ratios.

They can safely be used on any theme surface color, but should not be used on static background color contexts.

<bolt-button color="primary">Primary</bolt-button>
<bolt-button color="secondary">Secondary</bolt-button>
<bolt-button color="tertiary">Tertiary</bolt-button>

Static button color options should be chosen in accordance with brand standards and contrast minimums.

<bolt-button color="darkMint">Dark mint button</bolt-button>

<bolt-button size="sm">Small button</bolt-button>
<bolt-button>Medium button</bolt-button>
<bolt-button size="lg">Large button</bolt-button>

By default, a button's width is based on its content. A full-width button takes up the entire width of its container. Additional responsive options based on grid breakpoints can be used to create full-width buttons that revert to content-width at the specified screen size and above.

<bolt-button width="full-sm">width="full-sm"</bolt-button>
<bolt-button width="full-md">width="full-md"</bolt-button>
<bolt-button width="full-lg">width="full-lg"</bolt-button>
<bolt-button width="full-xl">width="full-xl"</bolt-button>
<bolt-button width="full">width="full"</bolt-button>

Icons on buttons should be used sparingly, and should typically appear on the left side of a button.

<bolt-button iconleft="print">Print</bolt-button>
<bolt-button iconleft="search" arialabel="Search this page"></bolt-button>

Badge on buttons indicate one or more notifications are available. This should be used to indicate the button needs the user's attention. The badge will appear in the top right of the button.

<bolt-button type="solid" badgecount="3">Notification Button</bolt-button>

<bolt-button
  [arialabel="..."]
  [arialabelledby="..."]
  [badgecolor="..."]
  [badgecount="..."]
  [color="..."]
  [datatestbutton="..."]
  [disabled]
  [href="..."]
  [iconleft="..."]
  [iconright="..."]
  [size="..."]
  [submit]
  [target="..."]
  [type="..."]
  [width="..."]
  ...
>
  <!-- (optional) text label goes here -->
</bolt-button>

In addition to global HTML attributes, the <bolt-button> custom element supports the following properties.

• arialabel (optional)
  • Sets the aria-label attribute of the underlying <button> element.
  • Has no effect on "link" buttons.
• arialabelledby (optional)
  • Sets the aria-labelledby attribute of the underlying <button> element.
  • Has no effect on "link" buttons.
• badgecount (optional)
  • Configures the number count shown on the badge.
  • Values: 1 ≤ badgecount
    • A minimum value of 1 is required for the badge to appear.
    • Values below 2 are not shown on the badge.
• badgecolor (optional)
  • Sets the badge color.
  • Values:
    • dark
    • error (default)
    • light
• color (optional)
  • By default, automatically adapts to contextual theme and global theme to ensure accessible contrast.
    • When configuring button color, designers are responsible for meeting brand standards and contrast minimums.
  • Theme
    • Theme colors dynamically update with the global theme.
    • Provides a consistent hierarchy of accent colors that work in both light and dark mode.
    • Values:
      • primary
      • secondary
      • tertiary
  • Static
    • Static colors are neither thematically nor contextually aware and will remain their configured color, regardless of global theme or theming context.
    • Certain values are intended to be use on a light or dark background.
      • See "Button color" design guidelines for more info.
    • Values:
      • charcoal
      • darkMint
      • lightBlue
      • mint
      • vibrantBlue
      • white
• datatestbutton (optional)
  • Configures the [data-test] attribute on the underlying primary interactive element.
  • Default: "button"
  • See also "Test selectors"
• disabled (optional)
  • Boolean flag used to disable the button.
• href (optional)
  • Sets a URL to navigate to when the button is clicked.
  • This should only be used if the button is being used as a link.
• iconleft (optional)
  • Icon to display on the left side of the button.
  • see Iconography for supported icons
• iconright (optional)
  • Icon to display on the right side of the button.
  • see Iconography for supported icons
• size (optional)
  • The size of the button.
    • See "Button size" design guidelines for more info.
  • Values:
    • sm
    • md (default)
    • lg
• submit (optional)
  • Boolean flag to enable form submission on click.
  • If present, modifies element behavior to act like a <button type="submit">, so that it triggers <form> submission when clicked.
  • Has no effect on "link" buttons.
• target (optional)
  • Passed through to underlying <a target="..."> configuration.
  • Only affects "link" buttons.
  • Values:
    • _self (default)
    • _blank
      • Use if button link is expected to open URL from href value above in a new window.
• type (optional)
  • Overrides the button style.
    • See "Button types" design guidelines for more info.
  • Values:
    • ghost
    • outline (default)
    • solid
• width (optional)
  • Values:
    • full (always full width of parent container)
    • full-sm
    • full-md
    • full-lg
    • full-xl
  • Values with a breakpoint suffix will apply button sizing at specified screen size and smaller (similar to conventions used in the Grid component).

<bolt-button
  [iconleft="..."]
  [iconright="..."]
  ...
></bolt-button>

• To configure the icon, you may use either the iconleft or iconright attribute, but not both.
• You will need to make use of either the arialabel or arialabelledby property to configure an accessible label for the button.

• [data-test="button"]
  • Targets the primary interactive element.
  • Value is configurable via the datatestbutton property

• In Angular applications, adding the routerLink directive to a <bolt-button> results in tabindex="0" being applied, making the button receive focus twice.
  • This is a known issue with how Angular's routerlink works.
  • A workaround is to implement a (click) handler that performs a router.navigate() instead.

• Buttons provide a clear and intuitive way for users to interact with an application or website.
• Buttons are used to communicate and trigger actions users can take in an interface.
• Prioritize and emphasize the most important action in a page by making it the singular preferred Button.
• Buttons should be grouped visually, with destructive actions spatially separated from preferred actions as much as possible.
• Do not disable a Button if there's even a small chance users do not understand what to do to enable it. It is an industry best practice and Nationwide's standard to allow a user to always be able to press a Button in an interface. This allows the user to receive messaging informing them what they can do to fix an issue rather than letting them struggle to figure out what they can do to enable the Button.

• The use of Solid, Outline, and Ghost Button types help create a clear visual hierarchy, making it easier for users to understand which actions are most important. This hierarchy guides users through the interface, ensuring they can quickly identify and complete key tasks.
• Place a single Solid, preferred action Button, at the end of a button group.
• Use Outline Buttons for multiple actions of equal importance.

• Consider adding an Icon to a Button triggering actions without navigation, (e.g., "Print").
• A label should be included when using an Icon in a Button, if possible.
• Only use an Icon in a Button that clearly communicates its meaning.
• Icons in Buttons should not be used to imply directionality.

• Icon-only Buttons should be reserved for:
  • when the Icon is easily understood by an average user or has been widely standardized, such as the icons used for airport and subway signs.
  • when screen real estate is at a premium.
• Example: using a Button with a printer Icon and the word "Print" on desktop that changes to a Button with only the printer Icon on a smaller screen (e.g. phone).

• Choosing the right Button size depends on the context and the importance of the action.

• The use of primary, secondary, and tertiary colors helps in creating a visual prominence to Button hierarchy.

• When progressing or regressing a user through the steps in a flow.
• When indicating actions of high priority.
• To draw attention or highlight a preferred call to action.

• Refrain from using Buttons for in-page navigation (e.g, anchor links) or for navigation to another site; instead use Link.
• When text within a paragraph is used to navigate to another page, use a Link.
• Consider using Checkbox, Switch, or segmented controls for toggleable states.

• Use sentence case for Button labels.
• Button labels should be as short as possible and include "trigger words" that clearly explain the singular action that will take place when the Button is clicked, such as "Download" or "View."
• Consider leading with a strong, actionable verb.
• Don't use vague terms like "button", "Click Here", "more", "click for details" when labelling a Button.
• Avoid using the same label for multiple Buttons on the same page.
• Maintain consistency with terms and language.

• The arialabel attribute will override ARIA attributes of child components.
  • If arialabel is defined, ARIA attributes of children will have to manually added (e.g. badge).

• When applying the disabled attribute to <bolt-button>, the underlying <button> element is semantically disabled.
  • Disabled buttons are removed from the tab order, and cannot receive keyboard focus.
  • Disabled buttons can still receive screen reader focus, and can be accessed by screen reader navigation controls such as the arrow keys.

In Angular applications, adding a routerLink to a button results in tabindex="0" being added to it, making the button receive focus twice. This is a known issue with how Angular's routerlink works. A workaround is to implement a @click handler that performs a router.navigate() instead.

All Bolt components have gone through accessibility testing, but please keep our accessibility guidelines in mind.