list

List & List item

Structured list layouts for items.

List / List_item Examples

Copy-ready examples with live previews.

Basic usage

A list with leading, body and trailing content slots.

Live preview

Profile

Account settings

Billing

Payment methods

Security

Password and 2FA

import List from "@/packages/ui/src/_components/list/List";
import List_item from "@/packages/ui/src/_components/list/list_item/List_item";
import Icon from "@/packages/ui/src/_components/icon/Icon";

export default function Example() {
  return (
    <List variant="outlined">
      <List_item
        key="profile"
        leadingContent={<Icon name="person" />}
        bodyContent="Profile"
      />
      <List_item
        key="settings"
        leadingContent={<Icon name="settings" />}
        bodyContent="Settings"
        trailingContent={<Icon name="chevron_right" />}
      />
    </List>
  );
}

List variants

Container surface styles: outlined / tonal / elevated.

Live preview

The variant prop belongs to List (container). Items remain the same.

variant="outlined"

Outlined list

Container style

Settings

Secondary content

variant="tonal"

Tonal list

Softer background

Notifications

Preview layout

variant="elevated"

Elevated list

Shadow surface

Help

Trailing button example

import List from "@/_components/list/List";
import List_item from "@/_components/list/list_item/List_item";

export default function Example() {
  return (
    <>
      <List variant="outlined">
        <List_item key="a" bodyContent="Outlined" />
      </List>

      <List variant="tonal">
        <List_item key="b" bodyContent="Tonal" />
      </List>

      <List variant="elevated">
        <List_item key="c" bodyContent="Elevated" />
      </List>
    </>
  );
}

Slots + states

Use leadingContent / bodyContent / trailingContent + selected/disabled styles.

• Tip: keep a stable React key per item to ensure predictable drag-and-drop behavior.

Live preview

Basic item

Leading + body + trailing

check

Checkbox as leading

Just for layout testing

Selected (static)

isSelected=true

Disabled (static)

isDisabled=true

import List from "@/_components/list/List";
import List_item from "@/_components/list/list_item/List_item";

export default function Example() {
  return (
    <List variant="outlined">
      <List_item key="1" bodyContent="Normal" />
      <List_item key="2" bodyContent="Selected" isSelected />
      <List_item key="3" bodyContent="Disabled" isDisabled />
    </List>
  );
}

Drag and drop

Enable dragging per row using showDrag (handle-based drag).

• Only items with showDrag=true participate in reordering.

Live preview

Drag starts only from the handle. Only items with showDrag participate in reordering.

Fixed item

showDrag=false (stays in place)

Draggable item 1

Try dragging me

Draggable item 2

Try dragging me

Draggable item 3

Try dragging me

Draggable item 4

Try dragging me

Draggable item 5

Try dragging me

Draggable item 6

Try dragging me

Draggable item 7

Try dragging me

Draggable item 8

Try dragging me

Draggable item 9

Try dragging me

Draggable item 10

Try dragging me

Fixed item

Still not draggable

import List from "@/_components/list/List";
import List_item from "@/_components/list/list_item/List_item";

export default function Example() {
  return (
    <List variant="tonal">
      <List_item key="a" showDrag bodyContent="Draggable A" />
      <List_item key="b" bodyContent="Fixed (not draggable)" />
      <List_item key="c" showDrag bodyContent="Draggable C" />
    </List>
  );
}

Long content

Validate wrapping, spacing and trailing actions on narrow containers.

Live preview

Use this to validate wrapping and spacing inside a constrained live preview.

A longer title that should wrap to the next line on narrow widths

Supporting text can also wrap and should not push trailing actions out of view.

Body can be any ReactNode

For example: multiple lines, inline code, or even a custom layout using Stack.

This helps you stress-test the row height and vertical alignment.

import List from "@/_components/list/List";
import List_item from "@/_components/list/list_item/List_item";

export default function Example() {
  return (
    <List variant="outlined">
      <List_item
        key="x"
        bodyContent="A longer title that should wrap"
        trailingContent="Action"
      />
    </List>
  );
}

Interactive playground

Quick way to validate variant + selected/disabled + drag handle in docs.

Live preview

variant

states

Inbox

key="p-1"

Starred

key="p-2"

Sent

key="p-3"

Trash

key="p-4"

import { useState } from "react";
import List from "@/packages/ui/src/_components/list/List";
import List_item from "@/packages/ui/src/_components/list/list_item/List_item";

export default function Example() {
  const [selected, setSelected] = useState("b");

  return (
    <List variant="outlined">
      <List_item key="a" showDrag bodyContent="A" onClick={() => setSelected("a")} />
      <List_item key="b" showDrag bodyContent="B" isSelected={selected === "b"} />
      <List_item key="c" bodyContent="C" isDisabled />
    </List>
  );
}

On this page

List Props

List — Props
Prop	Type	Required	Default	Description
variant	"outlined" \| "tonal" \| "elevated"	No	"outlined"	Visual container style (`cssnt-list--*`).
children	React.ReactElement<ILisItemProps, typeof List_item>[]	No	undefined	List items to render. The List may clone children to inject internal props used for drag-and-drop.
allowDragAndDrop	boolean	No	undefined	Declared in the type, but the current implementation is gated by List_item.showDrag.
minHeight	number	No	undefined	Declared in the type, but not currently applied to styles.
maxHeight	number	No	undefined	Declared in the type, but not currently applied to styles.

List_item Props

List_item — Props
Prop	Type	Required	Default	Description
isSelected	boolean	No	false	Adds `is-selected` class for selected styling.
isDisabled	boolean	No	false	Adds `is-disabled` class and prevents dragging.
showDrag	boolean	No	false	Shows the drag handle and enables dragging for this item.
leadingContent	React.ReactNode	No	undefined	Rendered in the leading slot (icon/avatar/checkbox).
bodyContent	React.ReactNode	No	undefined	Main content slot (text or any ReactNode).
trailingContent	React.ReactNode	No	undefined	Rendered in the trailing slot (chevron/actions/buttons).
div attributes	React.HTMLAttributes<HTMLDivElement>	No	—	List_item also accepts native div attributes (onClick, className, style, role, aria-*, tabIndex, etc.).