ListBox

Grid-capable list component with client/server pagination and infinite scroll support.

iOSAndroid

Preview ListBox on your device

Scan with Expo Go

Download Expo Go, then scan the QR code to preview native components.

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-list-box

Usage

import { ListBox } from '@/components/docyrus-native/list-box';

const items = [
  { id: '1', name: 'Item 1' },
  { id: '2', name: 'Item 2' },
];

<ListBox
  data={items}
  keyExtractor={(item) => item.id}
  renderItem={(item) => <Text>{item.name}</Text>}
/>

Grid Layout

<ListBox
  data={items}
  keyExtractor={(item) => item.id}
  renderItem={(item) => <Card>{item.name}</Card>}
  columns={2}
  gap={12}
/>

Client-Side Pagination

<ListBox
  data={allItems}
  keyExtractor={(item) => item.id}
  renderItem={(item) => <Text>{item.name}</Text>}
  pageSize={10}
/>

Server-Side Pagination

<ListBox
  data={pageData}
  keyExtractor={(item) => item.id}
  renderItem={(item) => <Text>{item.name}</Text>}
  serverPagination
  totalItems={100}
  currentPage={page}
  onPageChange={setPage}
  pageSize={10}
/>

API Reference

Prop	Type	Default	Description
`data`	`T[]`	—	Array of items to display
`renderItem`	`(item: T, index: number) => ReactNode`	—	Render function for each item
`keyExtractor`	`(item: T, index: number) => string`	—	Function to extract unique key per item
`columns`	`1 \| 2 \| 3`	`1`	Number of columns in the grid
`gap`	`number`	`8`	Gap between items in pixels
`pageSize`	`number`	—	Items per page (enables pagination)
`serverPagination`	`boolean`	`false`	Use server-controlled pagination
`totalItems`	`number`	—	Total item count for server pagination
`currentPage`	`number`	`1`	Current page for server pagination
`onPageChange`	`(page: number) => void`	—	Page change callback for server pagination
`onEndReached`	`() => void`	—	Infinite scroll callback when reaching end
`loading`	`boolean`	`false`	Show loading indicator in footer
`emptyMessage`	`string`	`'No items to display'`	Message when list is empty
`emptyIcon`	`string`	—	Emoji displayed above empty message
`className`	`string`	—	FlatList CSS classes
`contentContainerClassName`	`string`	—	Content area CSS classes

Translation Keys

Built-in copy is read through useUiTranslation() — provide these keys via <UiTranslationProvider>. Without a provider the English fallback is shown.

Key	English fallback	Used for
`ui.listBox.empty`	No items to display	Empty text (`emptyMessage` prop wins)
`ui.listBox.loading`	Loading...	Load-more indicator

Type Exports

Type	Description
`ListBoxProps<T>`	Props for ListBox component
`ListBoxColumns`	`1 \| 2 \| 3`

ListBox

On this page