React Native Flexible Dropdown

A lightweight, TypeScript-first dropdown library for React Native CLI and Expo. Version 1.0.0 is prepared as the initial npm release source.

Features

• Single-select and multi-select components
• Three presentation modes: popover, bottom-sheet, and fullscreen
• Light, dark, and automatic system themes
• Customizable option rows: descriptions, leading/trailing text, row colors, and custom row renderers
• Search, disabled options, clear selection, helper/error text, and multi-select limits
• Zero additional runtime dependencies beyond React and React Native
• No native linking required

Install

Once published:

npm install react-native-flexible-dropdown

Single-select example

import React, { useState } from 'react';
import { Dropdown, type DropdownOption } from 'react-native-flexible-dropdown';

const countries: DropdownOption<string>[] = [
  { label: 'Pakistan', value: 'pk', description: 'PK', leadingText: '🇵🇰' },
  { label: 'United States', value: 'us', description: 'US', leadingText: '🇺🇸' },
  { label: 'Canada', value: 'ca', disabled: true },
];

export function CountryPicker() {
  const [country, setCountry] = useState<string | null>(null);

  return (
    <Dropdown
      label="Country"
      options={countries}
      value={country}
      onChange={(nextValue) => setCountry(nextValue)}
      presentation="bottom-sheet"
      theme="system"
      searchable
      clearable
    />
  );
}

Multi-select example

import React, { useState } from 'react';
import { MultiSelectDropdown } from 'react-native-flexible-dropdown';

const skills = [
  { label: 'React Native', value: 'rn', description: 'Mobile apps' },
  { label: 'TypeScript', value: 'ts', trailingText: 'Popular' },
  { label: 'Node.js', value: 'node' },
];

export function SkillsPicker() {
  const [selected, setSelected] = useState<string[]>([]);

  return (
    <MultiSelectDropdown
      label="Skills"
      options={skills}
      value={selected}
      onChange={(values) => setSelected(values)}
      maxSelected={3}
      presentation="fullscreen"
      theme="system"
      searchable
    />
  );
}

Presentation modes

<Dropdown {...props} presentation="popover" />
<Dropdown {...props} presentation="bottom-sheet" />
<Dropdown {...props} presentation="fullscreen" />

• popover: options panel appears below the field in the current layout.
• bottom-sheet: modal sheet slides up over a dimmed backdrop. Default mode.
• fullscreen: full-screen selector with search and Cancel action.

All three modes are available on both components.

Themes

<Dropdown {...props} theme="system" />
<Dropdown {...props} theme="light" />
<Dropdown {...props} theme="dark" />

system follows the device appearance. You can customize theme colors:

<Dropdown
  {...props}
  theme="dark"
  colors={{
    background: '#101828',
    surface: '#1D2939',
    text: '#F9FAFB',
    secondaryText: '#D0D5DD',
    accent: '#A6F4C5',
    selectedBackground: '#123B2A',
  }}
/>

Custom rows

Option objects can include label, value, disabled, description, leadingText, trailingText, labelColor, and backgroundColor.

For a fully custom row layout:

<Dropdown
  {...props}
  renderOption={(option, selected) => (
    <MyCustomOptionRow option={option} selected={selected} />
  )}
/>

Documentation

• docs/USAGE.md: integration guide and API overview.
• docs/AI_PROMPTS.md: prompts for AI coding assistants.

License

MIT. See LICENSE.