List
A typography primitive for ordered and unordered lists with design-system spacing, markers, and text styles.
API Reference
List is a moduix typography primitive. Base UI does not provide a matching list
primitive, so the public API stays focused on native ul/ol semantics, visual
variants, and root className composition.
Basic
- Use native list semantics.
- Keep spacing and typography on the design system scale.
- Customize markers with CSS variables.
import { List, ListItem } from "moduix";export function ListDemo() { return ( <List className={styles.list}> {items.map((item) => ( <ListItem key={item}>{item}</ListItem> ))} </List> );}.list { width: min(32rem, calc(100vw - var(--spacing-8)));}const items = [ "Use native list semantics.", "Keep spacing and typography on the design system scale.", "Customize markers with CSS variables.",];Full list of component variables available for project-level overrides.
| Property | Default | Description |
|---|---|---|
| --list-color | var(--list-default-color, var(--color-foreground)) | Controls list text color. |
| --list-default-color | var(--color-foreground) | Controls default tone color. |
| --list-destructive-color | var(--color-destructive) | Controls destructive tone color. |
| --list-font-family | var(--font-sans) | Controls list font family. |
| --list-font-size | var(--list-font-size-md, var(--text-md)) | Controls default list font size. |
| --list-font-size-xs | var(--text-xs) | Controls extra-small list font size. |
| --list-font-size-sm | var(--text-sm) | Controls small list font size. |
| --list-font-size-md | var(--text-md) | Controls medium list font size. |
| --list-font-size-lg | var(--text-lg) | Controls large list font size. |
| --list-font-size-xl | var(--text-xl) | Controls extra-large list font size. |
| --list-font-weight | var(--weight-regular) | Controls list font weight. |
| --list-gap | var(--list-gap-sm, var(--spacing-2)) | Controls default gap between items. |
| --list-gap-xs | var(--spacing-1) | Controls extra-small list item gap. |
| --list-gap-sm | var(--spacing-2) | Controls small list item gap. |
| --list-gap-md | var(--spacing-3) | Controls medium list item gap. |
| --list-gap-lg | var(--spacing-4) | Controls large list item gap. |
| --list-gap-xl | var(--spacing-5) | Controls extra-large list item gap. |
| --list-gap-2xl | var(--spacing-6) | Controls 2xl list item gap. |
| --list-item-padding-x | 0 | Controls list item inline start padding. |
| --list-letter-spacing | 0 | Controls list letter spacing. |
| --list-line-height | var(--list-line-height-md, var(--line-height-text-md)) | Controls default list line height. |
| --list-line-height-xs | var(--line-height-text-xs) | Controls extra-small list line height. |
| --list-line-height-sm | var(--line-height-text-sm) | Controls small list line height. |
| --list-line-height-md | var(--line-height-text-md) | Controls medium list line height. |
| --list-line-height-lg | var(--line-height-text-lg) | Controls large list line height. |
| --list-line-height-xl | var(--line-height-text-xl) | Controls extra-large list line height. |
| --list-marker-color | currentColor | Controls marker color. |
| --list-marker-font-weight | inherit | Controls native marker font weight. |
| --list-marker-gap | var(--spacing-3) | Controls custom bullet marker gap. |
| --list-marker-offset-y | 0.625em | Controls custom bullet vertical offset. |
| --list-marker-radius | var(--radius-full) | Controls custom bullet marker radius. |
| --list-marker-size | 0.375rem | Controls custom bullet marker size. |
| --list-muted-color | var(--color-muted-foreground) | Controls muted tone color. |
| --list-padding-x | var(--spacing-5) | Controls marker indentation. |
| --list-primary-color | var(--color-primary) | Controls primary tone color. |
| --list-subtle-color | var(--color-secondary-foreground) | Controls subtle tone color. |
Interactive variables scoped for docs preview without changing size scale tokens.
| Property | Value | Default | Description |
|---|---|---|---|
| --list-color | var(--list-default-color, var(--color-foreground)) | Controls list text color. | |
| --list-default-color | var(--color-foreground) | Controls default tone color. | |
| --list-destructive-color | var(--color-destructive) | Controls destructive tone color. | |
| --list-font-family | var(--font-sans) | Controls list font family. | |
| --list-font-size | var(--list-font-size-md, var(--text-md)) | Controls default list font size. | |
| --list-font-size-xs | var(--text-xs) | Controls extra-small list font size. | |
| --list-font-size-sm | var(--text-sm) | Controls small list font size. | |
| --list-font-size-md | var(--text-md) | Controls medium list font size. | |
| --list-font-size-lg | var(--text-lg) | Controls large list font size. | |
| --list-font-size-xl | var(--text-xl) | Controls extra-large list font size. | |
| --list-font-weight | var(--weight-regular) | Controls list font weight. | |
| --list-gap | var(--list-gap-sm, var(--spacing-2)) | Controls default gap between items. | |
| --list-gap-xs | var(--spacing-1) | Controls extra-small list item gap. | |
| --list-gap-sm | var(--spacing-2) | Controls small list item gap. | |
| --list-gap-md | var(--spacing-3) | Controls medium list item gap. | |
| --list-gap-lg | var(--spacing-4) | Controls large list item gap. | |
| --list-gap-xl | var(--spacing-5) | Controls extra-large list item gap. | |
| --list-gap-2xl | var(--spacing-6) | Controls 2xl list item gap. | |
| --list-item-padding-x | 0 | Controls list item inline start padding. | |
| --list-letter-spacing | 0 | Controls list letter spacing. | |
| --list-line-height | var(--list-line-height-md, var(--line-height-text-md)) | Controls default list line height. | |
| --list-line-height-xs | var(--line-height-text-xs) | Controls extra-small list line height. | |
| --list-line-height-sm | var(--line-height-text-sm) | Controls small list line height. | |
| --list-line-height-md | var(--line-height-text-md) | Controls medium list line height. | |
| --list-line-height-lg | var(--line-height-text-lg) | Controls large list line height. | |
| --list-line-height-xl | var(--line-height-text-xl) | Controls extra-large list line height. | |
| --list-marker-color | currentColor | Controls marker color. | |
| --list-marker-font-weight | inherit | Controls native marker font weight. | |
| --list-marker-gap | var(--spacing-3) | Controls custom bullet marker gap. | |
| --list-marker-offset-y | 0.625em | Controls custom bullet vertical offset. | |
| --list-marker-radius | var(--radius-full) | Controls custom bullet marker radius. | |
| --list-marker-size | 0.375rem | Controls custom bullet marker size. | |
| --list-muted-color | var(--color-muted-foreground) | Controls muted tone color. | |
| --list-padding-x | var(--spacing-5) | Controls marker indentation. | |
| --list-primary-color | var(--color-primary) | Controls primary tone color. | |
| --list-subtle-color | var(--color-secondary-foreground) | Controls subtle tone color. |
Anatomy
List is composed as a semantic list root with repeated li items. Use ListItem
when you want the exported item slot, or native li elements when a wrapper component
is unnecessary. The root controls marker style, spacing, and typography tokens.
List (ul | ol)
└─ ListItem| Part | Role |
|---|---|
List | Semantic list root that controls marker, spacing, size, and tone. |
ListItem | Individual item wrapper rendered as native list item semantics (li). |
List does not use portal-like service layers such as portal, backdrop, or
viewport. The root and direct li items are the complete DOM structure.
Composition
Use as="ul" or as="ol" for list semantics, marker for marker visibility/style,
and size, gap, tone, plus className for visual customization.
The default marker follows the root element: unordered lists use disc, ordered lists
use decimal. Pass marker="none" for markerless semantic lists or marker="bullet"
when marker size, gap, radius, or vertical offset must be styled independently from text.
All direct li elements receive root spacing and marker styles. For marker="bullet",
ListItem exposes marker/content composition and supports marker styling via
classNames.marker and marker content overrides via marker.
| Prop | Values | Default |
|---|---|---|
as | "ul", "ol" | "ul" |
marker | "disc", "decimal", "bullet", "none" | by as |
gap | "xs", "sm", "md", "lg", "xl", "2xl" | "sm" |
size | "xs", "sm", "md", "lg", "xl" | "md" |
tone | "default", "muted", "subtle", "primary", "destructive" | "default" |
Examples
Ordered
Use as="ol" for ordered steps. The marker defaults to decimal for ordered lists.
- Install the package.
- Import the library stylesheet.
- Use components in your app.
import { List, ListItem } from "moduix";export function OrderedListDemo() { return ( <List as="ol" className={styles.list}> {items.map((item) => ( <ListItem key={item}>{item}</ListItem> ))} </List> );}.list { width: min(32rem, calc(100vw - var(--spacing-8)));}const items = [ "Install the package.", "Import the library stylesheet.", "Use components in your app.",];Markerless
Use marker="none" when list semantics are useful but visual markers are not.
- Markerless item
- Another markerless item
- Useful for compact metadata groups
import { List, ListItem } from "moduix";export function MarkerlessListDemo() { return ( <List marker="none" className={styles.list}> {items.map((item) => ( <ListItem key={item}>{item}</ListItem> ))} </List> );}.list { width: min(32rem, calc(100vw - var(--spacing-8)));}const items = [ "Markerless item", "Another markerless item", "Useful for compact metadata groups",];Native Items
Use native li elements when you do not need the exported ListItem slot.
- Use native li elements when a wrapper component is unnecessary.
- The root still controls spacing, marker style, size, and tone.
- Reach for ListItem when you want the stable item slot.
import { List } from "moduix";export function NativeItemsListDemo() { return ( <List marker="bullet" className={styles.customBullet}> {items.map((item) => ( <li key={item}>{item}</li> ))} </List> );}.customBullet { width: min(32rem, calc(100vw - var(--spacing-8))); --list-marker-color: var(--color-chart-2); --list-marker-size: 0.5rem; --list-marker-gap: var(--spacing-4); --list-marker-offset-y: 0.5em;}const items = [ "Use native li elements when a wrapper component is unnecessary.", "The root still controls spacing, marker style, size, and tone.", "Reach for ListItem when you want the stable item slot.",];Sizes
Use size for visual sizing. Override size-specific CSS variables in your project for responsive typography.
- Extra-large list item
- Medium list item
- Extra-small list item
import { List, ListItem } from "moduix";export function ListSizesDemo() { return ( <div className={styles.stack}> {items.map((item) => ( <List key={item.size} size={item.size}> <ListItem>{item.label}</ListItem> </List> ))} </div> );}.stack { width: min(32rem, calc(100vw - var(--spacing-8))); display: flex; flex-direction: column; gap: var(--spacing-6);}const items = [ { size: "xl", label: "Extra-large list item" }, { size: "md", label: "Medium list item" }, { size: "xs", label: "Extra-small list item" },] as const;Gaps
Use gap to control vertical spacing between list items.
- Extra-small gap
- Second item
- Large gap
- Second item
import { List, ListItem } from "moduix";export function ListGapsDemo() { return ( <div className={styles.stack}> {groups.map((group) => ( <List key={group.gap} gap={group.gap}> {group.items.map((item) => ( <ListItem key={item}>{item}</ListItem> ))} </List> ))} </div> );}.stack { width: min(32rem, calc(100vw - var(--spacing-8))); display: flex; flex-direction: column; gap: var(--spacing-6);}const groups = [ { gap: "xs", items: ["Extra-small gap", "Second item"] }, { gap: "lg", items: ["Large gap", "Second item"] },] as const;Tones
Use tone when the list should inherit a semantic text color from the design system.
- Default list tone
- Muted list tone
- Subtle list tone
- Primary list tone
- Destructive list tone
import { List, ListItem } from "moduix";export function ListTonesDemo() { return ( <div className={styles.toneGrid}> {items.map((item) => ( <List key={item.tone} tone={item.tone}> <ListItem>{item.label}</ListItem> </List> ))} </div> );}.toneGrid { width: min(32rem, calc(100vw - var(--spacing-8))); display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: var(--spacing-4) var(--spacing-6);}const items = [ { tone: "default", label: "Default list tone" }, { tone: "muted", label: "Muted list tone" }, { tone: "subtle", label: "Subtle list tone" }, { tone: "primary", label: "Primary list tone" }, { tone: "destructive", label: "Destructive list tone" },] as const;Custom Styles
Use marker="bullet" when marker size, color, gap, or vertical offset must be controlled independently from the text.
- Bullet size is independent from text size.
- Bullet color and gap are controlled by CSS variables.
- Text color remains unchanged.
import { List, ListItem } from "moduix";export function CustomStylesListDemo() { return ( <List marker="bullet" className={styles.customBullet}> {items.map((item) => ( <ListItem key={item} classNames={{ marker: styles.glowMarker }}> {item} </ListItem> ))} </List> );}.customBullet { width: min(32rem, calc(100vw - var(--spacing-8))); --list-marker-color: var(--color-chart-2); --list-marker-size: 0.5rem; --list-marker-gap: var(--spacing-4); --list-marker-offset-y: 0.5em;}.glowMarker { box-shadow: 0 0 0 0.25rem color-mix(in oklab, var(--list-marker-color), transparent 78%), 0 0.125rem 0.375rem color-mix(in oklab, var(--list-marker-color), transparent 68%);}const items = [ "Bullet size is independent from text size.", "Bullet color and gap are controlled by CSS variables.", "Text color remains unchanged.",];