List

Beta

List primitives with item composition using ListItem children.

Installation

npm install @xaui/native

Import

import { List, ListItem } from '@xaui/native/list'

Basic Usage

Minimal example showing the component with its default configuration.

import { List } from '@xaui/native/list'

export function Example() {
  return (
    <List>
      {/* children */}
    </List>
  )
}

Basic List

Simple composable list using List and ListItem.

import { List, ListItem } from '@xaui/native/list'

export function BasicListExample() {
  return (
    <List>
      <ListItem itemKey="profile" title="Profile" description="Manage account settings" />
      <ListItem itemKey="notifications" title="Notifications" description="Push and email preferences" />
      <ListItem itemKey="security" title="Security" description="Password and 2FA" />
    </List>
  )
}

Single Selection (Controlled)

Drive selected state externally with selectedKeys.

import { useState } from 'react'
import { List, ListItem } from '@xaui/native/list'
import { Typography } from '@xaui/native/typography'

export function ControlledSingleSelectionListExample() {
  const [selected, setSelected] = useState<string[]>(['weekly'])

  return (
    <>
      <List
        selectionMode="single"
        isSelectable
        selectedKeys={selected}
        onSelectionChange={setSelected}
      >
        <ListItem itemKey="daily" title="Daily digest" />
        <ListItem itemKey="weekly" title="Weekly summary" />
        <ListItem itemKey="never" title="Never" />
      </List>
      <Typography variant="caption">Selected: {selected[0] ?? 'none'}</Typography>
    </>
  )
}

Multiple Selection with Dividers

Enable multi-select and separators between rows.

import { useState } from 'react'
import { List, ListItem } from '@xaui/native/list'

export function MultiSelectionListExample() {
  const [selected, setSelected] = useState<string[]>(['docs'])

  return (
    <List
      selectionMode="multiple"
      isSelectable
      showDivider
      selectedKeys={selected}
      onSelectionChange={setSelected}
    >
      <ListItem itemKey="docs" title="Docs" />
      <ListItem itemKey="api" title="API" />
      <ListItem itemKey="sdk" title="SDK" />
      <ListItem itemKey="examples" title="Examples" />
    </List>
  )
}

Disabled Item

Prevent selection and press interaction for specific rows.

import { List, ListItem } from '@xaui/native/list'

export function DisabledItemListExample() {
  return (
    <List selectionMode="single" isSelectable>
      <ListItem itemKey="free" title="Free plan" />
      <ListItem itemKey="pro" title="Pro plan" />
      <ListItem itemKey="enterprise" title="Enterprise" isDisabled description="Contact sales" />
    </List>
  )
}

Custom Item Content

Use startContent, endContent, and customAppearance on rows.

import { List, ListItem } from '@xaui/native/list'
import { Typography } from '@xaui/native/typography'
import { Badge } from '@xaui/native/badge'

export function CustomContentListExample() {
  return (
    <List showDivider>
      <ListItem
        itemKey="inbox"
        title="Inbox"
        startContent={<Typography>📥</Typography>}
        endContent={<Badge content={12} size="sm" />}
      />
      <ListItem
        itemKey="sent"
        title="Sent"
        startContent={<Typography>📤</Typography>}
        customAppearance={{ title: { fontWeight: '700' } }}
      />
    </List>
  )
}