Skip to main content

List

Stacks items down the page with evenly spaced bullets, numbers, or icons.

import { List } from "@/fragments/ui";Source

Preview

<List marker="disc">
  <List.Item>First item</List.Item>
  <List.Item>Second item</List.Item>
  <List.Item>Third item</List.Item>
</List>

Installation

npx @usefragments/cli add list

Writes src/fragments/ui/components/List plus what it imports, the globals stylesheet, and .fragments/registry-lock.json, then prints the packages to add. No account, no key.

Your own registry: publish from Fragments Cloud and add --registry org/name. Connect a workspace.

Anatomy

List is a compound: import the root and reach its parts through dot notation.

  • List.Item

The default marker — reach for it when order does not matter.

<List marker="disc">
  <List.Item>First item</List.Item>
  <List.Item>Second item</List.Item>
  <List.Item>Third item</List.Item>
</List>

Examples

Numbered List

as="ol" makes the sequence real, not just visual.

<List as="ol" marker="decimal">
  <List.Item>Create your account</List.Item>
  <List.Item>Configure your settings</List.Item>
  <List.Item>Start building</List.Item>
</List>

Icon List

Each item takes its own icon — checkmarks sell a feature list.

<List marker="icon">
  <List.Item icon={<Check weight="bold" color="var(--fui-color-success)" />}>
    Unlimited projects
  </List.Item>
  <List.Item icon={<Check weight="bold" color="var(--fui-color-success)" />}>
    Priority support

No Style

No markers, wider gap — the shape for stacked nav links.

<List marker="none" gap="md">
  <List.Item>Dashboard</List.Item>
  <List.Item>Settings</List.Item>
  <List.Item>Profile</List.Item>
</List>

API

Component props
Prop
Type
Default
Description
childrenRequirednodeNot setList.Item components
asenumulolulList type
markerenumnonediscdecimalicondiscMarker drawn before each item
gapenumnonexssmmdlgxlsmSpacing between items
styleobjectNot set—

Accessibility

  • Real ul/ol markup means screen readers announce the item count
  • Icons are decorative — the text has to carry the meaning

Guidance

Use when

  • Steps, instructions, or anything with an order
  • Feature and benefit lists
  • Plain stacks of links in a sidebar

Avoid when

  • Items are pickable (use Menu or Select)
  • Items have columns (use Table)
  • Items need their own surface (use Card in a Grid)

Related

  • IconchildUse Icon as List.Item icon prop
  • StackalternativeUse Stack for non-semantic vertical lists

Next steps