List

A List provides a container for List Items, as well as other non-interactive content.

<bolt-list>
  <bolt-list-item>First item</bolt-list-item>
  <bolt-list-item>Second item</bolt-list-item>
  <bolt-list-item>Third item</bolt-list-item>
  <bolt-list-item>Fourth item</bolt-list-item>
</bolt-list>

Headings, body copy, and Dividers can be used to organize list items into sections within a single list.

<bolt-list>
  <p class="bolt-list__heading">
    Settings
  </p>
  <p class="bolt-list__copy">
    Manage your account preferences
  </p>
  <bolt-divider></bolt-divider>
  <bolt-list-item subtitle="Update your personal information">
    Profile
  </bolt-list-item>
  <bolt-list-item subtitle="Manage notification preferences">
    Notifications
  </bolt-list-item>
  <p class="bolt-list__heading">
    Account & Security
  </p>
  <bolt-divider></bolt-divider>
  <bolt-list-item subtitle="Password and authentication">
    Security
  </bolt-list-item>
  <bolt-list-item subtitle="Data and privacy settings">
    Privacy
  </bolt-list-item>
</bolt-list>

A List Item should always be used inside a List. At minimum, it must include text content for its label.

<bolt-list>
  <bolt-list-item>List item</bolt-list-item>
</bolt-list>

Supporting text may be added below the main label using its subtitle property.

<bolt-list>
  <bolt-list-item subtitle="Supporting text">List item</bolt-list-item>
</bolt-list>

List items are rendered as either a button (default) or as a link.

Use the default button configuration for list items that trigger actions without navigation.

<bolt-list>
  <bolt-list-item subtitle="Get your latest account statement">
    Download Statement
  </bolt-list-item>
</bolt-list>

Add the href attribute to render the list item as a navigable link.

<bolt-list>
  <bolt-list-item href="/account-summary" subtitle="View your account details">
    Account Summary
  </bolt-list-item>
</bolt-list>

Add a leading icon to provide visual context for the list item.

<bolt-list>
  <bolt-list-item subtitle="You have unread messages">
    <bolt-icon decorative slot="leading" name="person"></bolt-icon>
    Notifications
  </bolt-list-item>
</bolt-list>

Add a trailing icon to indicate navigation or actions. Commonly used with chevrons.

<bolt-list>
  <bolt-list-item subtitle="View and download your policies">
    Policy Documents
    <bolt-icon decorative slot="trailing" name="chevron-right"></bolt-icon>
  </bolt-list-item>
</bolt-list>

A Badge on a list item indicates one or more notifications are available.

<bolt-list>
  <bolt-list-item badgecount="3" subtitle="Items waiting for your review">
    Pending Approvals
  </bolt-list-item>
</bolt-list>

Combine the previous options to create rich, informative UI patterns.

<bolt-list>
  <bolt-list-item href="/notifications" badgecount="5">
    <bolt-icon decorative slot="leading" name="bell"></bolt-icon>
    Notifications
    <bolt-icon decorative slot="trailing" name="chevron-right"></bolt-icon>
  </bolt-list-item>
</bolt-list>

<bolt-list>
  <bolt-list-item subtitle="Get your latest account statement">
    <bolt-icon decorative slot="leading" name="download"></bolt-icon>
    Download Statement
  </bolt-list-item>
  <bolt-list-item subtitle="Send documents to others">
    <bolt-icon decorative slot="leading" name="mail"></bolt-icon>
    Share Documents
  </bolt-list-item>

<bolt-list>
  <p class="bolt-list__heading">Navigation</p>
  <bolt-divider></bolt-divider>

  <bolt-list-item href="#dashboard">
    <bolt-icon decorative slot="leading" name="grid"></bolt-icon>
    Dashboard
    <bolt-icon decorative slot="trailing" name="chevron-right"></bolt-icon>
  </bolt-list-item>

  <bolt-list-item subtitle="View reports and insights" href="#analytics">
    <bolt-icon decorative slot="leading" name="gauge"></bolt-icon>
    Analytics
    <bolt-icon decorative slot="trailing" name="chevron-right"></bolt-icon>
  </bolt-list-item>

  <bolt-list-item subtitle="Manage team members" href="#team" badgecount="2">
    <bolt-icon decorative slot="leading" name="person"></bolt-icon>
    Team
    <bolt-icon decorative slot="trailing" name="chevron-right"></bolt-icon>
  </bolt-list-item>

  <p class="bolt-list__heading">Tasks</p>
  <bolt-divider></bolt-divider>

  <bolt-list-item subtitle="Finished yesterday">
    <bolt-icon decorative slot="leading" name="checkmark-circle"></bolt-icon>
    Completed task
  </bolt-list-item>

  <bolt-list-item subtitle="Due tomorrow" badgecount="3">
    In progress
  </bolt-list-item>

  <bolt-list-item subtitle="Requires immediate attention" badgecount="1">
    <bolt-icon decorative slot="leading" name="exclamation-circle"></bolt-icon>
    Overdue task
    <bolt-icon decorative slot="trailing" name="exclamation-triangle"></bolt-icon>
  </bolt-list-item>
</bolt-list>

On this page

• Bolt List (parent)
• Bolt List Item
• Related components

<bolt-list>
  <!-- Optional: Light DOM heading, subheading, or divider -->
  <bolt-list-item>...</bolt-list-item>
  <!-- Optional: Light DOM headings, subheadings, or dividers -->
</bolt-list>

• default slot
  • Accepts the following as children:
    • <bolt-list-item> elements
    • <bolt-divider> elements
    • Light DOM content with the following classes:
      • .bolt-list__heading - Custom heading element
      • .bolt-list__copy - Custom body copy element

<bolt-list-item
  [badgecolor="..."]
  [badgecount="..."]
  [datatestlistitem="..."]
  [disabled]
  [href="..."]
  [subtitle="..."]
  ...
>
  <!-- leading slot: optional bolt-icon -->
  Label text
  <!-- trailing slot: optional bolt-icon -->
</bolt-list-item>

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

• badgecolor (optional)
  • Sets the badge color.
  • Values:
    • dark
    • error (default)
    • light
• 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.
• datatestlistitem (optional)
  • Configures the [data-test] attribute on the underlying primary interactive element.
  • Default: "list-item"
  • See also "Test selectors"
• disabled (optional)
  • Boolean flag used to disable the list item.
• href (optional)
  • Sets a URL to navigate to when the list item is clicked.
  • This should only be used if the list item is being used as a link.
  • When set, the component renders as an anchor element.
• subtitle (optional)
  • Supporting text displayed below the main label text.
  • Provides additional context or description for the list item.

• default slot

  • Accepts text content as the list item's label.

• leading slot

  • Accepts a <bolt-icon> component.
    • <bolt-icon> should be decorative.
  • Displays on the left side of the list item.

• trailing slot

  • Accepts a <bolt-icon> component.
    • <bolt-icon> should be decorative.
  • Displays on the right side of the list item.

• click
  • Standard DOM click event emitted when the list item is clicked.
  • Can be prevented by calling preventDefault() on the event.

• [data-test="list-item"]
  • Targets the primary interactive element.
  • Value is configurable via the datatestlistitem property.

• Divider - Visual separator for grouping content
• Icon - Representations of objects or functions
• Badge - Indicates the presence of one or more notifications

• Lists provide layout patterns for stacked, related content. They can contain List items, Dividers, or non-interactive text.
• Lists commonly exist in Dialogs, but can also exist in other containers like panels and drawers or as standalone content on a page.
• Elements should remain in vertical alignment between List items.
  • If one item in a List has a leading element and others do not, the label and supporting text within items without a leading element should be indented.
  • Similarly in the trailing elements, if multiple items have Badges, but one had a trailing Icon and another does not, the Badges should remain vertically aligned.
  • Headings and dividers should not be indented. Typically, headings should remain left aligned, and Dividers should fill the available width.

• Lists may contain several different types of elements, but most commonly a List item.
• Non-interactive headings, body copy or Dividers can also be used.
  • It is recommended to use these sparingly.
  • Avoid two headings appearing consecutively and two dividers appearing consecutively.

• Use when it is desired to present a specific set of options in specific areas of a page, instead of in the main navigation.
• Use when there are multiple actions or paths (at least 2-3 is advised) a user could take on a page and they have some relation to one another. For example, a profile dropdown could contain a List with links to messages, settings, and a log out button.

• Avoid using a List when the options are the main way users navigate or complete primary tasks for the page.

• Keep labels concise and direct by using action-oriented, easily understood language.

• A List item provides a consistent layout and appearance for semantic links and buttons in a List.
• List items should live inside a List component.
• List items should be interactive and only have one click target inside them.
  • The whole element should be clickable.
• The structure of the List item includes:
  • Leading element: area for leading Icon
  • Body: area for List item label (required) and optional supporting text
  • Trailing elements: area for a Badge and a separate area for a trailing Icon
• Elements should remain in vertical alignment between List items.
  • If one item in a List has a leading element and others do not, the label and supporting text within items without a leading element should be indented.
  • Similarly in the trailing elements, if multiple items have Badges, but one had a trailing Icon and another does not, the Badges should remain vertically aligned.

• When creating a List and an interactive element is needed.

• Avoid using List items outside of a List.

• Keep labels concise and direct by using action-oriented, easily understood language.
• Labels should use sentence case unless there is a business line precedent.
• Avoid using ellipses if content gets cut off due to container size limitations. It is preferred to shorten the text or allow the text to wrap to multiple lines.

• Always use list items in a list. The <bolt-list> component provides a semantic container for list items.
• Include headings and body copy to provide clear context for the list's purpose when appropriate.
• List items automatically render as either a <button> or <a> element depending on whether an href is provided.
  • Use href for navigation actions (moving to a new page or section).
  • Use button mode (without href) for in-page actions (filtering, selecting, opening dialogs, etc.).
• Ensure list items have clear, descriptive labels to help users understand their purpose.
• Avoid nesting interactive elements inside list items, as this can create accessibility issues.

• The <bolt-list> component renders list items in a semantically appropriate container.
• When using <bolt-list-item> components within the list, ensure they are configured as either buttons or links depending on their function.
• Screen readers will announce the list structure and navigate through items appropriately.

• Keep headings and list item labels concise and descriptive.
• Avoid relying solely on visual cues like icons or colors to convey meaning.
• When using dividers to separate content, ensure the grouping is also conveyed through headings or logical organization.

• When no href is provided, the component renders as a semantic <button> element.
  • Buttons are included in the tab order and can be activated with keyboard (Space or Enter keys).
  • Buttons receive visual focus indicators by default.
  • Buttons emit a custom click event that can be prevented by calling preventDefault().

• When an href is provided, the component renders as a semantic <a> element.
  • Links are included in the tab order and can be activated with keyboard (Enter key).
  • Links receive visual focus indicators by default.
  • Links support standard browser navigation features (right-click, open in new tab, etc.).

• Tab - Moves focus to the list item
• Shift+Tab - Moves focus to the previous focusable element
• Space - Activates the list item (button mode only)
• Enter - Activates the list item (both button and link modes)

• The slotted text is announced as the accessible name of the button or link.
• The optional subtitle text is announced as additional descriptive content.
• Badge counts are announced by screen readers when using the badgecount attribute.
• A slotted Icon's title will be announced by screen readers, unless it is marked as decorative.

None at this time.

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