Reveal Button

The reveal button includes dynamic content that is updated based on its state. This state is toggled by user interaction.

This content may include text, icons, or a combination of both.

<bolt-reveal-button
    label="Button"
    labeltoggled="Button toggled"
></bolt-reveal-button>

<bolt-reveal-button
    label="Print"
    labeltoggled="Print toggled"
    iconleft="print"
></bolt-reveal-button>

<bolt-reveal-button
    label="Print"
    labeltoggled="Print toggled"
    iconright="print"
></bolt-reveal-button>

<bolt-reveal-button
    label="Document"
    labeltoggled="Document toggled"
    iconright="download"
    iconleft="document"
></bolt-reveal-button>

The left icon is always static, but the right icon can be static or dynamic.

To make iconright dynamic, provide an option for iconrighttoggled.

<bolt-reveal-button
    label="Bookmark"
    iconright="bookmark"
    iconrighttoggled="bookmark-filled"
    arialabel="Bookmark"
    arialabeltoggled="Bookmark toggled"
></bolt-reveal-button>

<bolt-reveal-button
    iconright="bookmark"
    iconrighttoggled="bookmark-filled"
    arialabel="Bookmark"
    arialabeltoggled="Bookmark toggled"
></bolt-reveal-button>

<bolt-reveal-button
    iconleft="document"
    iconright="star"
    iconrighttoggled="star-filled"
    arialabel="Favorite"
    arialabeltoggled="Favorite toggled"
></bolt-reveal-button>

<bolt-reveal-button
    label="Bookmark"
    labeltoggled="Bookmark toggled"
    iconright="bookmark"
    iconrighttoggled="bookmark-filled"
></bolt-reveal-button>

Reveal Button supports the same variations as the basic Button component.

However, it allows a restricted set of options for type, color, and size.

Reveal Button may use outline (default) or ghost button types. Solid reveal buttons are not supported.

<bolt-reveal-button
    type="outline"
    label="Outline"
    labeltoggled="Outline toggled"
></bolt-reveal-button>

<bolt-reveal-button
    label="Ghost"
    labeltoggled="Ghost toggled"
    type="ghost"
></bolt-reveal-button>

Reveal button includes the same default and theme color options as Button. Static button colors options are not supported.

<div class="bolt-background-darkBlue">
    <bolt-reveal-button
        label="On dark blue"
        labeltoggled="On dark blue toggled"
    ></bolt-reveal-button>
</div>

<bolt-reveal-button
    label="Primary"
    labeltoggled="Primary toggled"
    color="primary"
></bolt-reveal-button>
<bolt-reveal-button
    label="Secondary"
    labeltoggled="Secondary toggled"
    color="secondary"
></bolt-reveal-button>
<bolt-reveal-button
    label="Tertiary"
    labeltoggled="Tertiary toggled"
    color="tertiary"
></bolt-reveal-button>

Reveal Button supports small and medium (default) button sizes. Large reveal buttons are not supported.

<bolt-reveal-button
    label="Small"
    labeltoggled="Small toggled"
    size="sm"
></bolt-reveal-button>
<bolt-reveal-button
    label="Medium (default) toggled"
    labeltoggled="Medium toggled"
></bolt-reveal-button>

<bolt-reveal-button
    label="Reveal"
    labeltoggled="Reveal toggled"
    type="outline"
    disabled
></bolt-reveal-button>
<bolt-reveal-button
    label="Ghost"
    labeltoggled="Ghost toggled"
    type="ghost"
    disabled
></bolt-reveal-button>

For more information, see Button with Badge or standalone Badge documentation.

<bolt-reveal-button
    label="Button"
    labeltoggled="Button toggled"
    badgecount="3"
></bolt-reveal-button>

<bolt-reveal-button
  [arialabel="..."]
  [arialabeltoggled="..."]
  [arialabelledby="..."]
  [badgecolor="..."]
  [badgecount="..."]
  [color="..."]
  [datatestbutton="..."]
  [disabled]
  [iconleft="..."]
  [iconright="..."]
  [iconrighttoggled="..."]
  [label="..."]
  [labeltoggled="..."]
  [size="..."]
  [type="..."]
  ...
></bolt-reveal-button>

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

• toggled: (optional)
  • If present, applies the toggled state.
  • If absent, this communicates that the element has not been acted upon by the user, or has been un-toggled from a previously toggled state.

There are 3 sets of attributes that may be used to provide dynamic content based on the reveal button's state.

• Default state
  • label: (optional) Provides the text content for the reveal button.
  • arialabel: (optional) Sets the aria-label attribute of the underlying <button> element.
  • iconright: (optional) Icon to display on the right side of the button.
    • see [Iconography][iconography] for supported icons
• Toggled state
  • labeltoggled: (optional) Provides the text content for the reveal button in its toggled state.
  • arialabeltoggled: (optional) Sets the aria-label attribute of the underlying <button> element in its toggled state.
  • iconrighttoggled: (optional) Icon to display on the right side of the button in its toggled state.

Additionally, the <bolt-reveal-button> element supports the following parameters:

• arialabelledby: (optional) Sets the aria-labelledby attribute of the underlying <button> element.
• 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 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
• 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.
• iconleft: (optional) Icon to display on the left side of the button.
  • see [Iconography][iconography] for supported icons
• size (optional) The size of the button.
  • See "Button size" design guidelines for more info.
  • Values:
    • sm
    • md (default)
• type: (optional) Overrides the button style.
  • See "Button types" design guidelines for more info.
  • Values:
    • ghost
    • outline (default)

<bolt-reveal-button
  [iconleft="..."]
  [iconright="..."]
  [iconrighttoggled="..."]
  [arialabel="..."]
  [arialabeltoggled="..."]
  ...
></bolt-button>

• To configure the icon, you may use either iconright alone or together with iconleft.
• Icon-only elements MUST include values for both iconright and iconrighttoggled.
• You will need to make use of the arialabel and arialabeltoggled properties to configure an accessible label for each state of the reveal button.

• bolt-reveal-button-toggle: fires on click when reveal button is in un-toggled state
• bolt-reveal-button-untoggle: fires on click when reveal button is in toggled state

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

• Reveal Buttons allow for the display of 2 paired actions within one element.
• Reveal Buttons trigger actions users can take in an interface, and should never be a Link.
• Reveal buttons often show/hide or expand/collapse other elements in an interface.
• Reveal Buttons have content that changes between each expanded and collapsed state. It may be the label text, right icon, or both depending on the variation.
  • There may be instances with icon only Reveal Buttons where it is not desirable to have the Icon change, such as a “more actions” Dropdown that utilizes our “vdots” Icon. In this scenario the Icon may be static, however, the aria-label must be different between the expanded and collapsed states.
• Do not disable a Reveal 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 Outline and Ghost Button types help create a clear visual hierarchy from other elements on the page. This hierarchy guides users through the interface, ensuring they can quickly identify and complete tasks.
• There is no Solid option as Solid styling is reserved for the highest priority or most preferred action on the page. This should never be an action triggered by a Reveal Button since these Buttons represent 2 actions.
• When more than 3-4 Buttons are grouped together, lean towards the Ghost styling so the interface doesn’t become too cluttered.

• Only use Icons that clearly communicate their meaning.
• When the right Icon in a Reveal Button is dynamic, pair the icons with outlined and filled variations of the same Icon (like pencil and pencil-filled), or use other sensical pairs (like caret-up and caret-down or moon and sun Icons for dark/light mode). If no obvious pair exists, the xmark Icon may be useful if the Button open/closes another element.
• Often, the right Icon in a Reveal Button will indicate opening/closing with carets or chevrons. They may indicate from which direction an associated element may appear once the Reveal Button is clicked. While this is possible, it is not necessary and it should not interfere with common text/Icon pairs (such as “Close” for the label being paired with an xmark Icon).

• Icon-only and two-icons Reveal 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 ‘more actions’ (vdots) or ‘settings’ (gear).
  • when screen real estate is at a premium.
• Two-icons Reveal Buttons should only use carets or chevrons in the right Icon slot and is meant to indicate open/close and expand/collapse actions. The left Icon should be static.

• 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 Reveal Button hierarchy.

• When a button needs to represent up to 2 actions depending on if it is clicked or not.
• When a button triggers the appearance or disappearance of content or another screen element.

• When navigation to another page or site is desired; 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 in which the visual appearance of the control changes, but the content and accessible label does not.
• When submitting data, like a form, use Button. When validating a selection, confirming a choice or agreeing to terms and conditions, use Checkbox.

• Use sentence case for labels.
• Reveal 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 "Open" or "Close."
• Consider leading with a strong, actionable verb.
• Don’t use vague terms like “button”, "Click Here", "more", "click for details.”
• 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-reveal-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.

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