# React Native Searchable Select List

> Inline, searchable React Native selection list with single or multiple selection, groups, icons, descriptions and custom rows — the list inside Select.

# SelectList

`SelectList` is the searchable React Native list inside [`Select`](./select), as a standalone inline component. Use it in settings screens, onboarding steps, or your own sheets and modals.

```tsx
import { SelectList } from 'patine-ui';
```

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { SelectList } from 'patine-ui';

const themes = [
  {
    label: 'System',
    value: 'system',
    description: 'Follow the device setting',
  },
  { label: 'Light', value: 'light' },
  { label: 'Dark', value: 'dark' },
];

export default function Example() {
  const [mode, setMode] = useState<string | null>('system');
  return (
    <View
      style={{
        borderWidth: 1,
        borderColor: '#E8E4DC',
        borderRadius: 16,
        paddingVertical: 8,
      }}
    >
      <SelectList options={themes} value={mode} onValueChange={setMode} />
    </View>
  );
}
```

## Example: label an issue

An issue tracker's Labels picker: search the project's labels, pick up to three, and the chosen ones show as colored badges on the issue above.

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { Box, HStack, SelectList, Text, VStack } from 'patine-ui';

const LABELS = [
  { value: 'bug', label: 'Bug', color: '#DC2626', description: 'Something is broken' },
  { value: 'perf', label: 'Performance', color: '#D97706' },
  { value: 'ios', label: 'iOS', color: '#2563EB' },
  { value: 'android', label: 'Android', color: '#16A34A' },
  { value: 'web', label: 'Web', color: '#7C3AED' },
  { value: 'a11y', label: 'Accessibility', color: '#0891B2' },
  { value: 'design', label: 'Needs design', color: '#DB2777' },
  { value: 'docs', label: 'Docs', color: '#4B5563' },
  { value: 'good-first', label: 'Good first issue', color: '#059669', description: 'Small and well scoped' },
];

export default function Example() {
  const [picked, setPicked] = useState<string[]>(['bug', 'ios']);
  return (
    <Box border radius="lg" style={{ width: '100%', maxWidth: 400, overflow: 'hidden' }}>
      <VStack gap="xs" padding="md">
        <Text weight="semibold">Checkout freezes after Apple Pay</Text>
        <HStack gap="xs" wrap>
          {picked.map((value) => {
            const l = LABELS.find((x) => x.value === value)!;
            return (
              <View key={value} style={{ paddingHorizontal: 8, paddingVertical: 2, borderRadius: 999, backgroundColor: `${l.color}1F` }}>
                <Text size="xs" weight="medium" style={{ color: l.color }}>{l.label}</Text>
              </View>
            );
          })}
        </HStack>
      </VStack>
      <SelectList options={LABELS} multiple maxSelected={3} searchable searchPlaceholder="Filter labels" value={picked} onValueChange={setPicked} />
    </Box>
  );
}
```

## Multiple, with search

```tsx live
import { useState } from 'react';
import { SelectList } from 'patine-ui';

const toppings = [
  'Mozzarella',
  'Basil',
  'Mushrooms',
  'Olives',
  'Pepperoni',
  'Jalapeños',
  'Pineapple',
  'Onion',
  'Ham',
  'Rocket',
].map((t) => ({
  label: t,
  value: t,
  group: ['Pepperoni', 'Ham'].includes(t) ? 'Meat' : 'Veggie',
}));

export default function Example() {
  const [picked, setPicked] = useState<string[]>(['Mozzarella', 'Basil']);
  return (
    <SelectList
      multiple
      options={toppings}
      value={picked}
      onValueChange={setPicked}
      maxSelected={5}
      listHeight={320}
    />
  );
}
```

## Searching a server

`loadOptions` loads the options for what the user types, with the loader showing from the keystroke until they arrive. Here the list starts with recent picks and searches a fake API:

```tsx live
import { useState } from 'react';
import { SelectList } from 'patine-ui';

const RECENT = ['react', 'react-native', 'expo'].map((name) => ({ label: name, value: name, description: 'Recent' }));
const PACKAGES = ['react', 'react-dom', 'react-native', 'react-native-web', 'react-query', 'redux', 'expo', 'expo-router', 'zod', 'zustand', 'date-fns', 'dayjs'];

// Stands in for a package registry search
const searchPackages = (query: string) =>
  new Promise<{ label: string; value: string }[]>((resolve) =>
    setTimeout(() => resolve(PACKAGES.filter((p) => p.includes(query.toLowerCase())).map((p) => ({ label: p, value: p }))), 500)
  );

export default function Example() {
  const [packages, setPackages] = useState<string[]>([]);
  return (
    <SelectList
      multiple
      options={RECENT}
      loadOptions={searchPackages}
      value={packages}
      onValueChange={setPackages}
      searchPlaceholder="Search packages"
      loadingText="Searching the registry…"
      listHeight={300}
    />
  );
}
```

## Loading more as you scroll

`onEndReached` fires near the end of the list; append the next page to `options` and set `loading` while it's on its way. The spinner shows under the options.

```tsx live
import { useEffect, useState } from 'react';
import { SelectList } from 'patine-ui';

const PAGE = 15;
const TOTAL = 60;

// Stands in for your API
const fetchPage = (offset: number) =>
  new Promise<{ label: string; value: number }[]>((resolve) =>
    setTimeout(
      () =>
        resolve(
          Array.from({ length: Math.min(PAGE, TOTAL - offset) }, (_, i) => ({
            label: `Contact ${offset + i + 1}`,
            value: offset + i + 1,
          }))
        ),
      800
    )
  );

export default function Example() {
  const [contact, setContact] = useState<number | null>(null);
  const [options, setOptions] = useState<{ label: string; value: number }[]>([]);
  const [loading, setLoading] = useState(false);

  const loadMore = () => {
    if (loading || options.length >= TOTAL) return;
    setLoading(true);
    fetchPage(options.length).then((page) => {
      setOptions((current) => [...current, ...page]);
      setLoading(false);
    });
  };

  useEffect(loadMore, []);

  return (
    <SelectList
      options={options}
      value={contact}
      onValueChange={setContact}
      searchable={false}
      loading={loading}
      loadingText="Loading contacts…"
      onEndReached={loadMore}
      listHeight={300}
    />
  );
}
```

## Behaviour

- **Controlled only**: pass `value` and update it in `onValueChange`.
- In single mode, tapping an option calls `onValueChange(value, option)`, including when it's already selected (there's no deselect).
- In multiple mode, taps toggle. `onValueChange(values, options)` keeps selection order (appended at the end).
- With `maxSelected` reached, unselected options become disabled until something is deselected.
- Without `listHeight`, the list grows with its content. Inside a scroll view or sheet, give it a `listHeight` so it scrolls on its own.
- Search state is internal and resets when the list unmounts; with `onSearchChange`, that reset calls `onSearchChange('')` so a remote list can drop its results.
- For options from a server, see [Search on a server](./select#search-on-a-server): `loadOptions`, `onSearchChange`, `loading` and `onEndReached` work the same here.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | `ReadonlyArray<SelectOption<T>>` | `[]` | See [options](./select#options). With `loadOptions`, the ones shown before the user types. |
| `multiple` | `boolean` | `false` | Multi-select. |
| `value` | `T \| null` · `T[]` | — | Selection, when you control it. |
| `defaultValue` | `T \| null` · `T[]` | — | The selection at first, when it keeps its own. |
| `onValueChange` | `(value: T, option) => void` · `(values: T[], options) => void` | — | Single · multiple. |
| `maxSelected` | `number` | — | Multiple only. |
| `searchable` | `boolean` | `options.length > 8`, or with `loadOptions` / `onSearchChange` | Show the search field. |
| `query` | `string` | — | Controlled search query, for filtering from your own input. Hides the built-in search field. |
| `searchPlaceholder` | `string` | `'Search'` | Search hint and its accessibility label. |
| `filterOption` | `(option: SelectOption<T>, query: string) => boolean` | `defaultFilter`; none with `loadOptions` / `onSearchChange` | Custom filter. |
| `loadOptions` | `(query: string) => Promise<ReadonlyArray<SelectOption<T>>>` | — | [Search a server](./select#search-on-a-server): loader, debounce and stale answers handled. |
| `onSearchChange` | `(query: string) => void` | — | Called once typing pauses, to search yourself. |
| `searchPrompt` | `string` | `'Type to search'` | Shown before the user types, while a searched list has no options. |
| `searchDebounce` | `number` | `300` | ms after the last keystroke before `loadOptions` / `onSearchChange`. |
| `onEndReached` | `() => void` | — | Called near the end of the list, to load more. |
| `loading` | `boolean` | `false` | Spinner in place of an empty list, or under the options. |
| `loadingText` | `string` | `'Loading…'` | Text next to the spinner. |
| `renderLoading` | `(theme: Theme) => ReactNode` | — | Custom loader. |
| `renderOption` | `(info: SelectRenderOptionInfo<T>) => ReactNode` | — | Custom row content. |
| `renderGroupHeader` | `(group: string, theme: Theme) => ReactNode` | — | Custom section header. |
| `emptyText` | `string` | `'No results'` | Empty-state text. |
| `onCreate` | `(text: string) => SelectOption<T> \| void` | — | [Offer the typed text as a new option](./select#create-new-options) when no label matches. Return the option to select it. |
| `createLabel` | `(text: string) => string` | `` (text) => `Add "${text}"` `` | The create row's text. |
| `showCheckmarks` | `boolean` | `true` | ✓ or radio (single, radio in the Material design) / checkbox (multiple). |
| `isEqual` | `(a: T, b: T) => boolean` | `Object.is` | Value equality. |
| `listHeight` | `number` | — | Fixed height for the scrolling list. |
| `autoFocusSearch` | `boolean` | `false` | Focus the search on mount. |
| `style` | `StyleProp<ViewStyle>` | — | Container style. |
| `styles` | `SlotStyles<SelectSlot>` | — | Slots below. |
| `theme` | `DeepPartial<Theme>` | — | Theme override. |
| `design` | `'brand' \| 'ios' \| 'material' \| 'web' \| 'native'` | from `PatineProvider` | The look to follow, over the provider's: [brand, iOS, Material or web](../guides/designs), or `'native'` for the platform's own. |
| `testID` | `string` | — | Test ID. |

### Slots

| Slot | Element |
| --- | --- |
| `container` | Outer view |
| `search` | Search field wrapper |
| `searchInput` | The `TextInput` |
| `list` | The `FlatList` |
| `groupHeader` / `groupHeaderText` | Section header |
| `option` | Each row |
| `selectedOption` | Selected rows (merged after `option`) |
| `optionLabel` / `selectedOptionLabel` | Row label |
| `optionDescription` | Second line |
| `check` | ✓, radio or checkbox |
| `empty` / `emptyText` | Empty state, and the `searchPrompt` |
| `loading` / `loadingText` | Loader row / its text |
| `createOption` / `createOptionLabel` | The **Add "…"** row / its text |

### Types

```ts
interface SelectRenderOptionInfo<T> { option: SelectOption<T>; selected: boolean; disabled: boolean; theme: Theme }
type SelectValueProps<T> =
  | { multiple?: false; value?: T | null; onValueChange?: (value: T, option: SelectOption<T>) => void }
  | { multiple: true; value?: T[]; onValueChange?: (value: T[], options: SelectOption<T>[]) => void; maxSelected?: number };
```

## Related

- [Select](./select): the same list behind a field, in a dropdown or a sheet
- [Search a server example](/examples/server-search): options loaded as the user types
- [Tags example](/examples/tags): multiple selection with search
