react-native-smart-dropdown

react-native-smart-dropdown

Production-ready React Native dropdown / select with smart positioning, search, multi-select, and a full theming system. Zero runtime dependencies. TypeScript-first.

npm · GitHub · Issues · Interactive demo · Full video tour

Preview

Highlights from the interactive demo on Android and iOS:

Android

Selection (single + multi)	Multi-select · searchable	Inline + keyboard-aware

iOS

Create new / taggable	Multi-select · searchable

Watch all 32 demos on YouTube — full walkthrough of every feature in the demo app.

Features

• Single & multi-select — controlled or uncontrolled; multi shows a count or removable chips (with +N more overflow).
• Search — local, remote (debounced + race-safe), or hybrid; optional pagination (infinite scroll) and load-on-open.
• Autocomplete — trigger-as-search combobox; create-new / taggable items.
• Smart positioning — auto up/down, keyboard-aware, edge-clamped; floating Modal or inline (in-flow) render.
• Rich rows — section grouping, disabled items, subtitle + avatar, fully custom renderItem.
• Forms — label / required / helperText / error (reddens the border); minSelections / maxSelections + validity callback.
• Theming — partial theme override, light/dark (colorScheme), custom fonts (iOS-safe, family-based), RTL, custom icons.
• Control — renderTrigger, controlled open, imperative ref, animated open/close.
• Scale & web — virtualized inline lists, getItemLayout, keyboard navigation (↑/↓/Enter/Esc) + hover.

Install

npm install react-native-smart-dropdown
# or
yarn add react-native-smart-dropdown

Peer deps: react >= 18, react-native >= 0.72. MIT license · 90 tests · ~75 kB packed · zero runtime dependencies.

Interactive demo (32 cards)

The repo includes DropdownDemo — 32 runnable cards, one feature per card:

Category	Demos
SELECTION	7
SEARCH	7
LIST CONTENT	4
FORM FIELD	1
THEMING & ICONS	5
POSITIONING & RENDER	7
STATES	1
Total	32

Run locally from example/DropdownDemo, or watch the full video tour on YouTube.

Quick start

import React from 'react';
import { DropdownSelect } from 'react-native-smart-dropdown';

type Fruit = { id: number; label: string };
const FRUITS: Fruit[] = [
  { id: 1, label: 'Apple' },
  { id: 2, label: 'Banana' },
];

function Example() {
  const [value, setValue] = React.useState<Fruit | null>(null);
  return (
    <DropdownSelect<Fruit>
      items={FRUITS}
      labelKey="label"
      valueKey="id"
      value={value}
      onChange={setValue}
      placeholder="Pick a fruit"
    />
  );
}

Recipes

Multi-select · chips + search

<DropdownSelect<Fruit>
  mode="multi"
  multiDisplay="chips"
  isSearch
  searchInTrigger
  searchMode="local"
  items={FRUITS}
  labelKey="label"
  valueKey="id"
  selectedValues={selected}
  onChangeMulti={setSelected}
  placeholder="Type to search, pick several"
/>

Search query clears after each pick by default. Pass persistSearchOnSelect to keep it.

Multi-select · chips + search (with cap)

<DropdownSelect<Fruit>
  mode="multi"
  multiDisplay="chips"
  maxVisibleChips={3}        // extras collapse into "+N more"
  isSearch
  searchInTrigger
  searchMode="local"
  items={FRUITS}
  labelKey="label"
  valueKey="id"
  selectedValues={selected}
  onChangeMulti={setSelected}
  placeholder="Pick several"
/>

Select-all · min/max validation

<DropdownSelect<Fruit>
  mode="multi"
  multiDisplay="chips"
  showSelectAll               // header toggles Select all ↔ Clear all
  minSelections={1}
  maxSelections={3}
  onValidityChange={setValid}
  items={FRUITS} labelKey="label" valueKey="id"
  selectedValues={sel} onChangeMulti={setSel}
/>

Remote search · pagination · load on open

<DropdownSelect<Item>
  isSearch
  searchInTrigger
  searchMode="remote"
  loadOnOpen                  // fetch first page when opened
  minSearchLength={0}
  enablePagination
  pageSize={20}
  fetchData={(text, page) => api.search(text, page)}
  renderLoading={() => <MySkeleton />}
  items={[]} labelKey="label" valueKey="id"
/>

Hybrid search (local + remote)

<DropdownSelect<Item>
  isSearch
  searchInTrigger
  searchMode="hybrid"           // local matches first, remote merged in
  minSearchLength={1}
  fetchData={(text, page) => api.search(text, page)}
  items={LOCAL_ITEMS}             // seed list for instant local matches
  labelKey="label" valueKey="id"
/>

Create new / taggable

<DropdownSelect<Item>
  isSearch searchInTrigger searchMode="local"
  allowCreate
  onCreateOption={(text) => ({ id: Date.now(), label: text })}
  items={items} labelKey="label" valueKey="id"
  value={value} onChange={setValue}
/>

Grouped · disabled · subtitle + avatar

<DropdownSelect<User>
  items={users} labelKey="name" valueKey="id"
  groupBy={(u) => u.team}
  isItemDisabled={(u) => !u.active}
  descriptionKey={(u) => u.email}
  imageKey={(u) => u.avatarUrl}
/>

Form field (label / required / error)

<DropdownSelect<Fruit>
  label="Favorite fruit"
  required
  error={value ? undefined : 'This field is required'}
  items={FRUITS} labelKey="label" valueKey="id"
  value={value} onChange={setValue}
/>

Theming · dark · custom font · RTL

<DropdownSelect<Fruit>
  theme={{ colors: { accent: '#0a7', chipBg: '#0a7' }, radii: { md: 14 } }}
  colorScheme="dark"                          // 'system' | 'light' | 'dark'
  // iOS-safe: family-only per weight (NO fontWeight when a custom family is set)
  // theme={{ fonts: { regular: 'Inter-Regular', bold: 'Inter-Bold' } }}
  rtl                                         // mirror layout + right-align (Arabic/Hebrew)
  items={FRUITS} labelKey="label" valueKey="id"
/>

Fonts on iOS: iOS ignores fontWeight on a custom fontFamily — the weight is baked into the font file. So set per-weight families (Inter-Regular / Inter-Medium / Inter-Bold) via theme.fonts; the library never emits fontWeight alongside a custom family.

Custom trigger · controlled open

import { Pressable, Text } from 'react-native';

<DropdownSelect<Fruit>
  open={open}
  onOpenChange={setOpen}
  renderTrigger={({ toggle, label, placeholder, isOpen }) => (
    <Pressable onPress={toggle}>
      <Text>{label || placeholder} {isOpen ? '▲' : '▼'}</Text>
    </Pressable>
  )}
  items={FRUITS} labelKey="label" valueKey="id"
/>

Inline · virtualized (large lists)

<DropdownSelect<Item>
  inline
  scrollRef={scrollRef}        // the host ScrollView ref
  virtualizeInline             // windowed FlatList for big inline lists
  itemHeight={44}              // enables getItemLayout (uniform rows)
  items={bigList} labelKey="label" valueKey="id"
/>

Full prop reference

Every prop on <DropdownSelect<T>>, grouped. Optional unless marked required. See the DropdownDemo app for 32 runnable demos (one per feature).

Data

Prop	Type	Default	Notes
items	T[]	—	required. Option list.
labelKey	keyof T | (item: T) => string	tries label/name	how to read the display label
valueKey	keyof T | (item: T) => string | number	tries value/id	how to read the unique id
keyExtractor	(item, index) => string	from valueKey	list key override
descriptionKey	keyof T | (item: T) => string	—	secondary line (subtitle) per row
imageKey	keyof T | (item: T) => string	—	left avatar image URI per row
renderRowLeft	(item) => ReactNode	—	custom left accessory per row (overrides imageKey)

Selection

Prop	Type	Default	Notes
mode	'single' | 'multi'	'single'
value / onChange	T | null / (item|null) => void	—	single, controlled
defaultValue	T | null	—	single, uncontrolled
selectedValues / onChangeMulti	T[] / (items) => void	—	multi, controlled
defaultSelectedValues	T[]	—	multi, uncontrolled
multiDisplay	'count' | 'chips'	'count'	multi trigger display
maxVisibleChips	number	—	cap chips → "+N more" pill
maxSelections	number	—	cap multi selections
minSelections	number	—	block deselect below this
onValidityChange	(valid: boolean) => void	—	fires when min/max/required validity changes
includeSelectedInList	boolean	true	inject selected value not present in items
closeOnSelect	boolean	single true / multi false	close after a pick

Search

Prop	Type	Default	Notes
isSearch	boolean	false	enable search
searchMode	'none' | 'local' | 'remote' | 'hybrid'	'none'
searchInTrigger	boolean	false	trigger itself is the search input (autocomplete)
searchPlaceholder	string	'Search…'
autoFocusSearch	boolean	false	focus search on open
minSearchLength	number	0	min chars before remote fetch
searchDebounceMs	number	400	remote debounce
filterFunction	(item, text) => boolean	substring on label	local filter override
onSearchTextChange	(text) => void	—	observe query
fetchData	(text, page?) => Promise<T[]>	—	remote/hybrid fetch
enablePagination	boolean	false	infinite scroll (remote/hybrid)
pageSize	number	—	page size for last-page detection
loadOnOpen	boolean	false	fetch first page on open
persistSearchOnSelect	boolean	false	keep query after a pick

List content

Prop	Type	Default	Notes
groupBy	(item) => string	—	section grouping
renderSectionHeader	(group) => ReactNode	styled label	custom section header
isItemDisabled	(item) => boolean	—	greyed, non-selectable rows
allowCreate	boolean	false	show "Add …" for unmatched query
onCreateOption	(text) => T	—	build a new item (required for allowCreate)
createOptionLabel	(text) => string	Add "<text>"	create-row label
showSelectAll	boolean	false	select-all / clear-all header (multi)
selectAllText / clearAllText	string	'Select all' / 'Clear all'
highlightSelected	boolean	true	highlight selected rows
autoScrollToSelected	boolean	true	scroll to selection on open

Form field

Prop	Type	Default	Notes
label	string	—	label above the trigger
required	boolean	false	adds a *
helperText	string	—	helper below (hidden when error set)
error	string	—	error text + reddens the trigger border
labelStyle / helperTextStyle	StyleProp<TextStyle>	—

Trigger appearance & icons

Prop	Type	Default	Notes
placeholder	string	'Select…'
disabled	boolean	false
triggerStyle / triggerTextStyle / placeholderStyle	StyleProp	—
chipStyle / chipTextStyle	StyleProp	—	multi chips
caretUpIcon / caretDownIcon / clearIcon / leftIcon	ReactNode	▲ ▼ ✕	any node (svg/Image/vector/text)
leftIconStyle	StyleProp<ViewStyle>	—	left-icon slot
showRightAccessory	boolean	true	show the caret
isClearable	boolean	true	show the clear ✕
showClearOnlyWhenHasValue	boolean	true	hide clear when empty
openOnClear	boolean	false	reopen after clearing

Theming

Prop	Type	Default	Notes
theme	DeepPartial<DropdownTheme>	—	partial token override (see below)
colorScheme	'system' | 'light' | 'dark'	'system'	base palette
rtl	boolean	I18nManager.isRTL	mirror layout + right-align text

Positioning & sizing

Prop	Type	Default	Notes
direction	'up' | 'down' | 'auto'	'auto'	open direction
allowDirectionFallback	boolean	true	flip if the chosen side lacks space
listHeight	number	280	requested panel height
minListHeight / maxListHeight	number	0 / —	clamp
autoAdjustHeight	boolean	true	shrink/grow to available space
shrinkToContent	boolean	true	fit to actual content height
edgeMargin	number	8	min gap from screen edges

Render mode & behavior

Prop	Type	Default	Notes
inline	boolean	false	in-flow panel instead of floating Modal
scrollRef	RefObject	—	host ScrollView ref (inline keyboard-reveal)
virtualizeInline	boolean	false	windowed FlatList for big inline lists
itemHeight	number	—	fixed row height → getItemLayout
animated	boolean	false	LayoutAnimation on open/close + chips
open / onOpenChange	boolean / (open: boolean) => void	—	controlled open state
showOverlay	boolean	false	dim backdrop when true (Modal mode)
overlayColor	string	theme overlay	backdrop color
closeOnOutsidePress	boolean	true	tap-outside closes
initialNumToRender	number	10	FlatList perf
listProps	Partial<FlatListProps<T>>	—	passthrough to the list

States & render slots

Prop	Type	Default	Notes
loading	boolean	false	parent-controlled loading
emptyText / searchEmptyText / errorText / minSearchText	string	see defaults	empty/error copy
showEmptyAction / emptyActionLabel / onEmptyActionPress	boolean / string / () => void	—	empty-state action button
emptyContainerStyle / emptyTextStyle / emptyActionStyle / emptyActionTextStyle	StyleProp	—
renderEmptyState	(params: EmptyStateParams) => ReactNode	—	fully custom empty state
renderLoading	() => ReactNode	spinner	custom loader
renderTrigger	(params: RenderTriggerParams<T>) => ReactNode	—	fully custom trigger
renderItem	(params: RenderItemParams<T>) => ReactNode	—	fully custom row
renderLeftAccessory / renderRightAccessory / renderClearAccessory	(params: AccessoryParams<T>) => ReactNode	—	accessory slots (win over icon props)

Accessibility / test

Prop	Type	Notes
accessibilityLabel	string	trigger a11y label
testID	string	base testID (children derive <testID>-row-N, -search, -chip-N-remove, …)

Theme tokens (DropdownTheme)

Override any subset via the theme prop.

{
  colors: { surface, text, textMuted, placeholder, inputPlaceholder, border, divider,
            chipBg, onChip, accent, error, overlay, triggerPressed, rowSelected,
            rowPressed, ripple, shadow },
  radii:     { sm, md },
  spacing:   { xs, sm, md, lg },
  fontSizes: { xs, sm, chip, body, input },
  fonts:     { regular?, medium?, bold? },   // family-only; iOS-safe (no fontWeight when set)
  sizes:     { control, row, input },        // auto-scaled 1.2× on tablets/iPad
  rtl: boolean,
}

Public exports

// Component
DropdownSelect

// Types
DropdownSelectProps, DropdownRef, Direction, ResolvedDirection,
SelectionMode, SearchMode, DataStatus,
RenderTriggerParams, RenderItemParams, AccessoryParams, EmptyStateParams

// Theming
lightTheme, darkTheme, mergeTheme, fontFor, textDir, rowDir
DropdownTheme, DropdownColors, DropdownFonts, DeepPartial

// Host integration (ScrollView / outside-tap coordination)
closeOpenDropdowns, markUserTap, subscribeOpen

Host integration (inline + ScrollView)

When using inline mode inside a host ScrollView, wire these helpers so outside taps close the dropdown and you can react to open/close (e.g. lock page scroll while open):

import React from 'react';
import { ScrollView } from 'react-native';
import {
  DropdownSelect,
  markUserTap,
  subscribeOpen,
  closeOpenDropdowns,
} from 'react-native-smart-dropdown';

function FormScreen() {
  const scrollRef = React.useRef<ScrollView>(null);
  const [dropdownOpen, setDropdownOpen] = React.useState(false);

  React.useEffect(() => subscribeOpen(setDropdownOpen), []);

  return (
    <ScrollView
      ref={scrollRef}
      scrollEnabled={!dropdownOpen}
      onScrollBeginDrag={closeOpenDropdowns}
      onTouchStart={markUserTap}
      keyboardShouldPersistTaps="handled">
      <DropdownSelect<Fruit>
        inline
        scrollRef={scrollRef}
        items={FRUITS}
        labelKey="label"
        valueKey="id"
      />
    </ScrollView>
  );
}

• markUserTap — call on the host root onTouchStart; closes inline dropdowns on outside tap (Modal dropdowns use their own backdrop).
• subscribeOpen — fires (open: boolean) whenever any dropdown opens or closes.
• closeOpenDropdowns — imperatively close the open dropdown (e.g. on host scroll).

Only one dropdown stays open at a time — opening another closes the previous one automatically.

Render-prop params

RenderTriggerParams<T> = { isOpen, disabled, hasValue, value, selectedValues,
                           label, placeholder, open, close, toggle, clear }
RenderItemParams<T>    = { item, index, isSelected, onPress }
AccessoryParams<T>     = { hasValue, isOpen, disabled, value, selectedValues }
EmptyStateParams       = { status, searchText, onActionPress? }

Imperative API (ref)

const ref = useRef<DropdownRef>(null);
ref.current?.open();
// DropdownRef: open · close · toggle · clear · focusSearch · blurSearch · remeasure · scrollToSelected

Keyboard & accessibility

Arrow ↑/↓ move the active row, Enter selects, Esc closes (while a search input is focused). Rows expose accessibilityRole / accessibilityState; web gets hover highlighting.

License

MIT · Bhavesh Barot · npm