# rn-list-box
URL: /docs/native/docyrus/list-box

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

## Installation

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

## Usage

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

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

}
/>
```

### Grid Layout

```tsx
}
  columns={2}
  gap={12}
/>
```

### Client-Side Pagination

```tsx
}
  pageSize={10}
/>
```

### Server-Side Pagination

```tsx
}
  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` |