ListBuilder

Beta

Data-driven list using FlatList with selection, dividers and generic item rendering.

Installation

npm install @xaui/native

Import

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

Basic Usage

Minimal example showing the component with its default configuration.

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

export function Example() {
  return <ListBuilder />
}

Basic List

Render a typed array with renderItem and keyExtractor.

import { ListBuilder } from '@xaui/native/list'
import { ListItem } from '@xaui/native/list'

type Fruit = { id: string; name: string; emoji: string }

const fruits: Fruit[] = [
  { id: '1', name: 'Apple', emoji: '🍎' },
  { id: '2', name: 'Banana', emoji: '🍌' },
  { id: '3', name: 'Cherry', emoji: '🍒' },
]

export function BasicListBuilderExample() {
  return (
    <ListBuilder
      data={fruits}
      keyExtractor={(item) => item.id}
      renderItem={(item) => (
        <ListItem
          itemKey={item.id}
          title={item.name}
          startContent={item.emoji}
        />
      )}
    />
  )
}

Single Selection

Enable item selection with selectionMode and isSelectable.

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

type Language = { id: string; label: string }

const languages: Language[] = [
  { id: 'ts', label: 'TypeScript' },
  { id: 'py', label: 'Python' },
  { id: 'go', label: 'Go' },
  { id: 'rs', label: 'Rust' },
]

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

  return (
    <>
      <ListBuilder
        data={languages}
        keyExtractor={(item) => item.id}
        selectionMode="single"
        isSelectable
        themeColor="primary"
        onSelectionChange={setSelected}
        renderItem={(item) => (
          <ListItem itemKey={item.id} title={item.label} />
        )}
      />
      <Typography variant="caption">
        Selected: {selected[0] ?? 'none'}
      </Typography>
    </>
  )
}

Multiple Selection with Dividers

Allow multi-select and show dividers between items.

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

type Tag = { id: string; label: string; color: string }

const tags: Tag[] = [
  { id: 'bug', label: 'Bug', color: 'danger' },
  { id: 'feat', label: 'Feature', color: 'success' },
  { id: 'docs', label: 'Docs', color: 'primary' },
  { id: 'refactor', label: 'Refactor', color: 'warning' },
]

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

  return (
    <ListBuilder
      data={tags}
      keyExtractor={(item) => item.id}
      selectionMode="multiple"
      isSelectable
      showDivider
      defaultSelectedKeys={['bug']}
      onSelectionChange={setSelected}
      renderItem={(item) => (
        <ListItem itemKey={item.id} title={item.label} />
      )}
    />
  )
}

Controlled Selection

Drive selection state externally with selectedKeys.

import { useState } from 'react'
import { View } from 'react-native'
import { ListBuilder, ListItem } from '@xaui/native/list'
import { Button } from '@xaui/native/button'

type Item = { id: string; label: string }

const items: Item[] = [
  { id: 'a', label: 'Item A' },
  { id: 'b', label: 'Item B' },
  { id: 'c', label: 'Item C' },
]

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

  return (
    <View style={{ gap: 12 }}>
      <ListBuilder
        data={items}
        keyExtractor={(item) => item.id}
        selectionMode="multiple"
        isSelectable
        selectedKeys={selected}
        onSelectionChange={setSelected}
        renderItem={(item) => (
          <ListItem itemKey={item.id} title={item.label} />
        )}
      />
      <Button onPress={() => setSelected([])}>Clear Selection</Button>
      <Button onPress={() => setSelected(items.map((i) => i.id))}>
        Select All
      </Button>
    </View>
  )
}