Skip to main content

List item

A list item is a singular representation of an object or piece of data.

Code documentation

Web

Anatomy

The list item component is made up of 11 elements.

  1. Container
  2. Default slot
  3. Left slot
  4. Text slot
  5. Metadata slot
  6. Right slot
  7. Divider
  8. Primary text
  9. Secondary text
  10. Primary metadata
  11. Secondary metadata
Anatomy diagram numbering 11 elements of a list item.

Variants

Default slot

The default slot is provided to allow for complete customization of the list item content area. A default layout is provided within the default slot with common slot and property configurations. Custom layouts that are placed within the default slot override the default layout and its associated properties.

A blue rectangle highlights the position of the default list item slot within a separate container.

Divider

A divider can be used between list items to create visual separation or to help group similar options. An inset property is provided to set the distance from the left edge of the divider to the container.

A series of list items include horizontal dividers in between each item. The dividers fill the entire width of each list item.
List item dividers are full-width by default.
A series of list items include horizontal dividers in between each item. The left edge of the dividers are indented to be flush with the left edge of the list item text.
Dividers can be inset along the left edge to align them to content within the list item.

Default layout

The list item includes a default layout that is designed to support common patterns and content needs with minimal customization. The layout includes four available slots that can accommodate both design system and custom components. Additionally, there are a handful of properties that allow for quick configuration of basic content layouts.

Left slot

The left slot allows you to place a relevant component at the start of the list item. There is no default content associated with this slot. The default behavior is for the slot to hug the content that is placed within it.

A blue rectangle highlights the position of the left slot in relationship to three additional slots to its right.

Text slot

The text slot is the primary location for placing content within a list item. By default, it can display primary and secondary strings of text. The text slot will expand to take up the remaining available space within the container.

A blue rectangle highlights the position of the text slot in between a slot to its left and two slots to its right.

Metadata slot

The metadata slot provides a supplementary location for placing content that supports the primary content. By default, it can display primary and secondary strings of metadata. The slot will hug the content that is placed within it.

A blue rectangle highlights the position of the metadata slot in between two slots to its left and one slot to its right.

Right slot

The right slot can be leveraged to include a relevant supplementary component. There are no defaults associated with the right slot. The slot will hug the content that is placed within it.

A blue rectangle highlights the position of the right slot in relationship to three additional slots to its left.

Primary text

Primary text should be included to label what the list item represents.

A list item includes a sample line of text within its container.

Secondary text

Secondary text may be included to provide supplemental information related to the primary text.

A list item includes a smaller line of secondary text immediately below a primary line of text.

Primary metadata

A primary line of metadata may be included to provide additional information related to the list item.

A list item includes a line of supplementary text inline with a primary line of text and right-aligned within the item container.

Secondary metadata

A secondary line of metadata may be included to provide another level of information related to the list item.

A list item includes a smaller line of supplementary text immediately below a larger line of supplementary text, both right-aligned within the item container.

Behavior

Size

List items dynamically resize to accommodate the height of their content while retaining a consistent padding within the container by default. A component token is available for users to explicitly set the list item’s height when greater control and consistency is required.

The height of a list item increases to hug multiple types of content including an avatar, primary text, primary metadata stacked on top of secondary metadata, and an icon-only button.
By default, list items vertically resize to best fit the content.
A series of three list items, each with different types of content, have the same height.
List items can be manually set to a fixed size via a component token to create consistent heights across multiple list items within a group.
Do
Use spacing tokens to manually size list items. This will ensure consistent visual relationships with other elements on the screen.

Text overflow

Within the default layout, text that is longer than the available space within the text slot will be truncated. An ellipsis (…) is appended to the end of truncated text to indicate that there is overflow.

The metadata slot—when visible—should expand to fit the content within it. The width of the metadata slot is determined by either the primary or secondary metadata—whichever is longer.

Custom layouts can establish a different overflow pattern as needed.

Primary and secondary text lines overflow their boundaries within the list item. The overflowed text is represented by an ellipsis.

When a user hovers over a piece of truncated text, a tooltip displays the full text. Placement and behavior of the tooltip follow the general guidelines for a tooltip.

A tooltip with placeholder text is positioned immediately above and horizontally centered with overflowed primary text. Blue dashed lines annotate the space between the tooltip arrow and text.

Alignment

All default content is vertically centered within the list item container. Additionally, the metadata is horizontally aligned to the right of the metadata slot. Custom layouts may use different content alignments as needed.

Two separate list items are compared top-to-bottom. The top list item includes content of varying heights and lines. The bottom item includes content of varying heights but only single line text. Both sets of content are vertically centered within their respective list item containers.

States

By default, list items do not have any states enabled. However, if a list item is made interactive, a set of default states will become present to indicate its interactive state. These include the following:

  1. Enabled
  2. Focus
  3. Hover
  4. Active
  5. Selected
  6. Disabled
  7. Selected disabled
List items can include enabled, focus, hover, active, selected, disabled, and selected disabled states.

Grouping

A list item can be used on its own if the situation warrants it. However, most list items will typically be grouped together to create a set of related data or items. When grouping list items together, use the list group component to provide the necessary structure. Consider using the list group to structure even a single list item; this will allow the freedom to easily add other list items down the road.

A series of three list items with sample content are grouped together within an implied container.