diff --git a/docs/components/lists-tables-trees/images/list-item-actions.png b/docs/components/lists-tables-trees/images/list-item-actions.png new file mode 100644 index 0000000000..48eed01f87 Binary files /dev/null and b/docs/components/lists-tables-trees/images/list-item-actions.png differ diff --git a/docs/components/lists-tables-trees/images/list-item-anatomy.png b/docs/components/lists-tables-trees/images/list-item-anatomy.png new file mode 100644 index 0000000000..818345b642 Binary files /dev/null and b/docs/components/lists-tables-trees/images/list-item-anatomy.png differ diff --git a/docs/components/lists-tables-trees/images/list-item-indicator.png b/docs/components/lists-tables-trees/images/list-item-indicator.png new file mode 100644 index 0000000000..d0b53a9701 Binary files /dev/null and b/docs/components/lists-tables-trees/images/list-item-indicator.png differ diff --git a/docs/components/lists-tables-trees/images/list-item-metadata.png b/docs/components/lists-tables-trees/images/list-item-metadata.png new file mode 100644 index 0000000000..7519d9adf3 Binary files /dev/null and b/docs/components/lists-tables-trees/images/list-item-metadata.png differ diff --git a/docs/components/lists-tables-trees/images/list-item.png b/docs/components/lists-tables-trees/images/list-item.png new file mode 100644 index 0000000000..9cde72732d Binary files /dev/null and b/docs/components/lists-tables-trees/images/list-item.png differ diff --git a/docs/components/lists-tables-trees/list-item.md b/docs/components/lists-tables-trees/list-item.md index bf8017778e..6e7c1c1849 100644 --- a/docs/components/lists-tables-trees/list-item.md +++ b/docs/components/lists-tables-trees/list-item.md @@ -1,9 +1,77 @@ # List item +The **list item** is the building block used to compose lists. +Each item represents a single row of content and can contain a heading, +description, timestamp, metadata, indicators, and actions. + ## Usage --- +List items are designed to be flexible +and can be used in different containers depending on the context. For example: + +- With [cards](../layout-navigation/cards.md) + to stack related information together in a compact space. +- With [popovers](../status-notifications/popover.md) + to show items inside a floating container. +- With [side panels](../layout-navigation/side-panel.md), + used when the list is part of the application frame, or contextual to the current page. +- With [list groups](../lists-tables-trees/list-group.md), + to represent a single-column layout that behaves like a simplified table. + +The list item can be **read-only** or **support interactions**. + +![List item](images/list-item.png) + +### When to use + +- To construct the [notification pattern](../../patterns/notifications.md). +- To construct the chat history pattern. +- When content needs to be shown as a repeatable, scannable row. + +### Best practices + +- For complex data, use a [table](../lists-tables-trees/overview.md) instead of a list. +- Keep structure consistent across all list items in the same list. + ## Design --- +### Anatomy + +![List item anatomy](images/list-item-anatomy.png) + +> 1\. Indicator, 2. Timestamp, 3. Heading, 4. Description, 5. Primary action, 6. Metadata, 7. Quick actions + +With the exception of the heading, all items are optional. + +### Indicator + +The indicator can support icons, [circle status](../status-notifications/circle-status.md), +or an [avatar](../status-notifications/avatar.md), depending on the content needs. + +It also supports an unread state, typically used for +[notifications](../../patterns/notifications.md). + +![List item indicator](images/list-item-indicator.png) + +### Actions + +The list item supports a primary action aligned with the heading, or quick +actions placed below the description. +Actions can use any button style needed. When there are too many to show inline, condense them into an overflow menu. + +![List item actions](images/list-item-actions.png) + +### Metadata + +It is typically displayed as text-based informational attributes. +Icons may be added when they improve recognition. +[Badges](../status-notifications/badges.md) can be used for explicit states or applied labels that should stand out visually. + +The metadata does not include an intrinsic overflow behavior. +How overflow is handled should change according to the layout constraints and information priorities. + +![List item metadata](images/list-item-metadata.png) + ## Code --- ### Example