react-native-dropdown-picker: one controlled component for every list in a mobile form

A fully controlled component, which is the whole API

The basic usage example in the README is worth reading as a design statement. The component takes open, value, items, setOpen, setValue and setItems, and it also takes a placeholder. There is no internal selection state that you have to query, and no imperative handle.

import DropDownPicker from 'react-native-dropdown-picker';

const [open, setOpen] = useState(false);
const [value, setValue] = useState(null);
const [items, setItems] = useState([
    {label: 'Apple', value: 'apple'},
    {label: 'Banana', value: 'banana'},
    {label: 'Pear', value: 'pear'},
]);

So the parent owns the state, and the component renders it. The open flag is a boolean the parent holds, the value is the parent state, and the item list is a setter the parent can also modify while the dropdown is open, which is what you need for cascading selects where choosing a country changes the list of cities.

This is a deliberate difference from the picker components that ship with the platform. A controlled component is more code at the call site and much easier to compose with a form library, because the form owns the field value and the picker is just a view of it.

The data shape is simple and worth noting. Each item is an object with a label and a value, and the label is what the user reads while the value is what your code receives. That separation is what lets the label be a translated string while the value stays a stable identifier, which is the hook the localisation support hangs on.

Search, categories and parent items, and what the screenshots show

The feature list in the package description is unusually long for a picker, and it names the capabilities: single or multiple, categorizable, customizable, localizable and searchable. The keyword list in package.json repeats them and adds more, including theme, placeholder, sub-item, context, rtl and rtl-support.

Categories are the feature that distinguishes it from a plain list. The screenshots in the README show a basic dropdown, a variant with badges, and a dark theme variant with parent items. Parent items are the mechanism behind the categorizable behaviour: a top level row can open a sub-list rather than select a value, so a country picker can list continents that expand into countries.

Search is the other capability that changes what the component is for. A dropdown with a text filter is a different widget from a dropdown, because the user can narrow a hundred options without scrolling, and a hundred options is where a native picker starts to feel bad.

The screenshots were taken from a working Expo example hosted on Snack, which is a useful detail for judging the component. The three images show a real rendered app rather than a storybook, and the dark theme screenshot with parent items shows two of the more involved features together, which is where a component like this either holds up or falls apart.

What is not in the README is a description of the styling API in detail. The theme support is real, the dark theme screenshot proves it, but the specific props and how the theme is structured are documented on the separate usage documentation site rather than here.

Two peer dependencies that have to be there first

The dependency list in package.json is short and worth reading closely, because both entries are native modules with their own installation requirements.

"dependencies": {
  "react-native-gesture-handler": "~2.13.1",
  "react-native-safe-area-context": "^5.6.1"
}

react-native-gesture-handler is what the dropdown uses to handle the pan and scroll gestures inside the list, and react-native-safe-area-context is what lets the dropdown position itself correctly around notches, rounded corners and the home indicator. The second one is a functional requirement rather than a nicety: without safe area information, a dropdown that opens downwards on a device with a home indicator can render underneath it.

In a React Native app both are native modules that need to be linked into the native project, not just present in package.json. That is the main practical cost of adopting this library, and it is a cost that arrives before you write a line of picker code.

The other side of the dependency picture is what is not there. There is no icon library, no date library, no utility library, no styling framework. The component renders with React Native primitives, and the requirements are limited to the two gesture and layout modules. For a component that sits in a form and therefore in the visual centre of your product, a minimal dependency list is a genuine advantage, because there is no style system to reconcile with your own and no transitive package to audit.

The examples project is the real documentation

The README points at the examples subdirectory and calls it what it is: a working Expo project demonstrating the library. Navigate into it, run npm install, and then run npx expo start to see the examples working.

What that project covers is the part most component READMEs skip. It shows how to use the library with class components as well as with function components, and in TypeScript as well as in JavaScript. That is a short list but it covers the two axes that actually break. A dropdown that works only with hooks is not usable in a class based codebase, and a component whose types only exist in TypeScript is awkward in a JavaScript one.

The examples directory in the repository confirms it. It holds App.tsx, app.json for the Expo configuration, a babel.config.js, a tsconfig.json, an assets folder, an example-src-files folder and its own package.json and package-lock.json. It is a separate npm project rather than a folder of snippets, which means the examples are compiled and run rather than pasted.

The repository root also carries index.js and index.d.ts, which is the CommonJS entry point and the TypeScript declarations, and the package.json points main at index.js and types at index.d.ts. So a TypeScript project gets the types without a separate DefinitelyTyped package, and the build configuration is a tsconfig.json at the root.

For further detail the project points to a usage documentation page, and the docs site itself lives in a separate repository, hossein-zare/react-native-dropdown-picker-website, which means the documentation is edited and versioned independently of the component.

A release line that has not moved since 2023, and a branch that is not master

The version information here needs care, because there are two different things in play.

The package.json says version 5.5.1. The newest tagged releases listed are v5.4.6 from 2023-03-09, v5.4.4 from 2022-12-20 and v5.4.3 from 2022-11-12. So the version in the source tree is ahead of the last tag, and the tags themselves are old.

Meanwhile the default branch is dev-5.x, not master. The build badge in the README points at the dev-5.x branch, the MIT badge and the CONTRIBUTING link both point at dev-5.x, and the raw image URLs for the screenshots use dev-5.x as well. The whole development line of this project is a version prefixed branch, which is a pattern used when a major version is still in progress and the branch carries the next major.

The last push to the repository was on 2026-06-28, and the repository is not archived. So the code is still being touched, but the released artefacts on npm are what most people install, and the relationship between the branch and the published package is not something the README explains.

For an adopter this is the practical risk to price in. If you pin a version from npm, you are pinning code from before the current branch, and you should read the changelog between your version and the branch head if you need a behaviour that was fixed after your version shipped. The repository also carries a CONTRIBUTING guide at its root that is the entry point for anyone who wants to help.

When a dropdown is the wrong tool, and what to use instead

A picker component is only one way to present a set of options, and it is worth saying when it is the wrong one.

The first case is a long list that the user needs to search. A dropdown with a search field is a reasonable answer up to a few dozen options, but a searchable list rendered as a full screen or an inline list is faster to use, because there is no mode switch between browsing and typing. If your data set is large enough that the filter matters, a dedicated search list is a better widget.

The second case is a handful of options. If there are three choices, a segmented control or a radio group is clearer than a dropdown, and it removes the extra tap. The component's own example uses three fruits, which is a good size for a demo and a poor size for a real form.

The third case is a value that must be visible while editing. A dropdown hides the available options, so a form with several dependent dropdowns is a form the user has to remember. Where space allows, radio groups or a list of choices keep everything visible.

The comparison with the platform pickers is straightforward. This component gives you all of those and stays inside your design system, at the cost of the two native dependencies and the fact that you now own the accessibility behaviour of the list.

Editorial conclusion

react-native-dropdown-picker fits a React Native team that needs a dropdown with search, categories and theming on both platforms without writing a modal, and it fits teams whose forms already hold their own state and want the picker to stay a controlled component. It does not fit a project that needs a component with no peer dependencies, because the package depends on react-native-gesture-handler and react-native-safe-area-context, and it does not fit a team that needs a maintained npm release line. Check three things before you commit. Check the release you will actually install, because the package version in the repository is 5.5.1 while the newest tagged release listed is v5.4.6 from 2023-03-09, so the npm tag and the source tree are not the same thing. Check your peer dependency situation, since gesture handler and safe area context have to be installed and linked in a React Native app before this component will behave. And check the examples project, which is a working Expo app covering class components, function components, TypeScript and JavaScript, and is the fastest way to see the component in the state you will use it. The last push was on 2026-06-28 and the license is MIT.

Frequently asked questions

Official sources

1. hossein-zare/react-native-dropdown-picker on GitHub
2. License: MIT
3. Project website
4. README
5. Releases