react-native-material-selectize

A React Native component inspired to Selectize which follows Material Design guidelines.

Examples

Working examples are provided within the project. After downloading it, navigate to any subfolder of examples and run either "npm install" or "yarn".

Features

• Type definitions with Typescript
• Material design guidelines compliance
• Consistent look and feel on iOS and Android
• State transitions (normal, focused and errored)
• Highly customizable styles and props of inner TextInput component
• Pure javascript implementation
• Minimal setup (no props required)

Installation

The easiest way to install it is via npm. You need to have node.js installed.

npm install react-native-material-selectize --save

Alternatively you can use yarn.

yarn add react-native-material-selectize

Properties

| name | description | type | default | | :-------------------- | :---------------------------------------------------------------------------------------------------------------------- | :--------------------------------------- | :---------------------------------------- | | chipStyle | Style of Chip component | Style | - | | chipIconStyle | Style of Chip close icon | Style | - | | containerStyle | Style of the main container component | Style | - | | inputContainerStyle | Style of the input container component | Style | - | | labelStyle | Style of the label text component | Style | - | | listStyle | Style of the dropdown list container | Style | - | | listRowStyle | Style of each row within the list | Style | - | | itemId | Unique identifier for each item object | String | id | | items | Array of objects to populate the list More info | Array | [] | | selectedItems | Array of objects to render chips More info | Array | [] | | label | Text field label text | String | - | | error | Text field error text | String | - | | errorColor | Text field color for errored state | String | rgb(213, 0, 0) | | tintColor | Text field accent color (focus) | String | rgb(0, 145, 234) | | baseColor | Text field base color (blur) | String | rgba(0, 0, 0, .38) | | showItems | Define when dropdown items should be seen | 'always', 'never', 'onFocus', 'onTyping' | 'onFocus' | | autoReflow | Define whether the typed text reflows More info | Boolean | true | | trimOnSubmit | Trim text before creating the Chip | Boolean | true | | renderRow | Return the rendered row of the list | Function | renderRow default | | renderChip | Return the rendered Chip component | Function | renderChip default | | textInputProps | TextInput props More info | Object | - | | middleComponent | A custom component to render between the text input and the item list | Component | - | | filterOnKey | The key to filter on. If not set, the provided itemId is used | String | - | | onChangeSelectedItems | Called when selectedItems changes | Function | (selectedItems) => {} |

items

In general, this array should be consisting of objects having at least one property [itemId] which value is unique for each object. An example of valid input for itemId = 'id' would be:

[
  { id: 'john', email: '[email protected]' },
  { id: 'doe', email: '[email protected]' }
]

An example of invalid input for itemId = 'anotherId' would be:

[
  { anotherId: '1' },
  { anotherId: '1' },
  { id: '2' }
]

It is invalid for two reasons: itemId doesn't appear in every object and there are two objects having same itemId.

If you just need to render a single value for each row in the list and for each Chip, 'items' prop can be represented as simple array of strings, but only if each value is unique:

['john', 'doe']

selectedItems

Same format rules of items

renderRow default

(id, onPress, item, style) => (
  <TouchableOpacity
    activeOpacity={0.6}
    key={id}
    onPress={onPress}
    style={[styles.listRow, style]}>
    <Text style={{ color: 'rgba(0, 0, 0, 0.87)' }}>{id}</Text>
  </TouchableOpacity>
);

| param | description | | :------ | :--------------------------------------------------------------------- | | id | 'itemId' of the row-indexed object contained in 'items', used as 'key' | | onPress | onPress handler that turns the selected row into a Chip | | item | row-indexed object contained in 'items' | | styles | reference to 'listRowStyle' prop |

renderChip default

(id, onClose, item, style, iconStyle) => (
  <Chip
    key={id}
    iconStyle={iconStyle}
    onClose={onClose}
    text={id}
    style={style}
  />
);

| param | description | | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------ | | id | unique key for the Chip, used as 'key' | | onClose | onClose handler for removing the Chip | | item | row-indexed object contained in 'items' if the Chip has been created clicking on a row of the list, OR the value of the TextInput otherwise | | styles | reference to 'chipStyle' prop | | iconStyle | reference to 'chipIconStyle' prop |

textInputProps

Object which contains the props of the inner TextInput component used for filtering the results from the list generated by 'items' prop. Some props are set internally and cannot be changed.

| ignored prop | type | default | | :-------------------- | :------ | :--------------- | | disableFullscreenUI | Boolean | true | | underlineColorAndroid | String | transparent | | value | String | set internally | | selectionColor | String | 'tintColor' prop |

Other props have different default to better cope with the component requirements, but they can be overridden.

| different default prop | type | default | | :--------------------- | :------ | :------ | | autoCapitalize | String | none | | autoCorrect | Boolean | false | | blurOnSubmit | Boolean | false |

The following handler props are wrapped internally and will be invoked if defined. They are called with different parameters than their original counterparts.

| different parameters prop | type | parameters | | :------------------------ | :------- | :----------- | | onChangeText | Function | (text) => {} | | onSubmitEditing | Function | (text) => {} | | onFocus | Function | (text) => {} | | onBlur | Function | (text) => {} |

The following handler props have a special behavior: returning false they prevent the related event dispatch.

| prevent event prop | type | | :----------------- | :------- | | onChangeText | Function | | onSubmitEditing | Function |

Methods

| name | description | returns | | :------------------- | :------------------------------------------ | :----------------------------------------------------------------- | | focus() | Acquire focus | - | | blur() | Release focus | - | | submit() | Transform current text into Chip | - | | getValue() | Get current value of the inner TextInput | String | | getSelectedItems() | Get normalised items transformed into Chips | { result: string[]; entities: { item: { [key: string]: Item } }; } | | clearSelectedItems() | Remove all the Chips | - |

Caveats

• When Selectize is a child of a ScrollView, the ScrollView's keyboardShouldPersistTaps prop must be set to either handled or always for dropdown completion to work properly.

FAQ

How to make list go over all other elements vs pushing them down?

By default the list of rendered items pushes the other elements down. If you want to have an absolute positioned list, it can be achieved in the following way:

• specify a zIndex for the container bigger than its siblings, usually 1 is just ok:

containerStyle: {
  zIndex: 1;
}

• specify an absolute positioning for listStyle:

listStyle: {
  position: 'absolute';
}

Related issue: https://github.com/raynor85/react-native-material-selectize/issues/19

Licence

react-native-material-selectize is MIT licensed.