Skip to content

List

Semantic ordered, unordered, and description lists with token-driven spacing, marker style, and marker colour.

stable
since v0.1.0
4.11 kB
typography
structure

Preview

tsx

import { List, ListItem } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <List>
      <ListItem>One</ListItem>
      <ListItem>Two</ListItem>
      <ListItem>Three</ListItem>
    </List>
  );
}

Ordered

OrderedList renders a <ol> and defaults to a decimal marker. It accepts the native start, reversed, and type props so numbered procedures stay flexible.

Preview

tsx

import { ListItem, OrderedList } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <OrderedList>
      <ListItem>Install the package</ListItem>
      <ListItem>Wrap your app in the provider</ListItem>
      <ListItem>Import and render a component</ListItem>
    </OrderedList>
  );
}

Markers

marker accepts disc, circle, square, none for unordered lists and decimal, lower-alpha, upper-alpha for ordered lists. Use markerColor to tint the bullet from any colour token.

Preview

tsx

import { List, ListItem, OrderedList } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div
      style={{ display: 'grid', gap: '1.5rem', gridTemplateColumns: 'repeat(2, minmax(0, 1fr))' }}
    >
      <List marker="disc">
        <ListItem>Disc</ListItem>
        <ListItem>Marker</ListItem>
      </List>
      <List marker="circle">
        <ListItem>Circle</ListItem>
        <ListItem>Marker</ListItem>
      </List>
      <List marker="square">
        <ListItem>Square</ListItem>
        <ListItem>Marker</ListItem>
      </List>
      <List marker="none">
        <ListItem>No marker</ListItem>
        <ListItem>Still a list</ListItem>
      </List>
      <OrderedList marker="lower-alpha">
        <ListItem>Lower alpha</ListItem>
        <ListItem>Marker</ListItem>
      </OrderedList>
      <OrderedList marker="upper-alpha">
        <ListItem>Upper alpha</ListItem>
        <ListItem>Marker</ListItem>
      </OrderedList>
    </div>
  );
}

Spacing

spacing accepts any space token and controls the gap between items. The default is 2 — bump it up for breathing room in long lists.

Preview

tsx

import { List, ListItem } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div
      style={{ display: 'grid', gap: '1.5rem', gridTemplateColumns: 'repeat(3, minmax(0, 1fr))' }}
    >
      <List spacing="1">
        <ListItem>Tight</ListItem>
        <ListItem>Spacing</ListItem>
        <ListItem>One</ListItem>
      </List>
      <List spacing="3">
        <ListItem>Default</ListItem>
        <ListItem>ish</ListItem>
        <ListItem>Spacing</ListItem>
      </List>
      <List spacing="6">
        <ListItem>Loose</ListItem>
        <ListItem>Breathing</ListItem>
        <ListItem>Room</ListItem>
      </List>
    </div>
  );
}

Nested

Nest a List (or OrderedList) inside a ListItem to express sub-points; spacing and markers can differ per level.

Preview

tsx

import { List, ListItem } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <List>
      <ListItem>Typography</ListItem>
      <ListItem>
        Layout
        <List marker="circle">
          <ListItem>Box</ListItem>
          <ListItem>Stack</ListItem>
          <ListItem>Grid</ListItem>
        </List>
      </ListItem>
      <ListItem>Forms</ListItem>
    </List>
  );
}

Description list

DescriptionList pairs DescriptionTerm with DescriptionDetails for key-value content such as glossaries and metadata tables.

Preview

tsx

import { DescriptionDetails, DescriptionList, DescriptionTerm } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <DescriptionList>
      <DescriptionTerm>Framework</DescriptionTerm>
      <DescriptionDetails>React 18+</DescriptionDetails>
      <DescriptionTerm>Styling</DescriptionTerm>
      <DescriptionDetails>vanilla-extract with design tokens</DescriptionDetails>
      <DescriptionTerm>Bundling</DescriptionTerm>
      <DescriptionDetails>Tree-shakeable ESM</DescriptionDetails>
    </DescriptionList>
  );
}

API

PropTypeDefaultDescription

spacing

Responsive<SpaceToken>

"2"

Vertical gap between list items, from the spacing scale.

marker

Responsive<ListMarker>

—

`list-style-type`. `List` defaults to `disc`; `OrderedList` defaults to `decimal`. Use `none` to hide markers entirely.

markerColor

"bg.canvas"|"bg.surface"|"bg.subtle"|"bg.muted"|"bg.raised"|"bg.overlay"|"bg.inverse"|"fg.subtle"|"fg.muted"|"fg.inverse"|"fg.default"|"fg.disabled"|"fg.onAccent"|"border.subtle"|"border.default"|"border.disabled"|"border.strong"|"border.focus"|"accent.solid"|"accent.solidHover"|"accent.solidActive"|"accent.soft"|"accent.softHover"|"accent.softActive"|"accent.ring"|"accent.onSolid"|"feedback.success.foreground"|"feedback.success.border"|"feedback.success.solid"|"feedback.success.soft"|"feedback.success.onSolid"|"feedback.danger.foreground"|"feedback.danger.border"|"feedback.danger.solid"|"feedback.danger.soft"|"feedback.danger.onSolid"|"feedback.warning.foreground"|"feedback.warning.border"|"feedback.warning.solid"|"feedback.warning.soft"|"feedback.warning.onSolid"|"feedback.info.foreground"|"feedback.info.border"|"feedback.info.solid"|"feedback.info.soft"|"feedback.info.onSolid"

—

Colour for the marker glyph (`::marker`). Independent of text colour.

className

string

—

Additional class names appended after Cynosure's base classes.

style

CSSProperties

—

Inline style overrides merged last.

children

ReactNode

—

List items.

padding

Responsive<SpaceToken>

—

Padding on all four sides. Token from the spacing scale.

paddingX

Responsive<SpaceToken>

—

Horizontal padding (left + right). Overrides `padding` on the X axis.

paddingY

Responsive<SpaceToken>

—

Vertical padding (top + bottom). Overrides `padding` on the Y axis.

paddingTop

Responsive<SpaceToken>

—

Padding on the top edge. Beats `padding` / `paddingY`.

paddingRight

Responsive<SpaceToken>

—

Padding on the right (inline-end in RTL) edge.

paddingBottom

Responsive<SpaceToken>

—

Padding on the bottom edge.

paddingLeft

Responsive<SpaceToken>

—

Padding on the left (inline-start in RTL) edge.

margin

Responsive<MarginValue>

—

Margin on all four sides. Accepts the spacing scale or `"auto"`.

marginX

Responsive<MarginValue>

—

Horizontal margin (left + right). Use `"auto"` to centre.

marginY

Responsive<MarginValue>

—

Vertical margin (top + bottom).

marginTop

Responsive<MarginValue>

—

Margin on the top edge.

marginRight

Responsive<MarginValue>

—

Margin on the right edge.

marginBottom

Responsive<MarginValue>

—

Margin on the bottom edge.

marginLeft

Responsive<MarginValue>

—

Margin on the left edge.

width

Responsive<SizeValue>

—

Element width. Accepts a `SpaceToken`, `LengthValue`, or named alias.

height

Responsive<SizeValue>

—

Element height. Accepts a `SpaceToken`, `LengthValue`, or named alias.

minWidth

Responsive<SizeValue>

—

Minimum width — useful for preventing flex children from collapsing.

maxWidth

Responsive<SizeValue>

—

Maximum width — `"prose"` caps to a comfortable reading measure.

minHeight

Responsive<SizeValue>

—

Minimum height.

maxHeight

Responsive<SizeValue>

—

Maximum height.

background

Responsive<ColorToken>

—

Background colour. Use a `ColorToken` like `"bg.surface"` for theme awareness.

color

Responsive<ColorToken>

—

Text colour. Inherits unless set.

borderColor

Responsive<ColorToken>

—

Border colour. Pair with `borderWidth` to make the border visible.

borderWidth

Responsive<BorderWidth>

—

Border thickness in scale steps.

borderStyle

Responsive<BorderStyle>

—

Border line style.

borderRadius

Responsive<RadiusToken>

—

Corner rounding token.

boxShadow

Responsive<ShadowToken>

—

Drop-shadow token from the elevation scale.

opacity

Responsive<number | `${number}`>

—

Opacity 0–1. Use sparingly — prefer surface tokens over translucency.

overflow

Responsive<Overflow>

—

How content that exceeds the box is handled.

overflowX

Responsive<Overflow>

—

Horizontal-axis overflow control. Overrides `overflow` for the X axis.

overflowY

Responsive<Overflow>

—

Vertical-axis overflow control.

display

Responsive<Display>

—

CSS `display` value. `"contents"` removes the element's box from layout.

position

Responsive<Position>

—

CSS `position`. Pair with `top`/`right`/`bottom`/`left` for placement.

top

Responsive<InsetValue>

—

Top inset (when positioned). Accepts a `SpaceToken`, `"auto"`, `"0"`, or `LengthValue`.

right

Responsive<InsetValue>

—

Right inset (when positioned).

bottom

Responsive<InsetValue>

—

Bottom inset (when positioned).

left

Responsive<InsetValue>

—

Left inset (when positioned).

zIndex

Responsive<ZIndexToken>

—

Stacking-context layer token (`"modal"`, `"tooltip"`, …).

gridColumn

Responsive<string>

—

Grid-column shorthand (e.g. `"1 / 3"`, `"span 2"`).

gridRow

Responsive<string>

—

Grid-row shorthand.

gridArea

Responsive<string>

—

Named grid area.

flex

Responsive<"1" | "none" | "auto" | "initial" | (string & {})>

—

Shorthand: `1 | auto | none | initial | <css>`. Resolves to `flex` on the child.

flexGrow

Responsive<number | `${number}`>

—

Grow factor inside a flex container.

flexShrink

Responsive<number | `${number}`>

—

Shrink factor inside a flex container.

flexBasis

Responsive<"content" | SizeValue>

—

Initial main-axis size before grow/shrink.

alignSelf

Responsive<AlignSelf>

—

Override `align-items` for a single child.

justifySelf

Responsive<JustifySelf>

—

Override `justify-items` for a single child (grid).

order

Responsive<number | `${number}`>

—

Flex/grid child reorder index.

asChild

boolean

—

When `true`, renders the primitive's single React child via `Slot`, forwarding className/style/ref/event handlers onto it.

Accessibility

List always renders as <ul> and OrderedList as <ol> so screen readers announce the list length and item position; DescriptionList renders <dl> to communicate term/details pairings.
Use OrderedList whenever sequence matters — assistive tech announces position information that an unordered list does not.
Avoid mixing non-ListItem children inside List / OrderedList; the semantic structure relies on <li> children to stay intact.
Setting marker="none" hides the visual bullet but preserves list semantics, so an unordered visual layout still reads as a list to screen readers.
Don’t pass as to list components — they are bound to their semantic element and warn in development if you try.

Recipes

Use OrderedList for procedural content like setup steps and checklists.
For key-value pairs, reach for DescriptionList with DescriptionTerm and DescriptionDetails rather than a two-column table.
Keep ListItem content concise; nest a List inside a ListItem when sub-points are needed.
Set markerColor to an accent token to tint bullets without changing the body colour.