General description

Library is a set of easy to use, customizable components (based on react-native-paper) which can help with building autocomplete/dropdown components.

Getting started

1. Install library

npm install @telenko/react-native-paper-autocomplete --save

2. Import components

import{Autocomplete,FlatDropdown,ModalDropdown,}from"@telenko/react-native-paper-autocomplete";

3. Using Autocomplete with multiple mode

constSomeForm: React.FC=()=>{const[selectedIds,setIds]=useState([]);constoptions=useMemo(()=>[{label: "option 1",value: "1"},{label: "option 2",value: "2"},{label: "option 3",value: "3"},],[]);return(<Autocompletemultiplevalue={selectedIds}onChange={setIds}options={options}/>);};

4. Using Autocomplete with single mode

constSomeForm: React.FC=()=>{const[id,setId]=useState("");constoptions=useMemo(()=>[{label: "option 1",value: "1"},{label: "option 2",value: "2"},{label: "option 3",value: "3"},],[]);return<Autocompletevalue={id}onChange={setId}options={options}/>;};

5. For more examples go to showcase section or checkout stories of storybook

!Note, to run storybook follow such steps:

1. Go to /storybook folder
2. Run: npm run <platrofm> (f.e. npm run android)
3. Expo application of storybook should run

API

1. Autocomplete

   import{Autocomplete}from"@telenko/react-native-paper-autocomplete";

   Autocomplete props:

   multiple

   • Type: boolean
   • Required: false
   • Default: false
   • Description: Sets whether component will work in multiple or single mode

   value

   • Type: string (single mode) | string[] (multiple mode)
   • Required: true
   • Default: "" (single mode) | [] (multiple mode)
   • Description: Sets value of autocomplete

   onChange

   • Type: (v: string) => void (single mode) | (v: string[]) => void (multiple mode)
   • Required: true
   • Default: -
   • Description: Sets value of autocomplete

   renderHelper

   • Type: () => React.ReactElement
   • Required: false
   • Default: -
   • Description: Element will be rendered between host/trigger input and chips (can be useful for validation)

   renderDropdown

   • Type: (props: DropdownProps) => React.ReactElement
   • Required: false
   • Default: uses FlatDropdown for single mode | uses ModalDropdown for multiple mode
   • Description: Renders dropdown component

   renderOption

   • Type: ({ value, label, selected, onSelect }, optionItem) => React.ReactElement
   • Required: false
   • Default: uses inner widget
   • Description: Renders single option inside dropdown

   filterOptions

   • Type: (options: any[], inputV: string) => any[]
   • Required: false
   • Default: local implementation, checks that option label includes query input string
   • Description: Filters options list depending on text input value

   labelExtractor

   • Type: (item: any) => string
   • Required: false
   • Default: item => item.label
   • Description: Gets option view text from option item

   ...Inherits all other common dropdown props

   Multiple mode specific props

   renderSelectedItem

   • Type: ({ value, label, style, onDelete }, optionItem: any) => React.ReactElement
   • Required: false
   • Default: Renders Chip component
   • Description: Renders single selected item (below dropdown)

2. Dropdown

   import{FlatDropdown,// used as default dropdown for single modeModalDropdown,// used as default dropdown for multiple mode}from"@telenko/react-native-paper-autocomplete";

   Dropdown props:

   inputValue

   • Type: string
   • Required: true
   • Description: Value for text input inside dropdown

   options

   • Type: any[]
   • Required: true
   • Description: options list

   renderOption

   • Type: ({ item: any, index: number }) => React.ReactElement
   • Required: false
   • Default: uses Menu.Item component of react-native-paper
   • Description: Renders single option

   renderHost

   • Type: (props: TextInputProps) => React.ReactElement
   • Required: false
   • Default: uses TextInput of react-native-paper
   • Description: Renders main trigger element

   renderNoItems

   • Type: () => React.ReactElement
   • Required: false
   • Default: uses internal layout
   • Description: Renders when no items available in dropdown

   noItemsLabel

   • Type: string
   • Required: false (will be used only if renderNoItems is not specified)
   • Default: "No items"
   • Description: Sets string value of noItems default widget

   onPress

   • Type: () => void
   • Required: false
   • Default: -
   • Description: Triggered when user presses on dropdown

   keyExtractor

   • Type: (item: any) => string
   • Required: false
   • Default: item => item.value
   • Description: Used to generate uniq key for each option

   openOnMount

   • Type: boolean
   • Required: false
   • Default: false
   • Description: Will open dropdown options after initial render

   ...Inherits all TextInput props

   All TextInput props will be applied to host and search inputs

   FlatDropdown specific props

   menuOffset

   • Type: number
   • Required: false
   • Default: 65
   • Description: Offset of menu from trigger (host) element

   ModalDropdown specific props

   renderSearchInput

   • Type: (props: TextInputProps) => React.ReactElement
   • Required: false
   • Default: uses TextInput of react-native-paper
   • Description: Renders search input inside modal (by default looks same as trigger/host input)

Showcase

1. Default modal mode

<Autocompletemultiplevalue={value}onChange={setValue}style={{width: 300}}options={[{value: "1",label: "option 1"},{value: "2",label: "option 2"},{value: "3",label: "option 3"},]}/>

2. Flat mode

<AutocompletemultiplerenderDropdown={(props)=><FlatDropdownmenuOffset={40}{...props}/>}value={value}onChange={setValue}style={{width: 300}}options={[{value: "1",label: "option 1"},{value: "2",label: "option 2"},{value: "3",label: "option 3"},]}/>

3. Custom option

<Autocompletemultiplevalue={value}onChange={setValue}style={{width: 300}}options={[{value: "1",label: "option 1",description: "some description 1",},{value: "2",label: "option 2",description: "some description 2",},{value: "3",label: "option 3",description: "some description 3",},]}renderOption={({ selected, onSelect, label },{ description })=>{return(<List.ItemonPress={onSelect}title={label}description={description}left={(props)=><List.Icon{...props}icon="mail"/>}right={selected
? (props)=><List.Icon{...props}icon="check"/>
: undefined}/>);}}/>

4. Custom option + flat mode + custom filter

<Autocompletemultiplevalue={value}onChange={setValue}style={{width: 300}}options={[{value: "1",label: "option 1",description: "some description 1",},{value: "2",label: "option 2",description: "some description 2",},{value: "3",label: "option 3",description: "some description 3",},]}filterOptions={(options,input)=>{if(!input){returnoptions;}constincludesIgnoreNoWhiteSpaceCase=(a: string,b: string): boolean=>{constoptionQuery=(a||"").replace(/\s/g,"").toUpperCase();constinputQuery=(b||"").replace(/\s/g,"").toUpperCase();return(optionQuery.includes(inputQuery)||inputQuery.includes(optionQuery));};returnoptions.filter((option)=>{return(includesIgnoreNoWhiteSpaceCase(option.label,input)||includesIgnoreNoWhiteSpaceCase(option.description,input));});}}renderDropdown={(props)=><FlatDropdownmenuOffset={40}{...props}/>}renderOption={({ selected, onSelect, label },{ description })=>{return(<List.ItemonPress={onSelect}title={label}description={description}left={(props)=><List.Icon{...props}icon="folder"/>}right={selected
? (props)=><List.Icon{...props}icon="check"/>
: undefined}/>);}}/>

5. Custom search input for modal mode

<AutocompletemultiplerenderDropdown={(props)=>(<ModalDropdown{...props}renderSearchInput={(props)=>(<TextInput{...props}left={<TextInput.Iconname="arrow-down"size={20}/>}/>)}/>)}value={value}onChange={setValue}style={{width: 300}}options={[{value: "1",label: "option 1"},{value: "2",label: "option 2"},{value: "3",label: "option 3"},]}/>

6. Custom chips

<AutocompletemultiplerenderSelectedItem={({ label, value, onDelete })=>(<Chipkey={value}icon="folder"mode="outlined"onClose={onDelete}>{label}</Chip>)}value={value}onChange={setValue}style={{width: 300}}options={[{value: "1",label: "option 1"},{value: "2",label: "option 2"},{value: "3",label: "option 3"},]}/>

7. Validation

<AutocompletemultipleonOpen={()=>{}}onClose={()=>{}}value={value}error={value.length!==2}renderHelper={value.length!==2
? ()=>(<HelperTexttype="error"visible>
You should select 2 items
</HelperText>)
: null}onChange={setValue}style={{width: 300}}options={[{value: "1",label: "option 1"},{value: "2",label: "option 2"},{value: "3",label: "option 3"},]}/>

8. Single selection autocomplete

<AutocompletemenuOffset={40}value={value}onChange={setValue}style={{width: 300}}options={[{value: "1",label: "option 1"},{value: "2",label: "option 2"},{value: "3",label: "option 3"},]}/>

9. Custom host element

<AutocompletemenuOffset={15}renderHost={()=>(<Buttonmode="contained">{value
? options.find((op)=>op.value===value)?.label
: "Select value..."}</Button>)}filterOptions={(options)=>options}onOpen={()=>{}}onClose={()=>{}}value={value}onChange={setValue}style={{width: 300}}options={options}/>

10. Plain Dropdown Component (Modal)

<ModalDropdownonOpen={()=>{}}onClose={()=>{}}onChangeText={setInput}style={{width: 300}}inputValue={input}options={[{value: "1",label: "option 1"},{value: "2",label: "option 2"},{value: "3",label: "option 3"},]}renderOption={({ item })=>(<Menu.ItemonPress={()=>{}}title={item.label}/>)}/>

11. Plain Dropdown Component (Flat)

<FlatDropdownonOpen={()=>{}}onClose={()=>{}}onChangeText={setInput}menuOffset={40}style={{width: 300}}inputValue={input}options={[{value: "1",label: "option 1"},{value: "2",label: "option 2"},{value: "3",label: "option 3"},]}renderOption={({ item })=>(<Menu.ItemonPress={()=>{}}title={item.label}/>)}/>

12. Writing Autocomplete which works in mixed mode (flat+modal)

import{FlatDropdown,ModalDropdown,Autocomplete,AutocompleteProps,}from"@telenko/react-native-paper-autocomplete";importReact,{useState}from"react";constAutocompleteMixed: React.FC<AutocompleteProps>=(props)=>{const[modal,setModal]=useState(false);const[currentOpen,setCurrentOpen]=useState(props.openOnMount);return(<AutocompleterenderDropdown={(props)=>modal ? (<ModalDropdownopenOnMount={currentOpen}{...props}/>) : (<FlatDropdownopenOnMount={currentOpen}menuOffset={40}{...props}/>)}onClose={()=>{setCurrentOpen(false);setModal(false);}}onChangeText={(v)=>{setCurrentOpen(true);setModal(v.length>0);}}{...props}/>);};