# rn-mega-select
URL: /docs/native/docyrus/mega-select

Searchable bottom-sheet select with categories, DocyrusIcon / image items, Tailwind accent colours, detail pages and a Choose CTA.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-mega-select
```

**Dependencies:**
- [@shopify/flash-list](https://www.npmjs.com/package/@shopify/flash-list)

## Usage

```tsx
import { MegaSelect, type MegaSelectItem } from '@/components/docyrus-native/mega-select';

const items: MegaSelectItem[] = [
  { id: 'figma', label: 'Figma', description: 'Design tool', icon: 'fab figma', color: 'purple', categoryId: 'design' },
  { id: 'vscode', label: 'VS Code', description: 'Code editor', icon: 'fal code', color: 'blue-500', categoryId: 'dev' }
];

<MegaSelect
  items={items}
  categories={[{ id: 'design', label: 'Design', icon: 'fal palette' }, { id: 'dev', label: 'Development' }]}
  value={selectedId}
  onSelectionChange={(value, item) => setSelectedId(value)}
  onChoose={(value, item) => handleChoose(item)}
  columns="auto"
  size="large"
/>
```

### Mapping API rows

```tsx
import { MegaSelect, mapToMegaSelectItems } from '@/components/docyrus-native/mega-select';

const items = mapToMegaSelectItems(rows, {
  id: 'id',
  label: 'name',
  description: 'summary',
  icon: 'icon',
  color: 'color',
  categoryId: 'category_id'
});

```

## Behaviour

- The trigger opens an `ActionSheet`. Tapping a row selects it (`onSelectionChange`) and closes the sheet, unless `onChoose` is set — then a **Choose** button confirms (`onChoose`) and closes.
- Items with `content` show a **Read more** chip that opens the detail page; with `forceOpenDetail` a tap on the row opens it directly.
- `onClose` fires only on user dismissal (backdrop tap, drag-down, close button) — not after a selection or Choose.
- String `icon`s render through `DocyrusIcon`; `color` accepts Tailwind names (`"blue"` → 500 shade, `"emerald-500"`) or hex, and the icon tile gets a translucent tint of it.
- Copy is translated through `useUiTranslation()` with the web keys: `ui.megaSelect.placeholder` (Select an item...), `ui.megaSelect.chooseItem` (Choose item), `ui.megaSelect.choose`, `ui.megaSelect.readMore`, `ui.megaSelect.back`, `ui.megaSelect.allCategories`, `ui.megaSelect.noItems`, `ui.megaSelect.noResults`, `ui.megaSelect.currentSelection`, `ui.megaSelect.result` / `ui.megaSelect.results`, `ui.common.close`, `ui.common.searchPlaceholder`.

## API Reference

### MegaSelectProps\<T\>

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `MegaSelectItem<T>[]` | - | Array of selectable items (required) |
| `categories` | `MegaSelectCategory[]` | - | Category chips for filtering |
| `value` | `string \| null` | - | Controlled selected item ID |
| `defaultValue` | `string \| null` | - | Initial selected item ID (uncontrolled) |
| `onSelectionChange` | `(value: string \| null, item: MegaSelectItem<T> \| null) => void` | - | Called when a row is tapped |
| `onChoose` | `(value: string, item: MegaSelectItem<T>) => void` | - | Called on the "Choose" button; enables the Choose CTA |
| `onClose` | `() => void` | - | Called when the user dismisses the sheet (backdrop, drag, close button) |
| `searchable` | `boolean` | `true` | Show search input |
| `placeholder` | `string` | `t('ui.megaSelect.placeholder', 'Select an item...')` | Trigger placeholder text |
| `disabled` | `boolean` | `false` | Disable the trigger |
| `loading` | `boolean` | `false` | Show skeleton rows instead of items |
| `forceOpenDetail` | `boolean` | `false` | Open the detail page on tap for items with content |
| `defaultColor` | `string` | - | Accent colour (Tailwind name or hex) for items without a colour |
| `defaultIcon` | `string` | - | DocyrusIcon for items without an icon or image |
| `columns` | `1 \| 2 \| 3 \| 4 \| 'auto'` | `1` | List columns; `'auto'` = 1 on phones, 2 on tablets (≥ 768pt) |
| `size` | `'thin' \| 'default' \| 'large' \| 'full'` | `'default'` | Sheet size (maps to ActionSheet detents — see below) |
| `variant` | `'default' \| 'elevated' \| 'flat'` | `'default'` | Trigger styling |
| `closable` | `boolean` | `true` | Show the close button and close on backdrop tap |
| `restrictedValue` | `string` | - | Only this item is interactable; others render disabled |
| `className` | `string` | - | Trigger CSS classes |
| `style` | `ViewStyle` | - | Trigger style |

### Sizes

| `size` | Sheet detents |
|--------|---------------|
| `thin` | `['medium']` |
| `default` | `['medium', 'large']` |
| `large` | `['large']` |
| `full` | `['large']` |

### Variants

| `variant` | Trigger |
|-----------|---------|
| `default` | Card background, subtle border |
| `elevated` | Card background, lighter border, `shadow-lg` |
| `flat` | Muted background, no border |

### MegaSelectItem\<T\>

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `id` | `string` | - | Unique identifier (required) |
| `label` | `string` | - | Display text (required) |
| `description` | `string` | - | Secondary text |
| `icon` | `string \| ReactNode` | - | DocyrusIcon identifier (e.g. `"fal star"`) or a custom element |
| `image` | `string` | - | Image URL — takes precedence over icon |
| `color` | `string` | - | Accent colour — Tailwind name (`"blue"`, `"emerald-500"`) or hex. Colour-only items render a letter avatar |
| `categoryId` | `string` | - | Category ID for filtering (falls back to `data.category`) |
| `content` | `ReactNode` | - | Rich content rendered in the detail page |
| `disabled` | `boolean` | `false` | Non-interactive, reduced opacity |
| `data` | `T` | - | Original data passthrough |

### MegaSelectCategory

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `id` | `string` | - | Category identifier (required) |
| `label` | `string` | - | Chip label (required) |
| `icon` | `string \| ReactNode` | - | DocyrusIcon identifier or a custom element |

### mapToMegaSelectItems

`mapToMegaSelectItems<R>(data: R[], config: MapToMegaSelectItemsConfig<R>): MegaSelectItem<R>[]` — maps raw rows to items (identical to web). Each row is kept in `item.data`.

| Field | Type | Description |
|-------|------|-------------|
| `id` | `keyof R` | Column for `item.id` (required) |
| `label` | `keyof R` | Column for `item.label` (required) |
| `description` | `keyof R` | Column for `item.description` |
| `icon` | `keyof R` | Column for `item.icon` |
| `image` | `keyof R` | Column for `item.image` |
| `color` | `keyof R` | Column for `item.color` |
| `categoryId` | `keyof R` | Column for `item.categoryId` |

## Exports

| Export | Description |
|--------|-------------|
| `MegaSelect` | Trigger + bottom-sheet select |
| `mapToMegaSelectItems` | Raw rows → `MegaSelectItem[]` helper |

## Type Exports

| Type | Description |
|------|-------------|
| `MegaSelectProps<T>` | Props for MegaSelect |
| `MegaSelectItem<T>` | Selectable item configuration |
| `MegaSelectCategory` | Category chip configuration |
| `MegaSelectSize` | `'thin' \| 'default' \| 'large' \| 'full'` |
| `MegaSelectVariant` | `'default' \| 'elevated' \| 'flat'` |
| `MapToMegaSelectItemsConfig<R>` | Field mapping for `mapToMegaSelectItems` |