MegaSelect

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

Edit on GitHubEditllms.txt

iOSAndroid

Preview MegaSelect on your device

Scan with Expo Go

iOS Android

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

Installation

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

Required Packages(1 package)

pnpm add @shopify/flash-list

Usage

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

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'
});

<MegaSelect items={items} onSelectionChange={setValue} />

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 icons 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`

MegaSelect

On this page