react-native-autocomplete-dropdown

Dropdown Item picker with search and autocomplete (typeahead) functionality for react native

This is documentation for version 4.x, if you are looking docs for version 3.x, you can find it here

Demo

Run expo snack demo @onmotion/react-native-autocomplete-dropdown

or download the Expo Go app and scan the QR code below

Nav

• react-native-autocomplete-dropdown - Demo - Nav - Installation - Post-install Steps - iOS - Android - Usage - Dataset item format - Example with local Dataset - Example with remote requested Dataset - Playground - Options - Usage with a Modal

Installation

Run:

or

1yarn add react-native-autocomplete-dropdown

or for v3.x

1yarn add react-native-autocomplete-dropdown@3.1.5

Post-install Steps

Make sure react-native-svg is installed. Follow the guide https://github.com/software-mansion/react-native-svg

1yarn add react-native-svg

iOS

Run: npx pod-install for install react-native-svg dependency (if not installed yet).

Android

No additional steps are necessary

Usage

Wrap your root component in AutocompleteDropdownContextProvider from react-native-autocomplete-dropdown as you can see in example

1<AutocompleteDropdownContextProvider>
2    <AppRootOrWhatever/>
3</AutocompleteDropdownContextProvider>

The dropdown position is relative to the AutocompleteDropdownContextProvider, so put this in the right place, it should cover all the screen/modal.

If you have a header component, you can pass an offset. For example with react navigation

1//...
2import { useHeaderHeight } from '@react-navigation/elements';
3//...
4const headerHeight = useHeaderHeight();
5//...
6
7<AutocompleteDropdownContextProvider headerOffset={headerHeight} >
8    <AppRootOrWhatever/>
9</AutocompleteDropdownContextProvider>

import the package

1import { AutocompleteDropdown } from 'react-native-autocomplete-dropdown';

Dataset item format

dataSet property must be an array of objects or null. Object required keys are:

1{
2    id: 'some uniq string id',
3    title: 'list item title'
4}

Example with local Dataset

1const [selectedItem, setSelectedItem] = useState(null);
2
3<AutocompleteDropdown
4  clearOnFocus={false}
5  closeOnBlur={true}
6  closeOnSubmit={false}
7  initialValue={{ id: '2' }} // or just '2'
8  onSelectItem={setSelectedItem}
9  dataSet={[
10    { id: '1', title: 'Alpha' },
11    { id: '2', title: 'Beta' },
12    { id: '3', title: 'Gamma' },
13  ]}
14/>;

Example with remote requested Dataset

1import React, { memo, useCallback, useRef, useState } from 'react'
2import { Button, Dimensions, Text, View, Platform } from 'react-native'
3import { AutocompleteDropdown } from 'react-native-autocomplete-dropdown'
4
5export const RemoteDataSetExample2 = memo(() => {
6  const [loading, setLoading] = useState(false)
7  const [suggestionsList, setSuggestionsList] = useState(null)
8  const [selectedItem, setSelectedItem] = useState(null)
9  const dropdownController = useRef(null)
10
11  const searchRef = useRef(null)
12
13  const getSuggestions = useCallback(async q => {
14    const filterToken = q.toLowerCase()
15    console.log('getSuggestions', q)
16    if (typeof q !== 'string' || q.length < 3) {
17      setSuggestionsList(null)
18      return
19    }
20    setLoading(true)
21    const response = await fetch('https://jsonplaceholder.typicode.com/posts')
22    const items = await response.json()
23    const suggestions = items
24      .filter(item => item.title.toLowerCase().includes(filterToken))
25      .map(item => ({
26        id: item.id,
27        title: item.title,
28      }))
29    setSuggestionsList(suggestions)
30    setLoading(false)
31  }, [])
32
33  const onClearPress = useCallback(() => {
34    setSuggestionsList(null)
35  }, [])
36
37  const onOpenSuggestionsList = useCallback(isOpened => {}, [])
38
39  return (
40    <>
41      <View
42        style={[
43          { flex: 1, flexDirection: 'row', alignItems: 'center' },
44          Platform.select({ ios: { zIndex: 1 } }),
45        ]}>
46        <AutocompleteDropdown
47          ref={searchRef}
48          controller={controller => {
49            dropdownController.current = controller
50          }}
51          // initialValue={'1'}
52          direction={Platform.select({ ios: 'down' })}
53          dataSet={suggestionsList}
54          onChangeText={getSuggestions}
55          onSelectItem={item => {
56            item && setSelectedItem(item.id)
57          }}
58          debounce={600}
59          suggestionsListMaxHeight={Dimensions.get('window').height * 0.4}
60          onClear={onClearPress}
61          //  onSubmit={(e) => onSubmitSearch(e.nativeEvent.text)}
62          onOpenSuggestionsList={onOpenSuggestionsList}
63          loading={loading}
64          useFilter={false} // set false to prevent rerender twice
65          textInputProps={{
66            placeholder: 'Type 3+ letters (dolo...)',
67            autoCorrect: false,
68            autoCapitalize: 'none',
69            style: {
70              borderRadius: 25,
71              backgroundColor: '#383b42',
72              color: '#fff',
73              paddingLeft: 18,
74            },
75          }}
76          rightButtonsContainerStyle={{
77            right: 8,
78            height: 30,
79
80            alignSelf: 'center',
81          }}
82          inputContainerStyle={{
83            backgroundColor: '#383b42',
84            borderRadius: 25,
85          }}
86          suggestionsListContainerStyle={{
87            backgroundColor: '#383b42',
88          }}
89          containerStyle={{ flexGrow: 1, flexShrink: 1 }}
90          renderItem={(item, text) => <Text style={{ color: '#fff', padding: 15 }}>{item.title}</Text>}
91        //   ChevronIconComponent={<Feather name="chevron-down" size={20} color="#fff" />}
92        //   ClearIconComponent={<Feather name="x-circle" size={18} color="#fff" />}
93          inputHeight={50}
94          showChevron={false}
95          closeOnBlur={false}
96          //  showClear={false}
97        />
98        <View style={{ width: 10 }} />
99        <Button style={{ flexGrow: 0 }} title="Toggle" onPress={() => dropdownController.current.toggle()} />
100      </View>
101      <Text style={{ color: '#668', fontSize: 13 }}>Selected item id: {JSON.stringify(selectedItem)}</Text>
102    </>
103  )
104})
105

More examples see at https://github.com/onmotion/react-native-autocomplete-dropdown/tree/main/example

Playground

To play around with the examples, you can run the following commands

1cd example
2yarn install
3yarn pods
4
5yarn ios
6yarn android

Options

Option	Description	Type	Default
dataSet	set of list items	array	null
initialValue	string (id) or object that contain id	string | object	null
loading	loading state	bool	false
useFilter	whether use local filter by dataSet (useful set to false for remote filtering to prevent rerender twice)	bool	true
showClear	show clear button	bool	true
showChevron	show chevron (open/close) button	bool	true
closeOnBlur	whether to close dropdown on blur	bool	false
closeOnSubmit	whether to close dropdown on submit	bool	false
clearOnFocus	whether to clear typed text on focus	bool	true
caseSensitive	whether to perform case-sensitive search	bool	false
ignoreAccents	ignore diacritics	bool	true
trimSearchText	trim the searched text	bool	true
editable	is textInput editable	bool	true
debounce	wait ms before call onChangeText	number	0
suggestionsListMaxHeight	max height of dropdown	number	200
direction	"up" or "down"	string	down + auto calculate
matchFrom	whether match suggestions from start of titles or anywhere in the title. Possible values are "any" or "start"	string	any
bottomOffset	for calculate dropdown direction (e.g. tabbar)	number	0
onChangeText	event textInput onChangeText	function
onSelectItem	event onSelectItem	function
onOpenSuggestionsList	event onOpenSuggestionsList	function
onChevronPress	event onChevronPress	function
onClear	event on clear button press	function
onSubmit	event on submit KB button press	function
onBlur	event fired on text input blur	function
onFocus	event on focus text input	function
renderItem	JSX for render item (item, searchText) => JSX | null if return null then the element will not be displayed	function	item.title
controller	return reference to module controller with methods close, open, toggle, clear, setInputText, setItem	function
containerStyle		ViewStyle
rightButtonsContainerStyle		ViewStyle
suggestionsListContainerStyle		ViewStyle
suggestionsListTextStyle		TextStyle	styles of suggestions list text items
ChevronIconComponent		React.Component	Feather chevron icon
ClearIconComponent		React.Component	Feather x icon
ScrollViewComponent	removed in 2.0.0 based on FlatList	React.Component name	ScrollView that provide suggestions content
EmptyResultComponent	replace the default `` Component on empty result	React.Component
InputComponent	input element component	React.ComponentType	TextInput
emptyResultText	replace the default "Nothing found" text on empty result	string	"Nothing found"
textInputProps	text input props	TextInputProps
flatListProps	props for \ component	FlatListProps\

Usage with a Modal

if you want to use the dropdown in a modal, you need to wrap the dropdown in another AutocompleteDropdownContextProvider inside the modal component

1    <Modal
2        visible={opened}
3        presentationStyle="formSheet"
4        animationType="slide"
5        onRequestClose={() => setOpened(false)}>
6        <SafeAreaView style={{ flex: 1, backgroundColor: 'transparent' }}>
7          <AutocompleteDropdownContextProvider>
8            <View style={{ paddingHorizontal: 20, flex: 1, paddingTop: 20 }}>
9              <AutocompleteDropdown {...props}/>
10            </View>
11          </AutocompleteDropdownContextProvider>
12        </SafeAreaView>
13    </Modal>