react-native-picker-select

A Picker component for React Native which emulates the native <select> interfaces for iOS and Android

For iOS, by default we are wrapping an unstyled TextInput component. You can then pass down styles to customize it to your needs.

For Android, by default we are using the native Picker component. If you prefer, you can set useNativeAndroidPickerStyle to false, which will also render an unstyled TextInput component. You can then pass down styles to customize it to your needs.

For either platform, you can alternatively pass down a child element of your choice that will be wrapped in a touchable area.

View examples on snack.expo.io

Getting Started

Installing

This package is built around and depends on @react-native-picker/picker. Please make sure you install it correctly (as seen below in installation steps).

npm install react-native-picker-select

# React Native users
npm install @react-native-picker/picker
npx pod-install

# Expo
expo install @react-native-picker/picker

Basic Usage

import RNPickerSelect from 'react-native-picker-select';

export const Dropdown = () => {
  return (
    <RNPickerSelect
      onValueChange={(value) => console.log(value)}
      items={[
        { label: 'Football', value: 'football' },
        { label: 'Baseball', value: 'baseball' },
        { label: 'Hockey', value: 'hockey' },
      ]}
    />
  );
};

Versioning

Props

Styling

All properties mentioned below must be nested under the style prop. Examples of different styling options can be found on the example snack.

iOS-specific

• The component wraps a TextInput without styling. You can target the TextInput styling with inputIOS.
• Other styles that can be modified for iOS are named inputIOSContainer, placeholder, viewContainer, chevronContainer, chevron, chevronUp, chevronDown, chevronActive, done, modalViewTop, modalViewMiddle, and modalViewBottom

Android-specific

• The native Picker in its inactive state acts looks similar to a TextInput, but it has limitations on custom styling. Any styling that is possible can be applied via inputAndroid.
• You can add some styling customization to the active-state native Picker, but that requires modifying some xml files
• If you set the prop useNativeAndroidPickerStyle to false, the component will allow a few other style objects: inputAndroidContainer, placeholder, and inputAndroid
• Other styles that can be modified for Android are named headlessAndroidContainer and viewContainer

Web-specific

• The component creates a select tag
• The styling of this select tag can be modified using a nested object with the key inputWeb

Icon

• If a component is passed in via the Icon prop - it will be rendered with { position: 'absolute', right: 0 } applied to its wrapping container. You can modify these values and add additional spacing to position the icon as needed by modifying iconContainer. You'll probably also want to add some paddingRight to your input styling to avoid any longer text appearing behind the icon.
• You can pass a component of your choosing (css, image, svg, etc..) for use as the icon. For ease of use, consider a library such as react-native-shapes or react-native-vector-icons.
• Examples of different icons and their usage can be found on the example snack.

Accessibility

If you need to add accessibility props to the rendered component, you may use pickerProps and touchableWrapperProps to pass these through.

pickerProps accepts an object of props that get passed directly to the native <Picker /> component. touchableWrapperProps also accepts an object of props, but this gets passed to a <TouchableOpacity /> that toggles the visibility of the picker.^{*note: touchableWrapperProps is not supported on web or when useNativeAndroidPickerStyle={true}}

Accessibility Example

In the example below, we render the picker with supplementary description text, but for screen readers, we omit this by passing just the title to the accessibilityLabel prop.

const selectedItem = {
  title: 'Selected item title',
  description: 'Secondary long descriptive text ...',
};

export const Dropdown = () => {
  return (
    <RNPickerSelect
      pickerProps={{
        accessibilityLabel: selectedItem.title,
      }}
    >
      <Text>{selectedItem.title}</Text>
      <Text>{selectedItem.description}</Text>
    </RNPickerSelect>
  );
};

Testing

Test suite included. This component has been used and tested since React Native v0.51.

License

react-native-picker-select is MIT licensed and built with :heart: in Austin, TX by the team at LawnStarter