↗

â†—

↗

☰

Dropdown

iOS

Android

Web

An animated dropdown selector with built-in search, portal overlay, and full render customization. Accepts a generic type parameter T for your data items.

Import

tsx

import { Dropdown, type DropdownProps, type DropdownRef, } from 'react-native-cross-elements';

Basic usage

dropdown.tsx

Select...

▼

Props

disabled

animateDropdown

With search & animation

tsx

<Dropdown data={OPTIONS} onSelect={onSelect} search searchPlaceHolder="Search..." renderSearchInputLeftIcon={() => <Text>��</Text>} animateDropdown animationType="spring" dropDownSpacing={8} dropdownOverlayColor="rgba(0,0,0,0.5)" /* ...button/item renderers */ />

Programmatic control (ref)

Pass a ref typed as DropdownRef to open, close, select, or reset the dropdown from outside.

tsx

import React from 'react'; import { Text } from 'react-native'; import { Dropdown, type DropdownRef } from 'react-native-cross-elements'; export default function Example() { const ref = React.useRef<DropdownRef>(null); return ( <> <Dropdown ref={ref} data={OPTIONS} onSelect={onSelect} /* ...other props */ /> <Text onPress={() => ref.current?.openDropdown()}>Open</Text> <Text onPress={() => ref.current?.closeDropdown()}>Close</Text> <Text onPress={() => ref.current?.selectIndex(0)}>Select first</Text> <Text onPress={() => ref.current?.reset()}>Reset</Text> </> ); }

Portal fallback

ℹ️

When a PortalHost is mounted at the root, Dropdown automatically renders its window into it. Otherwise it falls back to a native Modal. Mount <PortalHost /> at your app root for the best web experience.

DropdownProps

Prop

Type

Default

Description

data

req

T[]

—

Items to render.

onSelect

(item: T, index: number) => void

—

Called on selection.

defaultValue

—

Pre-selected item.

defaultValueByIndex

number

—

Pre-selected index (zero-based).

disabled

boolean

false

Disable the entire dropdown.

disabledIndexes

number[]

—

Disable specific items by index.

boolean

—

Enable built-in search input.

searchPlaceHolder

string

—

Placeholder for search input.

renderSearchInputLeftIcon

() => ReactElement

—

Left icon inside search input.

renderSearchInputRightIcon

() => ReactElement

—

Right icon inside search input.

animateDropdown

boolean

—

Enable open/close animation.

animationType

'spring' | 'timing'

'spring'

Animation driver.

animationConfig

AnimationConfig

—

Timing config when using timing driver.

springConfig

WithSpringConfig

—

Spring config when using spring driver.

dropDownSpacing

number

—

Gap between trigger and dropdown window.

dropdownOverlayColor

string

—

Backdrop overlay color.

dropdownStyle

ViewStyle

—

Container style for the dropdown.

renderButtonContent

(item, isVisible, focused) => JSX.Element

—

Custom trigger button content.

renderButton

({ selectedItem, isVisible, disabled, onPress }) => JSX.Element

—

Full custom trigger button.

renderItemContent

(item, index, isSelected) => JSX.Element

—

Custom row content.

renderItemButton

({ item, index, isSelected, disabled, onPress }) => JSX.Element

—

Full custom row button.

onDropdownWillShow

(willShow: boolean) => void

—

Called before opening or closing.

onScrollEndReached

() => void

—

Fired at the end of the list.

onChangeSearchInputText

(text: string) => void

—

Override search handler.

DropdownRef

Prop

Type

Default

Description

reset()

() => void

—

Clear selection and search text.

openDropdown()

() => void

—

Open the dropdown.

closeDropdown()

() => void

—

Close the dropdown.

selectIndex(index)

(index: number) => void

—

Select item by index.