Skip to main content
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 8 elements.

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

Variants

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.

Left slot

The left slot allows you to place relevant content 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 rectangle highlights the position of the left slot in relationship to two additional slots to its right.

Default slot

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

Two list items are displayed. In the first list item, a rectangle highlights the position of the default slot in between a slot to its left and a slot to its right. The second list item includes the four property-based content elements displayed within the position of the default slot.

Right slot

The right slot can be leveraged to include relevant content at the end of the list item. There are no defaults associated with the right slot. The slot will hug the content that is placed within it.

A rectangle highlights the position of the right slot in relationship to two 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.

The secondary metadata can be displayed independent of the primary metadata.

A list item includes a smaller line of supplementary text inline with a primary line of text and 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 each of three list items increases to hug multiple types of content including an avatar, primary text, primary text stacked on top of secondary 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

Text that is longer than than the available space within the main content container will wrap to the next line.

The metadata container expands to fit the content within it. The width of the metadata container is determined by either the primary or secondary metadata—whichever is longer.

Primary and secondary text lines wrap within the list item, constrained by the block of metadata content and the content in the left and right slots.

Custom layouts can establish a different overflow pattern as needed.

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 list items include content of varying heights and lines. The content is vertically centered within the list item container.

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.

Figma

Frame constraints

Figma currently applies fixed widths of placeholders to the fixed-width components that are swapped in. This means certain fixed-width components such as switch, radio, and checkbox won’t have much room to properly display a label or secondary text. To work around this quirk, simply set the horizontal resizing to hug the relevant layers.