Home

Awesome

react-native-modal-selector npm version

A cross-platform (iOS / Android), selector/picker component for React Native that is highly customizable and supports sections.

This project is the official continuation of the abandoned react-native-modal-picker repo. Contributors are welcome to request a promotion to collaborator status.

Demo

<img src="https://github.com/peacechen/react-native-modal-selector/blob/master/docs/demo.gif" />

Install

npm install react-native-modal-selector

Usage

You can either use this component in its default mode, as a wrapper around your existing component or provide a custom component (where you need to control opening of the modal yourself). In default mode a customizable button is rendered.

See SampleApp for an example how to use this component.

import ModalSelector from 'react-native-modal-selector'

class SampleApp extends Component {

    constructor(props) {
        super(props);

        this.state = {
            textInputValue: ''
        }
    }

    render() {
        let index = 0;
        const data = [
            { key: index++, section: true, label: 'Fruits' },
            { key: index++, label: 'Red Apples' },
            { key: index++, label: 'Cherries' },
            { key: index++, label: 'Cranberries', accessibilityLabel: 'Tap here for cranberries' },
            // etc...
            // Can also add additional custom keys which are passed to the onChange callback
            { key: index++, label: 'Vegetable', customKey: 'Not a fruit' }
        ];

        return (
            <View style={{flex:1, justifyContent:'space-around', padding:50}}>

                // Default mode
                <ModalSelector
                    data={data}
                    initValue="Select something yummy!"
                    onChange={(option)=>{ alert(`${option.label} (${option.key}) nom nom nom`) }} />

                // Wrapper
                <ModalSelector
                    data={data}
                    initValue="Select something yummy!"
                    supportedOrientations={['landscape']}
                    accessible={true}
                    scrollViewAccessibilityLabel={'Scrollable options'}
                    cancelButtonAccessibilityLabel={'Cancel Button'}
                    onChange={(option)=>{ this.setState({textInputValue:option.label})}}>

                    <TextInput
                        style={{borderWidth:1, borderColor:'#ccc', padding:10, height:30}}
                        editable={false}
                        placeholder="Select something yummy!"
                        value={this.state.textInputValue} />

                </ModalSelector>

                // Custom component
                <ModalSelector
                    data={data}
                    ref={selector => { this.selector = selector; }}
                    customSelector={<Switch onValueChange={() => this.selector.open()} />}
                />
            </View>
        );
    }
}

Data Format

The selector accepts a specific format of data:

[{ key: 5, label: 'Red Apples' }]

Optionally provide a component key which overrides the default label text. Optionally provide a unique testID for each item:

[{
  key: 5,
  label: 'Red Apples',
  // The next keys are optional --
  component: <View style={{backgroundColor: 'red'}}><Text style={{color: 'white'}}>Red Apples custom component ☺</Text></View>,
  testID: '5-red-apples'
}]
<img src="https://user-images.githubusercontent.com/6295083/51210593-d3fbae00-18d8-11e9-8f51-d1ca4f9f8267.png" />

If your data has a specific format, you can define extractors of data, example:

this.setState({data: [{ id: 5, name: 'Red Apples' }]});

return (
  <ModalSelector
    data={this.state.data}
    keyExtractor= {item => item.id}
    labelExtractor= {item => item.name}
  />
);

API

Props

PropTypeOptionalDefaultDescription
dataarrayNo[]array of objects with a unique key and label to select in the modal. Optional component overrides label text. Optional unique testID for each item.
onChangefunctionYes() => {}callback function, when the users has selected an option
onModalOpenfunctionYes() => {}callback function, when modal is opening
onModalClosefunctionYes(item) => {}callback function, when modal is closing. Returns the selected item.
keyExtractor     functionYes    (data) => data.key  extract the key from the data item
labelExtractor   functionYes    (data) => data.labelextract the label from the data item
componentExtractorfunctionYes    (data) => data.componentextract the component from the data item
visibleboolYesfalsecontrol open/close state of modal
closeOnChangeboolYestruecontrol if modal closes on select
initValuestringYesSelect me!text that is initially shown on the button
cancelTextstringYescanceltext of the cancel button
disabledboolYesfalsetrue disables opening of the modal
supportedOrientations['portrait', 'landscape']Yesbothorientations the modal supports
keyboardShouldPersistTapsstring / boolYesalwayspassed to underlying ScrollView
listTypestringYesSCROLLVIEWscroller type: SCROLLVIEW or FLATLIST
animationTypestringYesslidetype of animation to be used to show the modal. Must be one of none, slide or fade.
styleobjectYesstyle definitions for the root element
childrenContainerStyleobjectYes{}style definitions for the children container view
touchableStyleobjectYes{}style definitions for the touchable element
touchableActiveOpacitynumberYes0.2opacity for the touchable element on touch
selectStyle      object  Yes    {}        style definitions for the select element (available in default mode only!). NOTE: Due to breaking changes in React Native, RN < 0.39.0 should pass flex:1 explicitly to selectStyle as a prop.
selectTextStyleobjectYes{}style definitions for the select element (available in default mode only!)
overlayStyleobjectYes{ flex: 1, padding: '5%', justifyContent: 'center', backgroundColor: 'rgba(0,0,0,0.7)' }style definitions for the overlay background element. RN <= 0.41 should override this with pixel value for padding.
sectionStyleobjectYes{}style definitions for the section element
sectionTextStyleobjectYes{}style definitions for the select text element
selectedItemTextStyleobjectYes{}style definitions for the currently selected text element
optionStyleobjectYes{}style definitions for the option element
optionTextStyleobjectYes{}style definitions for the option text element
optionContainerStyleobjectYes{}style definitions for the option container element
cancelStyleobjectYes{}style definitions for the cancel element
cancelTextStyleobjectYes{}style definitions for the cancel text element
initValueTextStyleobjectYes{}style definitions for the initValue text element
cancelContainerStyleobjectYes{}style definitions for the cancel container
backdropPressToCloseboolYesfalsetrue makes the modal close when the overlay is pressed
passThruPropsobjectYes{}props to pass through to the container View and each option TouchableOpacity (e.g. testID for testing)
selectTextPassThruPropsobjectYes{}props to pass through to the select text component
optionTextPassThruPropsobjectYes{}props to pass through to the options text components in the modal
cancelTextPassThruPropsobjectYes{}props to pass through to the cancel text components in the modal
scrollViewPassThruPropsobjectYes{}props to pass through to the internal ScrollView
openButtonContainerAccessibleboolYesfalsetrue enables accessibility for the open button container. Note: if false be sure to define accessibility props directly in the wrapped component.
listItemAccessibleboolYesfalsetrue enables accessibility for data items. Note: data items should have an accessibilityLabel property if this is enabled
cancelButtonAccessibleboolYesfalsetrue enables accessibility for cancel button.
scrollViewAccessibleboolYesfalsetrue enables accessibility for the scroll view. Only enable this if you don't want to interact with individual data items.
scrollViewAccessibilityLabelstringYesundefinedAccessibility label for the modal ScrollView
cancelButtonAccessibilityLabelstringYesundefinedAccessibility label for the cancel button
modalOpenerHitSlopobjectYes{}How far touch can stray away from touchable that opens modal (RN docs)
customSelectornodeYesundefinedRender a custom node instead of the built-in select box.
selectedKeyanyYes''Key of the item to be initially selected
enableShortPressboolYestrueenables short press. This is regular touch behavior.
enableLongPressboolYesfalseenables long press. When true, onModalOpen returns {longPress: true}
optionsTestIDPrefixstringYes'default'This prefixes each selectable option's testID prop if no testID keys are provided in props.data array objects. Default for each option's testID: 'default-<optionLabel>'
headernodeYesundefinedRender a header above the list
onEndReachedfunctionYesundefinedCalled once when the scroll position gets of the rendered content.

Methods

See also