List item
A list item is a singular representation of an object or piece of data.
Code documentation
Anatomy
The list item component is made up of 11 elements.
- Container
- Default slot
- Left slot
- Text slot
- Metadata slot
- Right slot
- Divider
- Primary text
- Secondary text
- Primary metadata
- Secondary metadata
![](/assets/img/components/list-item/list-item-anatomy.png)
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.
![](/assets/img/components/list-item/list-item-variants-default-slot.png)
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.
![](/assets/img/components/list-item/list-item-variants-divider.png)
![](/assets/img/components/list-item/list-item-variants-divider-inset.png)
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.
![](/assets/img/components/list-item/list-item-variants-default-layout-left-slot.png)
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.
![](/assets/img/components/list-item/list-item-variants-default-layout-text-slot.png)
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.
![](/assets/img/components/list-item/list-item-variants-default-layout-metadata-slot.png)
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.
![](/assets/img/components/list-item/list-item-variants-default-layout-right-slot.png)
Primary text
Primary text should be included to label what the list item represents.
![](/assets/img/components/list-item/list-item-variants-default-layout-primary-text.png)
Secondary text
Secondary text may be included to provide supplemental information related to the primary text.
![](/assets/img/components/list-item/list-item-variants-default-layout-secondary-text.png)
Primary metadata
A primary line of metadata may be included to provide additional information related to the list item.
![](/assets/img/components/list-item/list-item-variants-default-layout-primary-metadata.png)
Secondary metadata
A secondary line of metadata may be included to provide another level of information related to the list item.
![](/assets/img/components/list-item/list-item-variants-default-layout-secondary-metadata.png)
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.
![](/assets/img/components/list-item/list-item-behavior-size-auto.png)
![](/assets/img/components/list-item/list-item-behavior-size-manual.png)
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.
![](/assets/img/components/list-item/list-item-behavior-text-overflow.png)
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.
![](/assets/img/components/list-item/list-item-behavior-text-overflow-tooltip.png)
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.
![](/assets/img/components/list-item/list-item-behavior-alignment.png)
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:
- Enabled
- Focus
- Hover
- Active
- Selected
- Disabled
- Selected disabled
![List items can include enabled, focus, hover, active, selected, disabled, and selected disabled states.](/assets/img/components/list-item/list-item-behavior-states.png)
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.
![](/assets/img/components/list-item/list-item-behavior-grouping.png)