List

When to useLink to "When to use"

• marker="number": instructions to follow in order, such as installing or setting something up.
• marker="check": what a plan or feature includes.
• marker="icon" or "tile": features or benefits, each with its own icon.
• marker="disc" (default) or "none": any short list of items.

Use something else when:

• the person is moving through the steps and needs to see where they are: Steps
• the items are terms with values: DescriptionList
• people tick, add or reorder the items: Checklist or SortableList
• the list is part of written content from Markdown or a CMS: Prose

UsageLink to "Usage"

import { List } from "@arshad-shah/cynosure";

<List
  marker="number"
  label="Install"
  items={[
    { label: "Add the package", description: "pnpm add @arshad-shah/cynosure" },
    { label: "Import the styles", description: "Once, at the root of the app." },
    { label: "Wrap the app in CynosureTheme" },
  ]}
/>

Items are data, as in Steps and DescriptionList: { id?, label, description?, icon?, tone? }. Give id when items are added, removed or reordered.

Numbered how-toLink to "Numbered how-to"

marker="number" renders an ol. The numbers start at start (default 1) and follow the items. Each number sits on its item's first line, also when a description follows.

Ticks, icons and tilesLink to "Ticks, icons and tiles"

check draws a tick in the success colour. icon draws each item's icon (or the list's), and tile puts it on an IconTile. tone on the list or on an item sets the marker's colour.

Gap and dividersLink to "Gap and dividers"

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

• Semantics: always a real ul or ol with li items. role="list" is set explicitly because Safari drops the list role from a list without bullets. Screen readers announce the list, how many items it has, and each item's position.
• Markers are aria-hidden. The list gives each item's position, so numbers are not read twice; ticks, icons and tiles are decoration.
• label names the list ("Install") when no heading above it does.
• Keyboard: none of its own. Nothing in a List is focusable unless you put a Link or a Button in an item.
• Right to left: markers move to the right and numbers still count down the page.
• Forced colours: discs draw in CanvasText and number circles get a CanvasText outline.

TouchLink to "Touch"

A List has nothing to press. Links or buttons you put in items keep their own hit areas.

ThemingLink to "Theming"

createTheme({ components: { list: { markerGap: "12px", gapMd: "16px" } } });

className and style are for layout only. Change the look through tokens so every product stays consistent.

RelatedLink to "Related"

Steps · IconTile · DescriptionList · Checklist · Prose