List
Lists present a vertical, scannable group of related items, from plain text rows to full navigation menus.
Overview
Lists display groups of related items in a vertical arrangement, making content easy to scan and act upon. They should be organized in logical order (alphabetical, chronological, or by priority) to help users quickly find what they need. List items can include text, icons, actions, and selection controls, with spacing achieved through dividers or white space for visual separation and improved readability.
Usage
forge-list groups forge-list-item children through dense, indented, twoLine/threeLine, wrap, multicolumn, and navlist, while each item carries its own selected, value, and start/end slots. The start slot holds a leading icon or avatar; the end slot holds trailing content like icons, badges, or actions. Use a list for related, primarily textual items; for content with three or more sortable dimensions, use a table instead, and for content built around imagery or non-homogeneous data, use a card instead.
Rules
forge-divider between sections of a list.indented on a nested list so its items sit inset from the parent list's items.Basic usage
Each forge-list-item carries its own value for identifying which item was interacted with.
A basic list of plain text items.
<forge-list class="max-w-[500px]">
<forge-list-item value="list-item-1">
<span>
List item 1
</span>
</forge-list-item>
<forge-list-item value="list-item-2">
<span>
List item 2
</span>
</forge-list-item>
<forge-list-item value="list-item-3">
<span>
List item 3
</span>
</forge-list-item>
<forge-list-item value="list-item-4">
<span>
List item 4
</span>
</forge-list-item>
</forge-list>Interactive items
Slot a real <button> or <a> inside a list item and it automatically picks up hover and focus states.
List items wrapping interactive buttons.
<forge-list class="max-w-[500px]">
<forge-list-item value="list-item-1">
<button type="button">
List item 1
</button>
</forge-list-item>
<forge-list-item value="list-item-2">
<button type="button">
List item 2
</button>
</forge-list-item>
<forge-list-item value="list-item-3">
<button type="button">
List item 3
</button>
</forge-list-item>
<forge-list-item value="list-item-4">
<button type="button">
List item 4
</button>
</forge-list-item>
</forge-list>As navigation
Set navlist on the list and pair each item with a leading icon and an anchor — the pattern used inside a drawer. Mark the active item with its own selected attribute, or set selectedValue on the list to match an item’s value — either way, also add aria-current="page" to that item, since that’s the attribute screen readers actually rely on to announce it as the current page.
A navigation-styled list inside a drawer.
<forge-drawer open direction="left">
<aside>
<forge-list navlist class="max-w-[500px]">
<forge-list-item>
<forge-icon slot="start" name="home">
</forge-icon>
<a href="javascript: void(0);">
Home
</a>
</forge-list-item>
<forge-list-item>
<forge-icon slot="start" name="inbox">
</forge-icon>
<a href="javascript: void(0);">
Inbox
</a>
</forge-list-item>
<forge-list-item>
<forge-icon slot="start" name="star">
</forge-icon>
<a href="javascript: void(0);">
Starred
</a>
</forge-list-item>
<forge-list-item>
<forge-icon slot="start" name="settings">
</forge-icon>
<a href="javascript: void(0);">
Settings
</a>
</forge-list-item>
</forge-list>
</aside>
</forge-drawer>
<script type="module">
import { IconRegistry } from "@tylertech/forge/icon";
import { tylIconHome, tylIconInbox, tylIconSettings, tylIconStar } from "@tylertech/tyler-icons";
IconRegistry.define([tylIconHome, tylIconInbox, tylIconSettings, tylIconStar]);
</script>Expandable items
Nest an expansion panel inside a list item to show or hide additional content or a sub-list. Put that content in an element with slot="additional-content" — that’s required for it to be visually and structurally separated from the item’s main content, and announced correctly by screen readers.
<forge-list-item>
Item with more detail
<forge-expansion-panel slot="additional-content">
<p>Additional detail shown when expanded.</p>
</forge-expansion-panel>
</forge-list-item>
Indented
Set indented to indent all of a list’s items. Use it for a nested list, such as a sub-list inside an expandable item, so the hierarchy reads at a glance.
<forge-list indented>
<forge-list-item>Child item</forge-list-item>
<forge-list-item>Another child item</forge-list-item>
</forge-list>
Multicolumn
Set multicolumn to lay out items in a responsive grid instead of a single column, for a longer list that doesn’t need to be scanned top-to-bottom.
A longer list laid out in a responsive multicolumn grid.
<forge-list multicolumn>
<forge-list-item>
<forge-icon slot="start" name="folder">
</forge-icon>
<button type="button">
List Item 1
</button>
</forge-list-item>
<forge-list-item>
<forge-icon slot="start" name="folder">
</forge-icon>
<button type="button">
List Item 2
</button>
</forge-list-item>
<forge-list-item>
<forge-icon slot="start" name="folder">
</forge-icon>
<button type="button">
List Item 3
</button>
</forge-list-item>
<forge-list-item>
<forge-icon slot="start" name="folder">
</forge-icon>
<button type="button">
List Item 4
</button>
</forge-list-item>
<forge-list-item>
<forge-icon slot="start" name="folder">
</forge-icon>
<button type="button">
List Item 5
</button>
</forge-list-item>
<forge-list-item>
<forge-icon slot="start" name="folder">
</forge-icon>
<button type="button">
List Item 6
</button>
</forge-list-item>
<forge-list-item>
<forge-icon slot="start" name="folder">
</forge-icon>
<button type="button">
List Item 7
</button>
</forge-list-item>
<forge-list-item>
<forge-icon slot="start" name="folder">
</forge-icon>
<button type="button">
List Item 8
</button>
</forge-list-item>
<forge-list-item>
<forge-icon slot="start" name="folder">
</forge-icon>
<button type="button">
List Item 9
</button>
</forge-list-item>
</forge-list>
<script type="module">
import { IconRegistry } from "@tylertech/forge/icon";
import { tylIconFolder } from "@tylertech/tyler-icons";
IconRegistry.define([tylIconFolder]);
</script>Lists are vertically oriented groups of related content that allow users to select or view one or more items from a set.
import "@tylertech/forge/list";| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
dense | dense | boolean | false | Whether the list has all dense items or not. |
indented | indented | boolean | false | Whether the list items within this list are indented. Default is false. |
selectedValue | selected-value | string | — | The selected list item value(s). |
twoLine | two-line | boolean | false | Whether the list has all two-line items or not. |
threeLine | three-line | boolean | false | Whether the list has all three-line items or not. |
wrap | wrap | boolean | false | Whether the list has all items that wrap their text or not. |
noninteractive | noninteractive | boolean | false | Controls whether the list items will automatically attach themselves to interactive slotted elements or not. |
multicolumn | multicolumn | boolean | false | Whether the list displays items in multiple columns using a responsive grid layout. |
| — | navlist | boolean | false | Controls whether the list is styled a navigation list or not. |
| Name | Description |
|---|---|
(default) | The default/unnamed slot for child list items. |
| Name | Description |
|---|---|
::part(root) | The component's root container element. |
| Name | Description |
|---|---|
--forge-list-container-color | The background color of the list surface. |
--forge-list-spacing | The spacing between the list items. |
--forge-list-column-width | The minimum width of each column when the list is in multicolumn mode. |
--forge-list-column-spacing | The spacing between columns when the list is in multicolumn mode. |
Keyboard interaction
- Every active list item should be reachable by keyboard navigation, with a distinct visual style showing which one is currently focused.
- Pressing Space or Enter on a focused list item should activate it the same way a mouse click would.
- If a list item contains a checkbox or radio, make sure it can still be focused and toggled by keyboard.
Roles
Give each list item a role attribute that describes what it’s being used for, so screen readers can announce it correctly.
Navigation lists
When a navlist is used for navigation, add aria-current="page" to the currently active item in addition to its visual selected state — that’s the attribute screen readers actually rely on to know it’s the current page.
Expandable items
When nesting an expansion panel inside a list item, put its content in an element with slot="additional-content". That’s required for the content to be visually and structurally separated from the main list item content, and to be announced correctly by screen readers.
Interactive elements in a list item
Placing more than one interactive element inside an interactive list item (like a checkbox alongside the item’s main content) needs the same forge-ignore handling described in nested interactive elements — by default, only the list item itself receives pointer events.