A list item is a singular representation of an object or piece of data.
The list item component is made up of 11 elements.
- Default slot
- Left slot
- Text slot
- Metadata slot
- Right slot
- Primary text
- Secondary text
- Primary metadata
- Secondary metadata
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 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.
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.
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.
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.
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.
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.
Primary text should be included to label what the list item represents.
Secondary text may be included to provide supplemental information related to the primary text.
A primary line of metadata may be included to provide additional information related to the list item.
A secondary line of metadata may be included to provide another level of information related to the list item.
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.
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.
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.
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.
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:
- Selected disabled
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.
The following component tokens are available for customizing the list item component.
Sample references including the swatch and computed values currently represent the applied light theme.
The token lists can be copied into tabular format for pasting into spreadsheets or other applications. Use these to help you document product-specific customizations or perform fine-grained filters.
The list item component uses the following components: