Skip to main content

SelectList

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

import { SelectList } from 'patine-ui';
Loading…
<View
  style={{
    borderWidth: 1,
    borderColor: '#E8E4DC',
    borderRadius: 16,
    paddingVertical: 8,
  }}
>
  <SelectList options={themes} value={mode} onValueChange={setMode} />
</View>

Try the props​

Props
<SelectList
options={countries}
value={value}
onValueChange={setValue}
searchable
/>

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.

Loading…
          <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>
Loading…
<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:

Loading…
<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.

Loading…
<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: loadOptions, onSearchChange, loading and onEndReached work the same here.

Props​

PropTypeDefaultDescription
optionsReadonlyArray<SelectOption<T>>[]See options. With loadOptions, the ones shown before the user types.
multiplebooleanfalseMulti-select.
valueT | null · T[]—Selection, when you control it.
defaultValueT | null · T[]—The selection at first, when it keeps its own.
onValueChange(value: T, option) => void · (values: T[], options) => void—Single · multiple.
maxSelectednumber—Multiple only.
searchablebooleanoptions.length > 8, or with loadOptions / onSearchChangeShow the search field.
querystring—Controlled search query, for filtering from your own input. Hides the built-in search field.
searchPlaceholderstring'Search'Search hint and its accessibility label.
filterOption(option: SelectOption<T>, query: string) => booleandefaultFilter; none with loadOptions / onSearchChangeCustom filter.
loadOptions(query: string) => Promise<ReadonlyArray<SelectOption<T>>>—Search a server: loader, debounce and stale answers handled.
onSearchChange(query: string) => void—Called once typing pauses, to search yourself.
searchPromptstring'Type to search'Shown before the user types, while a searched list has no options.
searchDebouncenumber300ms after the last keystroke before loadOptions / onSearchChange.
onEndReached() => void—Called near the end of the list, to load more.
loadingbooleanfalseSpinner in place of an empty list, or under the options.
loadingTextstring'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.
emptyTextstring'No results'Empty-state text.
onCreate(text: string) => SelectOption<T> | void—Offer the typed text as a new option when no label matches. Return the option to select it.
createLabel(text: string) => string(text) => `Add "${text}"`The create row's text.
showCheckmarksbooleantrue✓ or radio (single, radio in the Material design) / checkbox (multiple).
isEqual(a: T, b: T) => booleanObject.isValue equality.
listHeightnumber—Fixed height for the scrolling list.
autoFocusSearchbooleanfalseFocus the search on mount.
styleStyleProp<ViewStyle>—Container style.
stylesSlotStyles<SelectSlot>—Slots below.
themeDeepPartial<Theme>—Theme override.
design'brand' | 'ios' | 'material' | 'web' | 'native'from PatineProviderThe look to follow, over the provider's: brand, iOS, Material or web, or 'native' for the platform's own.
testIDstring—Test ID.

Slots​

SlotElement
containerOuter view
searchSearch field wrapper
searchInputThe TextInput
listThe FlatList
groupHeader / groupHeaderTextSection header
optionEach row
selectedOptionSelected rows (merged after option)
optionLabel / selectedOptionLabelRow label
optionDescriptionSecond line
check✓, radio or checkbox
empty / emptyTextEmpty state, and the searchPrompt
loading / loadingTextLoader row / its text
createOption / createOptionLabelThe Add "…" row / its text

Types​

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