moduix

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.

PropertyDefaultDescription
--list-colorvar(--list-default-color, var(--color-foreground))Controls list text color.
--list-default-colorvar(--color-foreground)Controls default tone color.
--list-destructive-colorvar(--color-destructive)Controls destructive tone color.
--list-font-familyvar(--font-sans)Controls list font family.
--list-font-sizevar(--list-font-size-md, var(--text-md))Controls default list font size.
--list-font-size-xsvar(--text-xs)Controls extra-small list font size.
--list-font-size-smvar(--text-sm)Controls small list font size.
--list-font-size-mdvar(--text-md)Controls medium list font size.
--list-font-size-lgvar(--text-lg)Controls large list font size.
--list-font-size-xlvar(--text-xl)Controls extra-large list font size.
--list-font-weightvar(--weight-regular)Controls list font weight.
--list-gapvar(--list-gap-sm, var(--spacing-2))Controls default gap between items.
--list-gap-xsvar(--spacing-1)Controls extra-small list item gap.
--list-gap-smvar(--spacing-2)Controls small list item gap.
--list-gap-mdvar(--spacing-3)Controls medium list item gap.
--list-gap-lgvar(--spacing-4)Controls large list item gap.
--list-gap-xlvar(--spacing-5)Controls extra-large list item gap.
--list-gap-2xlvar(--spacing-6)Controls 2xl list item gap.
--list-item-padding-x0Controls list item inline start padding.
--list-letter-spacing0Controls list letter spacing.
--list-line-heightvar(--list-line-height-md, var(--line-height-text-md))Controls default list line height.
--list-line-height-xsvar(--line-height-text-xs)Controls extra-small list line height.
--list-line-height-smvar(--line-height-text-sm)Controls small list line height.
--list-line-height-mdvar(--line-height-text-md)Controls medium list line height.
--list-line-height-lgvar(--line-height-text-lg)Controls large list line height.
--list-line-height-xlvar(--line-height-text-xl)Controls extra-large list line height.
--list-marker-colorcurrentColorControls marker color.
--list-marker-font-weightinheritControls native marker font weight.
--list-marker-gapvar(--spacing-3)Controls custom bullet marker gap.
--list-marker-offset-y0.625emControls custom bullet vertical offset.
--list-marker-radiusvar(--radius-full)Controls custom bullet marker radius.
--list-marker-size0.375remControls custom bullet marker size.
--list-muted-colorvar(--color-muted-foreground)Controls muted tone color.
--list-padding-xvar(--spacing-5)Controls marker indentation.
--list-primary-colorvar(--color-primary)Controls primary tone color.
--list-subtle-colorvar(--color-secondary-foreground)Controls subtle tone color.

Interactive variables scoped for docs preview without changing size scale tokens.

PropertyValueDefaultDescription
--list-colorvar(--list-default-color, var(--color-foreground))Controls list text color.
--list-default-colorvar(--color-foreground)Controls default tone color.
--list-destructive-colorvar(--color-destructive)Controls destructive tone color.
--list-font-familyvar(--font-sans)Controls list font family.
--list-font-sizevar(--list-font-size-md, var(--text-md))Controls default list font size.
--list-font-size-xsvar(--text-xs)Controls extra-small list font size.
--list-font-size-smvar(--text-sm)Controls small list font size.
--list-font-size-mdvar(--text-md)Controls medium list font size.
--list-font-size-lgvar(--text-lg)Controls large list font size.
--list-font-size-xlvar(--text-xl)Controls extra-large list font size.
--list-font-weightvar(--weight-regular)Controls list font weight.
--list-gapvar(--list-gap-sm, var(--spacing-2))Controls default gap between items.
--list-gap-xsvar(--spacing-1)Controls extra-small list item gap.
--list-gap-smvar(--spacing-2)Controls small list item gap.
--list-gap-mdvar(--spacing-3)Controls medium list item gap.
--list-gap-lgvar(--spacing-4)Controls large list item gap.
--list-gap-xlvar(--spacing-5)Controls extra-large list item gap.
--list-gap-2xlvar(--spacing-6)Controls 2xl list item gap.
--list-item-padding-x0Controls list item inline start padding.
--list-letter-spacing0Controls list letter spacing.
--list-line-heightvar(--list-line-height-md, var(--line-height-text-md))Controls default list line height.
--list-line-height-xsvar(--line-height-text-xs)Controls extra-small list line height.
--list-line-height-smvar(--line-height-text-sm)Controls small list line height.
--list-line-height-mdvar(--line-height-text-md)Controls medium list line height.
--list-line-height-lgvar(--line-height-text-lg)Controls large list line height.
--list-line-height-xlvar(--line-height-text-xl)Controls extra-large list line height.
--list-marker-colorcurrentColorControls marker color.
--list-marker-font-weightinheritControls native marker font weight.
--list-marker-gapvar(--spacing-3)Controls custom bullet marker gap.
--list-marker-offset-y0.625emControls custom bullet vertical offset.
--list-marker-radiusvar(--radius-full)Controls custom bullet marker radius.
--list-marker-size0.375remControls custom bullet marker size.
--list-muted-colorvar(--color-muted-foreground)Controls muted tone color.
--list-padding-xvar(--spacing-5)Controls marker indentation.
--list-primary-colorvar(--color-primary)Controls primary tone color.
--list-subtle-colorvar(--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
PartRole
ListSemantic list root that controls marker, spacing, size, and tone.
ListItemIndividual 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.

PropValuesDefault
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.

  1. Install the package.
  2. Import the library stylesheet.
  3. 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.",];

On this page