# List Lists organize related content into rows that are easy to scan. ## Usage Lists are designed to be flexible and can be used with different styles depending on the context. They can be **read-only** or **support interactions**. - Use a **ghost** list when the items should blend into the surrounding content and stay lightweight. - Use a **divider** list when the items need separation but the list should still feel quiet and compact. - Use a **filled** list when the list should stand out as a distinct section or card. - Use an **outline** list when you want a clear container around the items without the stronger weight of a filled surface. ![List](images/list.png) ### When to use - 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 items** are flexible building blocks that can support differentcontent types. The following example shows the most common layout. ![List item anatomy](images/list-item-anatomy.png) > 1\. Indicator, 2. Timestamp, 3. Heading, 4. Description, 5. Primary action, 6. Metadata, 7. Quick actions The anatomy above is a default example, but every slot can be swapped for a different control depending on the interaction the list needs to support. For example: - Add checkboxes to support multi-select and bulk actions, or radio buttons for single-select. - Add a drag handle to support manual reordering. - Replace the heading text with an input to support inline editing. ![List item content](images/list-item-content.png) ### 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. ![List item indicator](images/list-item-indicator.png) ### Actions The list item supports two distinct action slots: The primary action is most directly tied to the item's purpose. Works best as a single action, though it can hold more. ![List item action](images/list-item-primary-action.png) Quick actions are usually for operations performed on the item itself, such as pinning, archiving, sharing, or deleting. Works best when several need to be exposed at once. ![List item quick actions](images/list-item-quick-actions.png) Use a menu when there are more than three or four. ### 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 ### List styles Use `.list` for a ghost list, `.list.list-divider` to separate items with dividers, `.list.list-filled` to place items on a filled surface, or `.list.list-outline` to place each item in an outlined container. ```html ``` #### Example Component: ```typescript /** * Copyright (c) Siemens 2016 - 2026 * SPDX-License-Identifier: MIT */ import { Component, inject } from '@angular/core'; import { elementAhuPlant, elementLightOn, elementFireSensor, elementElevator, elementOptionsVertical } from '@siemens/element-icons'; import { addIcons, SiIconComponent } from '@siemens/element-ng/icon'; import { LOG_EVENT } from '@siemens/live-preview'; @Component({ selector: 'app-sample', imports: [SiIconComponent], templateUrl: './list-variants.html', host: { class: 'p-5' } }) export class SampleComponent { logEvent = inject(LOG_EVENT); icons = addIcons({ elementAhuPlant, elementLightOn, elementFireSensor, elementElevator, elementOptionsVertical }); readonly items = [ { icon: this.icons.elementAhuPlant, title: 'HVAC Zone Controller Lobby' }, { icon: this.icons.elementLightOn, title: 'Lighting Controller Parking Garage' }, { icon: this.icons.elementFireSensor, title: 'Fire Alarm Panel East Wing' }, { icon: this.icons.elementElevator, title: 'Elevator Motor Room Sensor' } ]; } ``` Template: ```html

Ghost

    @for (item of items; track item.title) {
  • {{ item.title }}
    • }

With dividers

    @for (item of items; track item.title) {
  • {{ item.title }}
    • }

Filled

    @for (item of items; track item.title) {
    • }

Outline

    @for (item of items; track item.title) {
    • }
``` ### List item configurations #### Example Component: ```typescript /** * Copyright (c) Siemens 2016 - 2026 * SPDX-License-Identifier: MIT */ import { CdkMenuTrigger } from '@angular/cdk/menu'; import { Component, inject } from '@angular/core'; import { elementArchive, elementCheckboxChecked, elementDelete, elementDocument, elementAhuPlant, elementSpecialObject } from '@siemens/element-icons'; import { SiAvatarComponent } from '@siemens/element-ng/avatar'; import { SiCircleStatusComponent } from '@siemens/element-ng/circle-status'; import { addIcons, SiIconComponent, SiStatusIconComponent } from '@siemens/element-ng/icon'; import { type MenuItem, SiMenuFactoryComponent } from '@siemens/element-ng/menu'; import { LOG_EVENT } from '@siemens/live-preview'; @Component({ selector: 'app-sample', imports: [ SiIconComponent, SiMenuFactoryComponent, SiAvatarComponent, SiCircleStatusComponent, SiStatusIconComponent, CdkMenuTrigger ], templateUrl: './list-item.html', host: { class: 'p-5' } }) export class SampleComponent { logEvent = inject(LOG_EVENT); icons = addIcons({ elementArchive, elementCheckboxChecked, elementDelete, elementDocument, elementAhuPlant, elementSpecialObject }); items: MenuItem[] = [ { type: 'action', label: 'View details', action: () => this.logEvent('View details') }, { type: 'action', label: 'Assign technician', action: () => this.logEvent('Assign technician') }, { type: 'action', label: 'Export log', action: () => this.logEvent('Export log') } ]; } ``` Template: ```html ``` ### Action list items If the entire item is clickable, wrap the content inside a `
    • ``` ### Metadata Use `.list-item-metadata` to display supplementary contextual information below the description, such as workspace names, contributor counts, document links, or status badges. Items within the metadata row can be separated with `.list-item-metadata-divider`, which renders a small dot separator. ### Unread state Use the `.unread` class on `.list-item-title` to indicate unread items with a bold title and a dot indicator. #### Example Component: ```typescript /** * Copyright (c) Siemens 2016 - 2026 * SPDX-License-Identifier: MIT */ import { Component, signal } from '@angular/core'; import { FormsModule } from '@angular/forms'; import { SiFormItemComponent } from '@siemens/element-ng/form'; @Component({ selector: 'app-sample', imports: [FormsModule, SiFormItemComponent], templateUrl: './list-item-unread.html', host: { class: 'p-5' } }) export class SampleComponent { readonly unread = signal(true); } ``` Template: ```html
    Interactive Demo Controls
    ``` ### Migrating from the list group The Bootstrap based list group (`.list-group`) is deprecated in favor of the list. The list group is only a bordered container and has no notion of the list anatomy, so migrating means restructuring the markup, it is not a plain class rename. | Deprecated | Replacement | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `.list-group` | `.list`, optionally with `.list-divider`, `.list-filled` or `.list-outline` | | `.list-group-item` | `.list-item`, wrap the content in the slot classes such as `.list-item-title` and `.list-item-description` | | `.list-group-item-action` | `.list-item.list-item-action` on a `