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: 'john@gmail.com' },
{ id: 'doe', email: 'doe@gmail.com' }
]
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 = = = => <Text =>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 = = = = = />;
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 aScrollView
, theScrollView
'skeyboardShouldPersistTaps
prop must be set to eitherhandled
oralways
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.