HomeGetting StartedColor SystemTypographySpacingIconographyLayoutInstallationUsageAngularBlazorReactSvelteVueThemingTypographyCustomizationCSS-Only ComponentsFormsIconsIllustrationsAccessibilityGlobal ConfigurationTailwind CSSSass LibraryForge MCP ServerDropdown OptionsFocus Indicator ClippingAll componentsButtonButton AreaChipFloating Action ButtonIcon ButtonSplit ButtonAutocompleteButton ToggleCalendarCheckboxChip FieldColor PickerDate PickerDate Range PickerFile PickerLabelRadioSelectSliderSwitchText FieldTime PickerApp BarApp LauncherDrawerMenuPaginatorSkip LinkStepperTabsView SwitcherAccordionApp LayoutCardDividerExpansion PanelScaffoldSplit ViewStackStructured CardToolbarBadgeBannerBusy IndicatorCircular ProgressDialogInline MessageLinear ProgressPage StateSkeletonToastTooltipAvatarIconKeyLabel ValueListMeterSecretTableTimelineTimestampTreeKeyboard ShortcutPopoverIntroductionColorTypographySpacingShapeBorderElevationLayeringAnimationUsageIcon LibraryBlocksRoadmapChangelogBlog

List

Lists present a vertical, scannable group of related items, from plain text rows to full navigation menus.

Home

Projects

Users

Settings

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

Do
Sort list items in a logical order that makes the content easy to scan.Use icons in the start slot consistently — either every item has one, or none does.Use navlist styling when a list is functioning as navigation, such as inside a drawer.Use a forge-divider between sections of a list.Set indented on a nested list so its items sit inset from the parent list's items.
Don't
Don't use a list for content that isn't primarily text — a card handles imagery better.Don't use a list when users need to sort or compare across three or more dimensions — use a table instead.Don't mix single-line and multi-line items in the same list without a good reason.

Basic usage

Each forge-list-item carries its own value for identifying which item was interacted with.

A basic list of plain text items.

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.

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.

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.

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";
Properties
PropertyAttributeTypeDefaultDescription
densedensebooleanfalseWhether the list has all dense items or not.
indentedindentedbooleanfalseWhether the list items within this list are indented. Default is false.
selectedValueselected-valuestring—The selected list item value(s).
twoLinetwo-linebooleanfalseWhether the list has all two-line items or not.
threeLinethree-linebooleanfalseWhether the list has all three-line items or not.
wrapwrapbooleanfalseWhether the list has all items that wrap their text or not.
noninteractivenoninteractivebooleanfalseControls whether the list items will automatically attach themselves to interactive slotted elements or not.
multicolumnmulticolumnbooleanfalseWhether the list displays items in multiple columns using a responsive grid layout.
—navlistbooleanfalseControls whether the list is styled a navigation list or not.
Slots
NameDescription
(default)The default/unnamed slot for child list items.
CSS Parts
NameDescription
::part(root)The component's root container element.
CSS Custom Properties
NameDescription
--forge-list-container-colorThe background color of the list surface.
--forge-list-spacingThe spacing between the list items.
--forge-list-column-widthThe minimum width of each column when the list is in multicolumn mode.
--forge-list-column-spacingThe 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.

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.

Loading Forge chat…