List

Vertical list container with items and sections.

Introduction

Lists present a continuous, vertical index of text or images. They are composed of related parts:

• List — wrapper for rows; renders as ul, ol, or nav via the as prop.
• ListItem — a single row with primary and optional secondary text, plus start and end slots.
• ListSection — a subheader that groups related items.

List vs Menu content: A List is part of the document flow—side navigation, settings screens, or static indexes. A Menu is a temporary floating surface anchored to a trigger; its panel often contains a List of ListItem rows using role="menuitem". Items and sections use compact inset rounded highlights. Use List for persistent layout; wrap it in Menu when choices should appear on demand and dismiss after selection.

List vs Table: A List is a vertical index of items. A Table aligns values across columns—rosters, invoices, and other tabular data. Use DataTable when that grid also needs sort, selection, filters, or pagination.

Import

import { List } from "@bridge-ui/vue/Components/List";
import { ListItem } from "@bridge-ui/vue/Components/ListItem";
import { ListSection } from "@bridge-ui/vue/Components/ListSection";

import { List } from "@bridge-ui/react/Components/List";
import { ListItem } from "@bridge-ui/react/Components/ListItem";
import { ListSection } from "@bridge-ui/react/Components/ListSection";

Basic usage

Wrap ListItem rows inside a List. Use primary and secondary for label text.

Sections

Use ListSection to add subheaders that group related items. Keep items as siblings of ListSection, not nested inside it. Add leading and trailing content to items with the start and end slots.

With the default as="li", sticky applies on the section root (with an opaque background) so the heading can stick while sibling items scroll. Use as="div" when you need sticky on the title element itself. The list (or a parent) needs a scroll container with a constrained height.

Interactive items

Set interactive on ListItem to apply hover and focus styles. Use selected to highlight the active row and customProps.interactive (React) or custom-props (Vue) to handle clicks.

Selected icon

Selected rows show a check icon by default. Customize it with selectedIcon on ListItem, or pass null to hide it. Providing slots.end replaces the selected icon.

Links

Set href to render the row as an anchor. The browser shows the URL on hover, and middle-click opens a new tab. target and rel are forwarded to that anchor. linkAs replaces that anchor and leaves the row root as as (li or div). linkProps is checked against linkAs and forwarded to it. interactive is implied, and role is omitted. A disabled item keeps the styles and drops the URL.

<List>
  <ListItem href="/inbox" primary="Inbox" />
  <ListItem href="/drafts" primary="Drafts" />
  <ListItem disabled href="/archive" primary="Archive" />
</List>

Dense

Pass dense to the List to reduce vertical spacing on child items and sections.

Related components

DataTable, Menu, Select, Sidebar, Table

Accessibility

• Set as="nav" on List when it represents site or section navigation.
• On interactive rows, set interactive so hover and focus styles apply and tabIndex={0} is added. href implies that and renders an anchor.
• When items appear inside a Menu, set role="menuitem" on ListItem (or "option" inside a listbox pattern).
• Use selected to highlight the active item; pair with visible focus styles for keyboard users.
• Set disabled on non-actionable rows so they are skipped or muted appropriately.

Anatomy

<ul> <!-- List root -->
  <li> <!-- ListSection -->
    <div> <!-- section title -->
  </li>
  <li> <!-- ListItem -->
    <div> <!-- start slot -->
    <div> <!-- content (primary + secondary) -->
    <div> <!-- end slot -->
  </li>
</ul>

Use classes on each component to style list, item, and section parts independently.

API

List

ListItem

ListSection