# @carlos3g/element-dropdown — full documentation

> Single-file dump of every documentation page on https://carlos3g.github.io/element-dropdown, in stable order.
> Generated at build time. For the manifest version see https://carlos3g.github.io/element-dropdown/llms.txt.

---

# Accessibility

Source: https://carlos3g.github.io/element-dropdown/docs/accessibility

# Accessibility

`@carlos3g/element-dropdown` ships sensible a11y defaults: every
touchable surface is exposed to screen readers, items announce
their selection state, the modal traps VoiceOver focus, and the
component honours the user's reduce-motion preference. Nothing
on this page requires any code change to benefit from — it's all
on by default.

## Trigger

Both `Dropdown` and `MultiSelect` triggers expose:

- `accessibilityRole="combobox"` — screen readers announce it as a
  dropdown.
- `accessibilityState.expanded` — `true` when the list is open.
- `accessibilityState.disabled` — `true` when the `disable` prop
  is set.

Set `accessibilityLabel` on the component to give the trigger a
descriptive label, and `accessibilityHint` for an action
description:

```tsx
<Dropdown
  accessibilityLabel="Country selector"
  accessibilityHint="Opens a list of countries"
  // …
/>
```

The label is also propagated to the search input
(as `{label} input`) and the list (as `{label} flatlist`), so
tests and assistive tech can address each surface.

## List items

Every list row exposes:

- `accessibilityRole="button"` — TalkBack / VoiceOver announces
  rows as actionable.
- `accessibilityState.selected` — `true` when this item matches
  the current value.
- `accessibilityState.disabled` — `true` when `disabledField` is
  set and the item's value at that field is truthy.

By default, the row's `accessibilityLabel` is `item[labelField]`.
To use a different field, set `itemAccessibilityLabelField`:

```tsx
<Dropdown
  data={data}
  labelField="name"
  valueField="id"
  itemAccessibilityLabelField="fullDescription"
  onChange={(item) => setValue(item.id)}
/>
```

Items are accessible regardless of whether you pass a
component-level `accessibilityLabel`. (Earlier upstream versions
silently set `accessible={false}` when the component label was
missing — that gate has been removed.)

## Section headers

When you use the `sections` prop, the default section header
carries `accessibilityRole="header"` so VoiceOver / TalkBack's
"next heading" gesture surfaces group titles:

```tsx
<Dropdown
  sections={[
    { title: 'Berries',  data: [/* … */] },
    { title: 'Citrus',   data: [/* … */] },
  ]}
  // …
/>
```

If you supply your own `renderSectionHeader`, set the role
yourself.

## MultiSelect chips

Each chip in the selection row exposes:

- `accessibilityRole="button"`
- `accessibilityHint="Double tap to remove from selection"`

The decorative `ⓧ` glyph is hidden from the accessibility tree
(`accessibilityElementsHidden` + `importantForAccessibility="no-hide-descendants"`)
so screen readers don't read out "circled x" after the label.

The chip-row container is an
`accessibilityLiveRegion="polite"` region — toggling a row
announces the new chip without forcing the user to navigate back
to the row.

## Modal isolation

The dropdown opens inside a React Native `<Modal>` whose root
view sets `accessibilityViewIsModal`. On iOS, this scopes
VoiceOver focus to the modal contents; users can't accidentally
swipe back into the screen behind the open list.

## Reduce motion

Both components subscribe to the OS-level "Reduce Motion"
preference via `AccessibilityInfo`. When enabled, the modal
opens / closes with `animationType="none"` instead of the
default platform animation. The change happens live — toggling
the OS setting while a dropdown is open propagates without a
remount.

## Tap target size

Use [`hitSlop`](./guides/hit-slop) to expand the trigger's tap
area without changing its visual layout. WCAG 2.5.5 recommends
at least 44 × 44 pt; if your trigger sits in tight UI, set
`hitSlop` to widen the touch target.

## Font scaling

Labels and the search input respect the system font-scale setting
by default. Use [`allowFontScaling`](./guides/font-scaling) to
override per-component when you need to lock a fixed size for
layout reasons.

## Search input

The built-in search input inherits an accessibility label
derived from the component's `accessibilityLabel` (`{label}
input`). To set a more user-friendly label, override via
`searchInputProps`:

```tsx
<Dropdown
  search
  accessibilityLabel="Country picker"
  searchInputProps={{
    accessibilityLabel: 'Search countries',
    selectionColor: '#007AFF',
  }}
  // …
/>
```

`searchInputProps` is also where to set `selectionColor`,
`returnKeyType`, `autoCapitalize`, `autoFocus`, etc. for
keyboard / cursor a11y. See
[Search input passthrough](./guides/search-input-props).

## Known gaps

- **Hardware keyboard navigation** (arrow keys, Home/End, Escape,
  typeahead) is not yet implemented. The component relies on
  touch. Tracking upstream `#228` as a follow-up; needs an
  active-descendant focus model that doesn't exist yet in the
  codebase.
- **Programmatic focus management** — opening the dropdown does
  not auto-focus the search input, and closing does not return
  focus to the trigger. Adding this without device-level testing
  would risk regressions on Android, so it's deferred until we
  have a Fabric / web harness.

If you hit an accessibility bug or gap not listed here, open an
issue at
[`carlos3g/element-dropdown`](https://github.com/carlos3g/element-dropdown/issues).

---

# Introduction

Source: https://carlos3g.github.io/element-dropdown/docs/intro

# `react-native-element-dropdown`, maintained.

`@carlos3g/element-dropdown` is a drop-in fork of
[`react-native-element-dropdown`](https://github.com/hoaphantn7604/react-native-element-dropdown).
Bugs get fixed, the toolchain stays current, and every release is
signed. Same API, same three components (`Dropdown`,
`MultiSelect`, `SelectCountry`), same props — change two lines and
keep shipping.

```sh
npm install @carlos3g/element-dropdown
```

```diff
- import { Dropdown } from 'react-native-element-dropdown';
+ import { Dropdown } from '@carlos3g/element-dropdown';
```

## Why this fork exists

The original package is unmaintained. A large open-issue backlog,
plus clean community pull requests sitting untouched for years. If
you're already on `react-native-element-dropdown`, you've likely
hit one of these:

- `Invariant Violation: scrollToIndex out of range` when searching
  long lists
- The list flashes at the wrong position for a frame when you
  reopen it
- `IDropdownRef` / `IMultiSelectRef` aren't importable when you
  build for web or Expo
- Every item has a non-overridable `padding: 17` —
  `itemContainerStyle` can't shrink it
- `MultiSelect` trigger uses `placeholderStyle` even after you've
  selected something

All fixed in this fork — along with plenty more. The
[release notes](https://github.com/carlos3g/element-dropdown/releases)
have the per-version detail.

## Where to go next

- **[Installation](./installation)** — add the package to your
  project.
- **[Quick start](./quick-start)** — render your first `Dropdown`
  and `MultiSelect`.
- **[Migration from upstream](./migration-from-upstream)** — what
  changes (and what doesn't) when moving from
  `react-native-element-dropdown`.
- **Components** — full prop reference for
  [`Dropdown`](./components/dropdown),
  [`MultiSelect`](./components/multi-select), and
  [`SelectCountry`](./components/select-country).
- **Guides** — copy-paste recipes for common patterns.
- **[Why this fork](./why-this-fork)** — the longer version.

---

# Installation

Source: https://carlos3g.github.io/element-dropdown/docs/installation

# Installation

## Install the package

```sh
npm install @carlos3g/element-dropdown
```

```sh
yarn add @carlos3g/element-dropdown
```

## Peer dependencies

`@carlos3g/element-dropdown` declares `react` and `react-native` as
`peerDependencies: "*"` — the package does not pin them. Use the
`react` and `react-native` versions your app is already on. The
library itself runs on everything from `react-native@0.71`+ and any
matching React version.

There are no native modules, no pods to link, no Gradle files to
touch. Expo Managed and bare React Native both work as-is.

## Supported platforms

- iOS
- Android
- React Native Web (via `react-native-web`)

## TypeScript

TypeScript support is first-class — the package ships both the
type definitions and the TypeScript source. Consumer types are
re-exported from the package root:

```tsx
import type {
  DropdownProps,
  IDropdownRef,
  MultiSelectProps,
  IMultiSelectRef,
  SelectCountryProps,
  ISelectCountryRef,
} from '@carlos3g/element-dropdown';
```

## Verifying the install

The fastest smoke test is rendering a minimal `Dropdown` — head to
[Quick start](./quick-start).

---

# Why this fork

Source: https://carlos3g.github.io/element-dropdown/docs/why-this-fork

# Why this fork

`react-native-element-dropdown` has been a good library. At the
time of writing this fork was created, the upstream had **1.3k
GitHub stars, 210 forks, and roughly 1.2 million weekly npm
downloads**. People rely on it.

It's also effectively unmaintained. The last meaningful upstream
activity was mid-2024. The issue tracker has a large backlog, and
the PR queue has clean, small community fixes that have been
waiting years to merge.

Rather than re-architect a new dropdown library, this fork keeps
what worked and fixes what didn't.

## What this fork commits to

- **Same public API.** Migration is two lines: the install name
  and the import path. See
  [Migration from upstream](./migration-from-upstream).
- **Bugs get fixed.** Upstream issues get triaged and landed
  release by release. See the
  [release notes](https://github.com/carlos3g/element-dropdown/releases)
  for what's in each version, and
  [`docs/upstream-triage.md`](https://github.com/carlos3g/element-dropdown/blob/master/docs/upstream-triage.md)
  for the roadmap.
- **The toolchain stays current.** TypeScript, React Native,
  ESLint, Prettier, Jest — they get upgraded so this library can
  keep up with its consumers rather than hold them back.
- **Releases are signed.** Every version is published via npm
  Trusted Publishing (OIDC) with provenance attestation. Anyone
  can verify a given tarball came from this repository's CI.

## What this fork does not try to be

- A rewrite. The public API is intentionally unchanged; do not
  expect breaking redesigns.
- A new dependency-free implementation. The same FlatList +
  Modal approach the upstream used is still used here.
- An enterprise-supported product. This is a maintained
  open-source fork — no SLA, no commercial tier, no email
  support. Issues and pull requests are the interface.

## Open questions and follow-ups

Some upstream issues are deferred because they need device-level
reproduction:

- Keyboard-avoidance math on iOS and Android 0.76+ (upstream
  `#180`, `#357`, `#339`, `#288`, `#328`).
- Android 14+ `dropdownPosition="top"` behavior (`#355`).
- Realme OEM positioning quirks (`#350`).

These are tracked in
[`docs/upstream-triage.md`](https://github.com/carlos3g/element-dropdown/blob/master/docs/upstream-triage.md).
Pull requests with repro projects are welcome.

## How to help

- File issues with minimal repros.
- Send pull requests — ideally with a test.
- Port clean upstream PRs (see the upstream-triage doc for the
  prioritized list).
- Star the repo; it makes the fork easier to find for people who
  are currently on the abandoned upstream.

---

# Quick start

Source: https://carlos3g.github.io/element-dropdown/docs/quick-start

# Quick start

## A single-select `Dropdown`

```tsx
import { useState } from 'react';
import { Dropdown } from '@carlos3g/element-dropdown';

const data = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Cherry', value: 'cherry' },
];

export function FruitPicker() {
  const [value, setValue] = useState<string | null>(null);

  return (
    <Dropdown
      data={data}
      labelField="label"
      valueField="value"
      placeholder="Pick a fruit"
      value={value}
      onChange={(item) => setValue(item.value)}
    />
  );
}
```

What you get out of the box:

- A styled trigger that displays the placeholder or the selected
  label.
- A modal-backed list that opens on tap and closes on outside press.
- Automatic positioning above or below the trigger (set
  [`dropdownPosition`](./components/dropdown#behavior) to lock it).

## A `MultiSelect`

```tsx
import { useState } from 'react';
import { MultiSelect } from '@carlos3g/element-dropdown';

const data = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Cherry', value: 'cherry' },
];

export function FruitBasket() {
  const [value, setValue] = useState<string[]>([]);

  return (
    <MultiSelect
      data={data}
      labelField="label"
      valueField="value"
      placeholder="Pick fruits"
      value={value}
      onChange={setValue}
    />
  );
}
```

`MultiSelect` is controlled by `value`. Tapping an item toggles it
on or off; `onChange` fires with the new array.

## With a search input

Set `search={true}` and the component renders a `TextInput` above
the list. By default the search matches against the label field.

```tsx
<Dropdown
  search
  searchPlaceholder="Search fruits…"
  data={data}
  labelField="label"
  valueField="value"
  value={value}
  onChange={(item) => setValue(item.value)}
/>
```

See the [custom search](./guides/custom-search-field) and
[custom matcher](./guides/custom-search-matcher) guides for more
control.

## Next steps

- **[Components](./components/dropdown)** — the full prop reference.
- **Guides** — recipes for programmatic open/close, disabled items,
  nesting inside a Modal, and more.

---

# Migration from upstream

Source: https://carlos3g.github.io/element-dropdown/docs/migration-from-upstream

import Head from '@docusaurus/Head';

<Head>
  <script type="application/ld+json">
    {JSON.stringify({
      '@context': 'https://schema.org',
      '@type': 'FAQPage',
      mainEntity: [
        {
          '@type': 'Question',
          name: 'Is @carlos3g/element-dropdown a drop-in replacement for react-native-element-dropdown?',
          acceptedAnswer: {
            '@type': 'Answer',
            text: 'Yes. The public API is unchanged from react-native-element-dropdown@2.12.x. Migration is a two-line change: update the package name in package.json and update the import path in your code. No config changes, no native rebuild.',
          },
        },
        {
          '@type': 'Question',
          name: 'Do I need to rebuild native code when switching to the fork?',
          acceptedAnswer: {
            '@type': 'Answer',
            text: 'No. The library has no native modules. Install the package, update your imports, and keep shipping. Works with Expo Managed and bare React Native identically.',
          },
        },
        {
          '@type': 'Question',
          name: 'Which bugs are fixed by the fork?',
          acceptedAnswer: {
            '@type': 'Answer',
            text: 'Key fixes include the scrollToIndex out-of-range crash when searching, the open-time position flicker, the non-overridable item padding, the MultiSelect trigger label using placeholderStyle after selection, broken TypeScript type re-exports that broke web and Expo builds, and missing accessibility metadata. See the release notes for the full list.',
          },
        },
        {
          '@type': 'Question',
          name: 'Are there breaking changes?',
          acceptedAnswer: {
            '@type': 'Answer',
            text: 'No. TypeScript type re-exports now use export type, which is a correctness fix rather than a breaking change. Default row padding is unchanged; itemContainerStyle can now override it.',
          },
        },
        {
          '@type': 'Question',
          name: 'What new props does the fork add?',
          acceptedAnswer: {
            '@type': 'Answer',
            text: 'disabledField (mark individual items as non-interactive), hitSlop (enlarge the trigger tap target), allowFontScaling (respect or override the system font scale), and isInsideModal (fix positioning when nested inside a React Native Modal). All are optional.',
          },
        },
        {
          '@type': 'Question',
          name: 'Will the fork keep getting updates?',
          acceptedAnswer: {
            '@type': 'Answer',
            text: 'Yes. The fork triages and lands community patches in every release. Releases are published via npm Trusted Publishing with provenance attestation. The roadmap is public in docs/upstream-triage.md.',
          },
        },
      ],
    })}
  </script>
</Head>

# Migration from `react-native-element-dropdown`

The fork is designed for drop-in migration from
`react-native-element-dropdown@2.12.x`. The public API is
unchanged — only the package name and import paths differ.

## The two-line change

```sh
# 1. Remove the upstream and install the fork
npm uninstall react-native-element-dropdown
npm install @carlos3g/element-dropdown
```

```diff
// 2. Update your imports
- import { Dropdown, MultiSelect, SelectCountry } from 'react-native-element-dropdown';
+ import { Dropdown, MultiSelect, SelectCountry } from '@carlos3g/element-dropdown';
```

That's it. No config file changes, no `metro.config.js` tweaks, no
native rebuild.

## Is the API compatible?

Yes. Every prop and every component signature from `2.12.x` works
unchanged. Peer dependencies are still `react: *` and
`react-native: *`. Platforms supported: iOS, Android, and React
Native Web.

## Do I need to rebuild native code?

No. The library has no native modules, no pods to link, no Gradle
files to touch. Expo Managed and bare React Native both work
as-is.

## What improves automatically after migration?

Behavior changes you get for free, with no code changes:

- **TypeScript types are exported as types.** Importing
  `IDropdownRef` or `IMultiSelectRef` no longer trips bundlers on
  web or Expo.
- **The `scrollToIndex out of range` crash is gone.** The common
  crash when auto-scrolling to a selected item while searching a
  long list no longer fires.
- **Open-time flicker is gone.** The list no longer paints for a
  frame at the previous open's position before snapping to the
  correct one.
- **MultiSelect trigger label honors `selectedTextStyle`** once
  items are selected. Previously it stayed on `placeholderStyle`.
- **Row padding is customizable.** `itemContainerStyle` can shrink
  (or expand) the item row. Previously the `padding: 17` was
  hardcoded deeper in the tree and could only be overridden via
  `renderItem`.
- **Duplicate-key warnings from `FlatList` are gone.** The list
  now extracts keys from `valueField` when present.
- **Accessibility is announced properly.** Triggers expose
  `accessibilityRole="combobox"` plus `expanded` and `disabled`
  states; items expose `selected` and `disabled`.

## What new props are available?

All new props are optional:

- **[`disabledField`](./components/dropdown#behavior)** — mark
  individual items as non-interactive.
- **`hitSlop`** — enlarge the trigger tap target without changing
  layout.
- **`allowFontScaling`** — respect or override the system font
  scale for the trigger, the search input, and item labels.
- **`isInsideModal`** — tells the component it's rendered inside
  a React Native `<Modal>` so positioning math doesn't
  double-count the status bar.

## Anything to watch out for?

- The TS type-only re-exports now use `export type`, which means
  that downstream code that imported `IDropdownRef` as a **value**
  (e.g. via `typeof`) needs to import it as a type. In practice
  this trips code only if you were misusing the type in the first
  place.
- If your project depends on the exact previous row padding of
  `17`, no action needed — the default is unchanged. The
  difference is that `itemContainerStyle` can now override it.

## Still stuck?

Open an issue at
[`carlos3g/element-dropdown`](https://github.com/carlos3g/element-dropdown/issues).
If the same symptom appears in the upstream and it's not covered
by the roadmap in
[`docs/upstream-triage.md`](https://github.com/carlos3g/element-dropdown/blob/master/docs/upstream-triage.md),
it's worth reporting.

---

# Dropdown

Source: https://carlos3g.github.io/element-dropdown/docs/components/dropdown

# `Dropdown`

Single-select dropdown. The user taps the trigger, picks one item
from a list, and the list closes.

## Minimal example

```tsx
import { useState } from 'react';
import { Dropdown } from '@carlos3g/element-dropdown';

const data = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
];

export function FruitPicker() {
  const [value, setValue] = useState<string | null>(null);
  return (
    <Dropdown
      data={data}
      labelField="label"
      valueField="value"
      placeholder="Pick a fruit"
      value={value}
      onChange={(item) => setValue(item.value)}
    />
  );
}
```

## Props

### Required

| Prop | Type | Description |
|---|---|---|
| `data` | `T[]` | Flat array of items. Pass `sections` instead for grouped rendering. |
| `labelField` | `keyof T` | Field on each item to use as the visible label. |
| `valueField` | `keyof T` | Field on each item that identifies it uniquely. |
| `onChange` | `(item: T) => void` | Fires with the selected item when the user picks from the list. |

### Sections (optional — alternative to `data`)

| Prop | Type | Description |
|---|---|---|
| `sections` | `{ title: string; data: T[] }[]` | Groups of items rendered under section headers. When provided, `data` is ignored. See [Sectioned lists](../guides/sectioned-lists). |
| `renderSectionHeader` | `(section) => ReactElement \| null` | Fully custom header renderer. |
| `sectionHeaderStyle` | `ViewStyle` | Style for the default header container. |
| `sectionHeaderTextStyle` | `TextStyle` | Style for the default header `<Text>`. |

### Value and display

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `T \| string \| null` | `undefined` | Currently selected value. Can be the full item or just the `valueField` value. |
| `placeholder` | `string` | `'Select item'` | Shown when no value is selected. |
| `placeholderStyle` | `TextStyle` | — | Style for the placeholder text. |
| `selectedTextStyle` | `TextStyle` | — | Style for the label when an item is selected. |
| `selectedTextProps` | `TextProps` | `{}` | Extra props spread onto the selected-label `<Text>` (e.g. `numberOfLines`). |

### Container and layout

| Prop | Type | Default | Description |
|---|---|---|---|
| `style` | `ViewStyle` | — | Style for the outer wrapper. |
| `containerStyle` | `ViewStyle` | — | Style for the floating list container. |
| `backgroundColor` | `string` | — | Color of the scrim behind the modal in full-screen modes. |
| `modalAnimationType` | `'none' \| 'slide' \| 'fade'` | RN default | Forwarded to the underlying React Native `<Modal>`. When the OS "Reduce Motion" setting is on, this is always forced to `'none'`. |
| `maxHeight` | `number` | `340` | Max height of the list. |
| `minHeight` | `number` | `0` | Min height of the list. |
| `mode` | `'default' \| 'modal' \| 'auto'` | `'default'` | `'modal'` centers the list on screen; `'auto'` measures trigger position. |
| `dropdownPosition` | `'auto' \| 'top' \| 'bottom'` | `'auto'` | Force the list to open above or below the trigger. |
| `inverted` | `boolean` | `true` | Reverses scroll direction when positioned above the trigger. |
| `isInsideModal` | `boolean` | `false` | Set to `true` when the Dropdown is rendered inside a React Native `<Modal>` so the status-bar offset isn't double-counted. See [Nest inside a Modal](../guides/nested-in-modal). |

### Items

| Prop | Type | Default | Description |
|---|---|---|---|
| `itemContainerStyle` | `ViewStyle` | — | Style merged on top of the built-in row style. Use this to change padding. |
| `itemTextStyle` | `TextStyle` | — | Style for the default item label text. |
| `activeItemTextStyle` | `TextStyle` | — | Extra text style applied only to the currently-selected row. |
| `activeColor` | `string` | `'#F6F7F8'` | Background color of the currently selected row in the list. |
| `renderItem` | `(item: T, selected?: boolean, index?: number) => ReactElement` | — | Fully custom row renderer. Overrides the default label. The optional `index` is the row index in the current list (per-section when `sections` is used) — handy for staggered enter animations. See [Animations guide](../guides/animations). |
| `disabledField` | `keyof T` | — | When set, items whose value at this field is truthy are non-interactive. |
| `hideSelectedFromList` | `boolean` | `false` | When `true`, the currently selected item is removed from the rendered list. |

### Search

| Prop | Type | Default | Description |
|---|---|---|---|
| `search` | `boolean` | `false` | Show the search input above the list. |
| `searchField` | `keyof T \| (keyof T)[]` | `labelField` | Which field(s) to match against. Pass an array to search several at once. See [Custom search field](../guides/custom-search-field). |
| `searchQuery` | `(keyword: string, labelValue: string) => boolean` | — | Fully custom matcher. See [Custom matcher](../guides/custom-search-matcher). |
| `searchKeyboardType` | `KeyboardTypeOptions` | — | `keyboardType` for the search input (e.g. `'numeric'`, `'email-address'`). |
| `searchInputProps` | `TextInputProps` | — | Extra props spread onto the underlying search `<TextInput>` (`selectionColor`, `returnKeyType`, `autoCapitalize`, etc.). See [Search input passthrough](../guides/search-input-props). |
| `persistSearch` | `boolean` | `false` | Keep the search text across opens / selections instead of clearing it. |
| `searchDebounce` | `number` | `0` | Debounce the filter pass by this many ms. The text input stays responsive; only the filter is throttled. Useful for lists in the thousands. |
| `inputSearchStyle` | `ViewStyle` | — | Style for the search input. |
| `searchPlaceholder` | `string` | — | Placeholder text for the search input. |
| `searchPlaceholderTextColor` | `string` | `'gray'` | Placeholder color for the search input. |
| `renderInputSearch` | `(onSearch: (text: string) => void) => ReactElement` | — | Fully custom search input. |
| `renderSearchClearIcon` | `() => ReactElement \| null` | — | Replace only the clear glyph on the built-in search input while keeping the clear-on-press behaviour. Ignored when `renderInputSearch` is supplied. |
| `onChangeText` | `(text: string) => void` | — | Fires whenever the search text changes (including when the dropdown closes). |

### Icons & trigger

| Prop | Type | Default | Description |
|---|---|---|---|
| `iconStyle` | `ImageStyle` | — | Style for the default right-side chevron. |
| `iconColor` | `string` | `'gray'` | Tint for the default right-side chevron. |
| `renderLeftIcon` | `(visible?: boolean) => ReactElement \| null` | — | Custom left icon; receives whether the list is open. |
| `renderRightIcon` | `(visible?: boolean) => ReactElement \| null` | — | Custom right icon; receives whether the list is open. See [Icons per state](../guides/icon-per-state). |
| `renderSelectedItem` | `(visible?: boolean) => ReactElement \| null` | — | Replace the entire trigger body (left icon, label, right icon) with a custom layout. See [Custom trigger](../guides/custom-trigger). |
| `renderModalHeader` | `(close: () => void) => ReactElement \| null` | — | Renders a header view above the list inside the modal. Receives a `close()` to dismiss. See [Modal header](../guides/modal-header). |

### Behavior

| Prop | Type | Default | Description |
|---|---|---|---|
| `disable` | `boolean` | `false` | When `true`, tapping the trigger does nothing. |
| `autoScroll` | `boolean` | `true` | On open, scroll the list to the currently-selected row. Ignored while the list is filtered. |
| `keyboardAvoiding` | `boolean` | `true` | Lift the list when the search input raises the keyboard. |
| `confirmSelectItem` | `boolean` | `false` | When `true`, selecting an item calls `onConfirmSelectItem` instead of `onChange`. |
| `onConfirmSelectItem` | `(item: T) => void` | — | Called when `confirmSelectItem` is `true`. |
| `closeModalWhenSelectedItem` | `boolean` | `true` | When `false`, the list stays open after a selection. |
| `showsVerticalScrollIndicator` | `boolean` | `true` | Shows the vertical scroll indicator on the list. |
| `flatListProps` | `Omit<FlatListProps<T>, 'renderItem' \| 'data'>` | — | Passthrough to the underlying `FlatList`. |
| `renderEmpty` | `(searchText: string) => ReactElement \| null` | — | Custom view rendered when the list has no rows — either empty `data` / `sections` or a search that filters everything out. The callback receives the current search query so you can switch between "no data" and "no results for X" copy. |
| `onEndReached` | `() => void` | — | Fires when the list scrolls within `onEndReachedThreshold` of the bottom. See [Pagination](../guides/end-reached-pagination). |
| `onEndReachedThreshold` | `number` | `0.5` | Distance from the end (in viewport units) at which `onEndReached` fires. |
| `excludeItems` | `T[]` | `[]` | Items to hide from the rendered list. |
| `excludeSearchItems` | `T[]` | `[]` | Items that show in the list but are excluded from search matches. |

### Callbacks

| Prop | Type | Description |
|---|---|---|
| `onFocus` | `() => void` | Fires when the list opens. |
| `onBlur` | `() => void` | Fires when the list closes. |

### Text rendering

| Prop | Type | Default | Description |
|---|---|---|---|
| `fontFamily` | `string` | — | Applied to trigger label, item labels, and the search input. |
| `allowFontScaling` | `boolean` | RN default | Propagated to every `Text` and `TextInput` the component renders. |

### Accessibility

| Prop | Type | Description |
|---|---|---|
| `accessibilityLabel` | `string` | Label for the trigger. Propagated as `{label} input` to the search field and `{label} flatlist` to the list. |
| `accessibilityHint` | `string` | Hint for the trigger, announced after the label and role. |
| `itemAccessibilityLabelField` | `string` | Field on each item to use for per-item `accessibilityLabel`. Defaults to `labelField`. |
| `testID` | `string` | testID for the trigger. Propagated as `{testID} input` / `{testID} flatlist`. |
| `itemTestIDField` | `string` | Field on each item to use as its `testID`. Defaults to `labelField`. |
| `hitSlop` | `Insets \| number` | Expand the trigger's tap target. |

Triggers expose `accessibilityRole="combobox"` and
`accessibilityState.expanded` / `.disabled`. Items expose
`accessibilityRole="button"` plus `accessibilityState.selected`
and `.disabled`. The open modal is scoped with
`accessibilityViewIsModal`, and the OS-level "Reduce Motion"
preference disables the modal animation automatically. See
[Accessibility](../accessibility).

## Imperative ref

```tsx
import { useRef } from 'react';
import { Dropdown } from '@carlos3g/element-dropdown';
import type { IDropdownRef } from '@carlos3g/element-dropdown';

const ref = useRef<IDropdownRef>(null);

<Dropdown ref={ref} {/* … */} />
<Button title="Open" onPress={() => ref.current?.open()} />
<Button title="Close" onPress={() => ref.current?.close()} />
```

See [Open and close programmatically](../guides/imperative-open-close).

## Related guides

- [Custom search field](../guides/custom-search-field)
- [Custom search matcher](../guides/custom-search-matcher)
- [Search input passthrough](../guides/search-input-props)
- [Sectioned lists](../guides/sectioned-lists)
- [Pagination with `onEndReached`](../guides/end-reached-pagination)
- [Custom trigger](../guides/custom-trigger)
- [Modal header](../guides/modal-header)
- [Disabled items](../guides/disabled-items)
- [Nest inside a Modal](../guides/nested-in-modal)
- [Icons per open state](../guides/icon-per-state)
- [Bigger tap targets](../guides/hit-slop)

---

# MultiSelect

Source: https://carlos3g.github.io/element-dropdown/docs/components/multi-select

# `MultiSelect`

Multi-select variant. The user taps the trigger, toggles one or
more items, and the selection renders as a row of chips either
below or inside the trigger.

## Minimal example

```tsx
import { useState } from 'react';
import { MultiSelect } from '@carlos3g/element-dropdown';

const data = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Cherry', value: 'cherry' },
];

export function FruitBasket() {
  const [value, setValue] = useState<string[]>([]);
  return (
    <MultiSelect
      data={data}
      labelField="label"
      valueField="value"
      placeholder="Pick fruits"
      value={value}
      onChange={setValue}
    />
  );
}
```

`MultiSelect` is controlled. `value` is the array of selected
`valueField` values; `onChange` fires with the new array every
time an item is toggled.

## Props

### Required

| Prop | Type | Description |
|---|---|---|
| `data` | `T[]` | Flat array of items. Pass `sections` instead for grouped rendering. |
| `labelField` | `keyof T` | Field on each item used as the visible label. |
| `valueField` | `keyof T` | Field on each item that identifies it uniquely. |
| `value` | `string[] \| null` | Currently selected `valueField` values. |
| `onChange` | `(value: string[]) => void` | Fires with the new selection array. |

### Sections (optional — alternative to `data`)

| Prop | Type | Description |
|---|---|---|
| `sections` | `{ title: string; data: T[] }[]` | Groups of items rendered under section headers. When provided, `data` is ignored. See [Sectioned lists](../guides/sectioned-lists). |
| `renderSectionHeader` | `(section) => ReactElement \| null` | Fully custom header renderer. |
| `sectionHeaderStyle` | `ViewStyle` | Style for the default header container. |
| `sectionHeaderTextStyle` | `TextStyle` | Style for the default header `<Text>`. |

### Display

| Prop | Type | Default | Description |
|---|---|---|---|
| `placeholder` | `string` | `'Select item'` | Trigger label when nothing is selected. |
| `placeholderStyle` | `TextStyle` | — | Style for the placeholder text. |
| `selectedTextStyle` | `TextStyle` | — | Style for the trigger label when the selection is non-empty. |
| `selectedTextProps` | `TextProps` | `{}` | Extra props for the trigger `<Text>`. |
| `maxSelect` | `number` | — | Cap on how many items can be selected. |
| `visibleSelectedItem` | `boolean` | `true` | When `false`, hides the chip row below the trigger. |
| `alwaysRenderSelectedItem` | `boolean` | `false` | When `true`, the chip row stays visible while the list is open. |
| `inside` | `boolean` | `false` | Render selected chips inside the trigger instead of below it. See [Inside mode](../guides/multi-select-inside-mode). |

### Container and layout

| Prop | Type | Default | Description |
|---|---|---|---|
| `style` | `ViewStyle` | — | Style for the outer wrapper. |
| `containerStyle` | `ViewStyle` | — | Style for the floating list container. |
| `backgroundColor` | `string` | — | Scrim color behind the modal in full-screen modes. |
| `modalAnimationType` | `'none' \| 'slide' \| 'fade'` | RN default | Forwarded to the underlying React Native `<Modal>`. Forced to `'none'` when the OS "Reduce Motion" setting is on. |
| `maxHeight` | `number` | `340` | Max list height. |
| `minHeight` | `number` | `0` | Min list height. |
| `mode` | `'default' \| 'modal' \| 'auto'` | `'default'` | See the matching Dropdown prop. |
| `dropdownPosition` | `'auto' \| 'top' \| 'bottom'` | `'auto'` | Force list above or below. |
| `inverted` | `boolean` | `true` | Reverses scroll when list opens above. |
| `isInsideModal` | `boolean` | `false` | Set when inside a React Native `<Modal>`. |

### Selected chips

| Prop | Type | Description |
|---|---|---|
| `selectedStyle` | `ViewStyle` | Style for each chip container. |
| `renderSelectedItem` | `(item: T, unSelect?: (item: T) => void) => ReactElement` | Fully custom chip renderer. |
| `renderChipRemoveIcon` | `(item: T) => ReactElement` | Replace the built-in `ⓧ` glyph on the default chip without reimplementing the whole chip. Ignored when `renderSelectedItem` is passed. |

### Items

| Prop | Type | Default | Description |
|---|---|---|---|
| `itemContainerStyle` | `ViewStyle` | — | Style merged on top of the built-in row style. |
| `itemTextStyle` | `TextStyle` | — | Style for the default item label. |
| `activeItemTextStyle` | `TextStyle` | — | Extra text style applied only to selected rows. |
| `activeColor` | `string` | `'#F6F7F8'` | Background of the row for already-selected items. |
| `renderItem` | `(item: T, selected?: boolean, index?: number) => ReactElement` | — | Fully custom row renderer. The optional `index` is the row index in the current list (per-section when `sections` is used) — handy for staggered enter animations. See [Animations guide](../guides/animations). |
| `disabledField` | `keyof T` | — | Marks individual items as non-interactive. |
| `hideSelectedFromList` | `boolean` | `false` | Hide already-selected items from the rendered list. |
| `selectedToTop` | `boolean` | `false` | Sort selected items to the top of the list (no-op when `hideSelectedFromList` is `true`). See [Selected-item ordering](../guides/selected-ordering). |

### Search

Same props as [Dropdown](./dropdown#search): `search`, `searchField`
(supports `keyof T` or `(keyof T)[]`), `searchQuery`,
`searchKeyboardType`, `searchInputProps`, `persistSearch`,
`searchDebounce`, `inputSearchStyle`, `searchPlaceholder`,
`searchPlaceholderTextColor`, `renderInputSearch`,
`renderSearchClearIcon`, `onChangeText`.

### Icons & modal header

Same as Dropdown: `iconStyle`, `iconColor`, `renderLeftIcon`,
`renderRightIcon`. MultiSelect also accepts:

| Prop | Type | Description |
|---|---|---|
| `renderModalHeader` | `(close: () => void) => ReactElement \| null` | Renders a header view above the list inside the modal. See [Modal header](../guides/modal-header). |

### Behavior

| Prop | Type | Default | Description |
|---|---|---|---|
| `disable` | `boolean` | `false` | Disable the trigger. |
| `keyboardAvoiding` | `boolean` | `true` | Lift the list when the keyboard opens. |
| `confirmSelectItem` | `boolean` | `false` | Call `onConfirmSelectItem` on toggles instead of immediately mutating `value`. |
| `confirmUnSelectItem` | `boolean` | `false` | Same but for un-toggling. |
| `onConfirmSelectItem` | `(item: T) => void` | — | Confirm handler. |
| `closeModalWhenSelectedItem` | `boolean` | `false` | When `true`, the list closes after each toggle. Defaults to `false` to match typical multi-select UX (keep selecting). |
| `showsVerticalScrollIndicator` | `boolean` | `true` | Scroll indicator on the list. |
| `flatListProps` | `Omit<FlatListProps<T>, 'renderItem' \| 'data'>` | — | Passthrough to the underlying `FlatList`. |
| `renderEmpty` | `(searchText: string) => ReactElement \| null` | — | Custom view rendered when the list has no rows — either empty `data` / `sections` or a search that filters everything out. The callback receives the current search query so you can switch between "no data" and "no results for X" copy. |
| `onEndReached` | `() => void` | — | Fires when the list scrolls within `onEndReachedThreshold` of the bottom. See [Pagination](../guides/end-reached-pagination). |
| `onEndReachedThreshold` | `number` | `0.5` | Distance from the end (in viewport units) at which `onEndReached` fires. |
| `excludeItems` | `T[]` | `[]` | Items to hide from the list. |
| `excludeSearchItems` | `T[]` | `[]` | Items shown in the list but excluded from search. |

### Callbacks

| Prop | Type | Description |
|---|---|---|
| `onFocus` | `() => void` | Fires when the list opens. |
| `onBlur` | `() => void` | Fires when the list closes. |

### Text rendering

| Prop | Type | Description |
|---|---|---|
| `fontFamily` | `string` | Propagated to all text. |
| `allowFontScaling` | `boolean` | Propagated to every `Text`/`TextInput`. |

### Accessibility

Same props as Dropdown: `accessibilityLabel`, `accessibilityHint`,
`itemAccessibilityLabelField`, `testID`, `itemTestIDField`,
`hitSlop`. Trigger announces as `combobox`; items expose
`role="button"` and `selected` / `disabled` state. Chips in the
selection row carry `role="button"` plus a "remove from selection"
hint, and the chip row is an
`accessibilityLiveRegion="polite"` region so screen readers
announce newly-added chips without the user navigating back. See
[Accessibility](../accessibility) for the full picture.

| Prop | Type | Default | Description |
|---|---|---|---|
| `chipRemoveAccessibilityHint` | `string` | `'Double tap to remove from selection'` | Override the `accessibilityHint` announced on each chip — useful for localization or to describe a non-standard remove gesture. |

## Imperative ref

```tsx
import { useRef } from 'react';
import { MultiSelect } from '@carlos3g/element-dropdown';
import type { IMultiSelectRef } from '@carlos3g/element-dropdown';

const ref = useRef<IMultiSelectRef>(null);

<MultiSelect ref={ref} {/* … */} />
```

`ref.current?.open()` and `ref.current?.close()` mirror the
Dropdown API.

## Related guides

- [Custom search field](../guides/custom-search-field)
- [Search input passthrough](../guides/search-input-props)
- [Sectioned lists](../guides/sectioned-lists)
- [Selected-item ordering](../guides/selected-ordering)
- [Pagination with `onEndReached`](../guides/end-reached-pagination)
- [Modal header](../guides/modal-header)
- [Disabled items](../guides/disabled-items)
- [Chip row inside the trigger](../guides/multi-select-inside-mode)
- [Nest inside a Modal](../guides/nested-in-modal)

---

# SelectCountry

Source: https://carlos3g.github.io/element-dropdown/docs/components/select-country

# `SelectCountry`

A thin specialization of `Dropdown` that renders an image (usually
a country flag) next to each item's label. Every `Dropdown` prop
is supported — `SelectCountry` adds two of its own.

## Minimal example

```tsx
import { useState } from 'react';
import { SelectCountry } from '@carlos3g/element-dropdown';

const local_data = [
  {
    value: '1',
    lable: 'Country 1',
    image: {
      uri: 'https://www.vigcenter.com/upload/images/flag/GB.png',
    },
  },
  {
    value: '2',
    lable: 'Country 2',
    image: {
      uri: 'https://www.vigcenter.com/upload/images/flag/FR.png',
    },
  },
];

export function CountryPicker() {
  const [country, setCountry] = useState('1');

  return (
    <SelectCountry
      data={local_data}
      value={country}
      valueField="value"
      labelField="lable"
      imageField="image"
      placeholder="Select country"
      onChange={(e) => setCountry(e.value)}
    />
  );
}
```

## Props

`SelectCountry` accepts every prop that [Dropdown](./dropdown)
does, plus:

| Prop | Type | Required | Description |
|---|---|---|---|
| `imageField` | `string` | Yes | Field on each item whose value is an `ImageSourcePropType` (e.g. a `{ uri }` object or a `require(...)`). |
| `imageStyle` | `ImageStyle` | No | Style applied to the image rendered next to each item label in the list. |
| `selectedImageStyle` | `ImageStyle` | No | Extra style applied only to the image rendered inside the trigger when an item is selected. Merged on top of `imageStyle`. |

Items also render their image in the trigger when selected.

## Imperative ref

Same as `Dropdown`:

```tsx
import type { ISelectCountryRef } from '@carlos3g/element-dropdown';

const ref = useRef<ISelectCountryRef>(null);
```

## See also

- [Dropdown](./dropdown) — the base component.

---

# Open and close programmatically

Source: https://carlos3g.github.io/element-dropdown/docs/guides/imperative-open-close

# How do I open or close the dropdown from outside?

Use the component's imperative ref. Both `Dropdown` and
`MultiSelect` expose `open()` and `close()`.

```tsx
import { useRef } from 'react';
import { Button, View } from 'react-native';
import { Dropdown } from '@carlos3g/element-dropdown';
import type { IDropdownRef } from '@carlos3g/element-dropdown';

const data = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
];

export function FruitPicker() {
  const ref = useRef<IDropdownRef>(null);

  return (
    <View>
      <Button title="Pick a fruit" onPress={() => ref.current?.open()} />
      <Dropdown
        ref={ref}
        data={data}
        labelField="label"
        valueField="value"
        onChange={() => {}}
      />
    </View>
  );
}
```

Common uses: opening from a bottom-tab press, closing on navigation
events, deep-linking into a selector, or triggering the picker
from a keyboard shortcut on web.

## Watch out

- The ref is only defined **after** mount. Calling `open()` during
  the first render is a no-op. Open from a user gesture, or from
  a `useEffect`:

  ```tsx
  useEffect(() => {
    ref.current?.open();
  }, []);
  ```

- `open()` and `close()` are safe to call when the dropdown is
  disabled — they simply do nothing.

---

# Searching a different field

Source: https://carlos3g.github.io/element-dropdown/docs/guides/custom-search-field

# How do I search by a field other than the label?

By default, `search` matches against `labelField`. To search a
different field, set `searchField`.

```tsx
<Dropdown
  search
  data={users}
  labelField="name"
  valueField="id"
  searchField="email"
  placeholder="Pick a user"
  searchPlaceholder="Search by email…"
  onChange={(user) => setUser(user)}
/>
```

Now typing in the search box filters the list by `user.email`
while the visible label stays as `user.name`.

## Search across multiple fields

Pass `searchField` an array of keys — a row matches if **any** of
the listed fields contains the keyword (after the same accent /
whitespace normalization the single-field path uses):

```tsx
<Dropdown
  search
  data={users}
  labelField="name"
  valueField="id"
  searchField={['name', 'email', 'phone']}
  searchPlaceholder="Search name, email or phone…"
  onChange={setUser}
/>
```

The visible label stays as `user.name`; the search just widens its
net.

## Even more control

If you need locale-aware matching, fuzzy matching, scoring, or
anything else the multi-field path can't express, fall back to a
custom matcher — see
[Custom search matcher](./custom-search-matcher).

---

# Custom search matcher

Source: https://carlos3g.github.io/element-dropdown/docs/guides/custom-search-matcher

# How do I use a custom matcher?

Pass a `searchQuery` callback. The component calls it for each
item, with the current search keyword and the item's label as
resolved by `labelField`. Return `true` to keep the item in the
filtered list.

```tsx
<Dropdown
  search
  data={items}
  labelField="name"
  valueField="id"
  searchQuery={(keyword, labelValue) =>
    labelValue
      .toLocaleLowerCase()
      .normalize('NFD')
      .replace(/\p{Diacritic}/gu, '')
      .includes(keyword.toLocaleLowerCase())
  }
  onChange={(item) => setItem(item)}
/>
```

The example strips diacritics before comparing, so `"sao"`
matches `"São Paulo"`.

## Matching across multiple fields

`searchQuery` only receives the label. To match against other
fields, access the underlying item through your data closure:

```tsx
<Dropdown
  search
  data={items}
  labelField="name"
  valueField="id"
  searchQuery={(keyword, labelValue) => {
    const needle = keyword.toLowerCase();
    const item = items.find((i) => i.name === labelValue);
    return (
      labelValue.toLowerCase().includes(needle) ||
      item?.email?.toLowerCase().includes(needle) ||
      item?.handle?.toLowerCase().includes(needle) ||
      false
    );
  }}
  onChange={(item) => setItem(item)}
/>
```

---

# Disabling individual items

Source: https://carlos3g.github.io/element-dropdown/docs/guides/disabled-items

# How do I disable specific items?

Mark items with a truthy value at a shared field, then point
`disabledField` at that field.

```tsx
const data = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana', locked: true },
  { label: 'Cherry', value: 'cherry' },
];

<Dropdown
  data={data}
  labelField="label"
  valueField="value"
  disabledField="locked"
  onChange={(item) => setValue(item.value)}
/>
```

Disabled items:

- render at reduced opacity (`0.4` by default);
- don't fire `onChange` on press;
- expose `accessibilityState.disabled` to screen readers.

The rest of the list stays interactive.

Works on both `Dropdown` and `MultiSelect`.

## Custom look for disabled rows

Use `renderItem` for full control:

```tsx
<Dropdown
  data={data}
  labelField="label"
  valueField="value"
  disabledField="locked"
  renderItem={(item, selected) => (
    <View
      style={[
        styles.row,
        item.locked && styles.rowLocked,
        selected && styles.rowActive,
      ]}
    >
      <Text style={item.locked && styles.labelLocked}>{item.label}</Text>
    </View>
  )}
/>
```

`disabledField` still governs interactivity — `renderItem` is
purely visual.

---

# Nesting inside a React Native Modal

Source: https://carlos3g.github.io/element-dropdown/docs/guides/nested-in-modal

# How do I use a Dropdown inside a Modal?

Set `isInsideModal={true}`.

```tsx
import { Modal } from 'react-native';
import { Dropdown } from '@carlos3g/element-dropdown';

<Modal visible={visible} onRequestClose={close}>
  <Dropdown
    isInsideModal
    data={data}
    labelField="label"
    valueField="value"
    onChange={(item) => setValue(item.value)}
  />
</Modal>;
```

## Why this prop exists

React Native reports `measureInWindow` coordinates relative to the
outermost native view. Inside a `<Modal>`, that's the Modal's own
root — the status bar is already gone from that frame of reference.
Without the flag, the component adds its internal status-bar
offset (`~24–44 px` on Android) a second time and the list opens
below the trigger by that amount.

Set `isInsideModal={true}` whenever the component renders inside:

- React Native's `<Modal>`
- Libraries that use a native modal underneath (e.g. `react-native-modal`)
- Navigation screens configured as modals (e.g. React Navigation's
  `presentation: 'modal'` — only matters for iOS form sheets)

Default is `false`. Leave it off for normal rendering.

---

# Chip row inside the trigger

Source: https://carlos3g.github.io/element-dropdown/docs/guides/multi-select-inside-mode

# How do I render the chips inside the trigger?

Set `inside={true}`.

```tsx
import { MultiSelect } from '@carlos3g/element-dropdown';

<MultiSelect
  inside
  data={data}
  labelField="label"
  valueField="value"
  placeholder="Pick fruits"
  value={selected}
  onChange={setSelected}
/>;
```

By default, `MultiSelect` renders its selected items as a chip row
**below** the trigger. `inside={true}` moves that row **inline**
inside the trigger's own `View`, which is useful when the component
needs to look like a single form input.

## Also useful

- `visibleSelectedItem={false}` — hide the chip row entirely.
- `alwaysRenderSelectedItem={true}` — keep chips visible while the
  list is open (default is hide-while-open).
- `renderSelectedItem` — fully custom chip rendering.

```tsx
<MultiSelect
  inside
  renderSelectedItem={(item, unSelect) => (
    <Pressable onPress={() => unSelect?.(item)} style={styles.chip}>
      <Text>{item.label} ×</Text>
    </Pressable>
  )}
  {/* … */}
/>
```

---

# Empty state (no results)

Source: https://carlos3g.github.io/element-dropdown/docs/guides/empty-state

# How do I show an empty state?

Pass `ListEmptyComponent` through `flatListProps`. The dropdown
forwards it to the underlying `FlatList`, which renders it when
the current (possibly filtered) list is empty.

```tsx
import { Text, View } from 'react-native';
import { Dropdown } from '@carlos3g/element-dropdown';

<Dropdown
  search
  data={data}
  labelField="label"
  valueField="value"
  flatListProps={{
    ListEmptyComponent: () => (
      <View style={{ padding: 16 }}>
        <Text>No matches.</Text>
      </View>
    ),
  }}
  onChange={(item) => setValue(item.value)}
/>;
```

Works for both "data is empty to begin with" and "search filtered
everything out".

Every other `FlatList` prop is available the same way —
`ListHeaderComponent`, `ItemSeparatorComponent`,
`initialNumToRender`, etc.

---

# Reacting to the cleared search

Source: https://carlos3g.github.io/element-dropdown/docs/guides/on-change-text

# How do I detect when the search is cleared?

`onChangeText` fires on every change to the search input. When
the field is cleared — by the user, by the "X" clear button, or
automatically when the list closes — `onChangeText` fires with
`""`.

```tsx
<Dropdown
  search
  data={data}
  labelField="label"
  valueField="value"
  onChangeText={(text) => {
    if (text === '') {
      // user cleared, or the dropdown closed
    } else {
      // user typed
    }
  }}
  onChange={(item) => setValue(item.value)}
/>
```

## When does the search clear automatically?

The component clears `searchText` (and thus calls
`onChangeText('')`) whenever the list closes, to avoid the
search-input state leaking into the next open. If you want to
persist the query across opens, capture it in parent state inside
`onChangeText` and re-apply it after open via `onFocus`.

---

# Excluding items from the list or from search

Source: https://carlos3g.github.io/element-dropdown/docs/guides/exclusion

# How do I exclude items?

Two props, two different jobs.

## `excludeItems`: hide them completely

Items whose `valueField` matches anything in `excludeItems` do not
render at all.

```tsx
<Dropdown
  data={all}
  excludeItems={archived}
  labelField="label"
  valueField="value"
  onChange={(item) => setValue(item.value)}
/>
```

## `excludeSearchItems`: keep visible, skip in search

Items in `excludeSearchItems` stay in the list but are never
returned by search matches.

```tsx
<Dropdown
  search
  data={all}
  excludeSearchItems={pinned}
  labelField="label"
  valueField="value"
  onChange={(item) => setValue(item.value)}
/>
```

Typical use: pinned or "featured" items that should always be
visible but shouldn't clutter search results when the user types.

---

# Enlarging the tap target

Source: https://carlos3g.github.io/element-dropdown/docs/guides/hit-slop

# How do I make the trigger easier to tap?

Pass `hitSlop`. The prop is forwarded directly to the trigger's
`TouchableWithoutFeedback`.

```tsx
<Dropdown
  hitSlop={{ top: 16, bottom: 16, left: 16, right: 16 }}
  data={data}
  labelField="label"
  valueField="value"
  onChange={(item) => setValue(item.value)}
/>
```

`hitSlop` also accepts a number for symmetrical expansion:

```tsx
<Dropdown hitSlop={12} {/* … */} />
```

Useful when the trigger is small — a narrow chip, an icon-only
selector, or a table row — and you want a forgiving tap area
without changing the visual size.

---

# Respecting the system font scale

Source: https://carlos3g.github.io/element-dropdown/docs/guides/font-scaling

# How do I control font scaling?

Pass `allowFontScaling`. The prop threads through every `Text`
and `TextInput` the component renders itself — the trigger label,
the placeholder, item labels in the default renderer, and the
built-in search input.

```tsx
<Dropdown
  allowFontScaling={false}
  data={data}
  labelField="label"
  valueField="value"
  onChange={(item) => setValue(item.value)}
/>
```

Three sensible choices:

- **Default (`undefined`)** — React Native's default, which is
  `true` on iOS and Android. Labels scale with the user's font-size
  accessibility setting.
- **`true`** — same as default, but explicit.
- **`false`** — locks labels at their declared size. Use sparingly;
  disabling font scaling hurts users who rely on larger text.

If you use `renderItem`, `renderInputSearch`, or
`renderSelectedItem`, you're responsible for font scaling in your
own text.

---

# Customizing the search input

Source: https://carlos3g.github.io/element-dropdown/docs/guides/text-input-passthrough

# How do I change the cursor or selection color on the search input?

The component forwards unknown props straight to the underlying
`TextInput`, so every standard RN prop works.

```tsx
<Dropdown
  search
  selectionColor="#0088ff"
  cursorColor="#0088ff"  // Android only
  data={data}
  labelField="label"
  valueField="value"
  onChange={(item) => setValue(item.value)}
/>
```

Other props that work the same way:

- `keyboardType` / `inputMode`
- `autoCapitalize`
- `returnKeyType`
- `clearButtonMode` (iOS)
- `onSubmitEditing`

## Fully custom search input

When per-prop passthrough isn't enough, use `renderInputSearch`
for full control:

```tsx
<Dropdown
  search
  renderInputSearch={(onSearch) => (
    <TextInput
      placeholder="Search…"
      onChangeText={onSearch}
      style={styles.search}
      keyboardType="email-address"
    />
  )}
  {/* … */}
/>
```

You're responsible for wiring the `onSearch` callback yourself.

---

# Different icons for open and closed

Source: https://carlos3g.github.io/element-dropdown/docs/guides/icon-per-state

# How do I swap the chevron icon when the dropdown opens?

Both `renderLeftIcon` and `renderRightIcon` receive the current
visibility as their argument.

```tsx
import Icon from '@expo/vector-icons/Feather';

<Dropdown
  data={data}
  labelField="label"
  valueField="value"
  renderRightIcon={(visible) => (
    <Icon
      name={visible ? 'chevron-up' : 'chevron-down'}
      size={20}
      color="gray"
    />
  )}
  onChange={(item) => setValue(item.value)}
/>;
```

Same pattern on `renderLeftIcon`. Both arguments are typed as
`visible?: boolean` — the optional `?` just reflects that the
render function is called before the first open with `undefined`;
treat `undefined` the same as `false`.

Works on `Dropdown`, `MultiSelect`, and `SelectCountry`.

---

# Pagination with onEndReached

Source: https://carlos3g.github.io/element-dropdown/docs/guides/end-reached-pagination

# How do I paginate a long dropdown list?

Both `Dropdown` and `MultiSelect` expose `onEndReached` and
`onEndReachedThreshold` first-class, so you can append a page of
data when the user scrolls near the bottom — same shape as
`FlatList`.

```tsx
import { useCallback, useEffect, useState } from 'react';
import { Dropdown } from '@carlos3g/element-dropdown';

type User = { id: string; name: string };

export function PaginatedUsers() {
  const [data, setData] = useState<User[]>([]);
  const [page, setPage] = useState(1);
  const [loading, setLoading] = useState(false);
  const [done, setDone] = useState(false);

  const loadPage = useCallback(async (p: number) => {
    if (loading || done) return;
    setLoading(true);
    const next = await fetchUsers({ page: p, pageSize: 50 });
    setData((prev) => [...prev, ...next]);
    setDone(next.length < 50);
    setLoading(false);
  }, [loading, done]);

  useEffect(() => {
    loadPage(page);
  }, [page, loadPage]);

  return (
    <Dropdown
      data={data}
      labelField="name"
      valueField="id"
      placeholder="Pick a user"
      onChange={(u) => /* … */ undefined}
      onEndReached={() => setPage((p) => p + 1)}
      onEndReachedThreshold={0.4}
    />
  );
}
```

## Notes

- `onEndReachedThreshold` defaults to `0.5` (half a viewport from
  the bottom). Lower it to fire later (closer to the end), raise
  it to prefetch earlier.
- The same props go on `MultiSelect`.
- If you'd rather manage the FlatList behavior yourself, you can
  still pass `flatListProps={{ onEndReached, onEndReachedThreshold,
  ListFooterComponent }}` — the explicit props are just a thinner
  surface for the common case.
- `autoScroll` is ignored while the list is filtered (search
  active), so pagination plays nicely with search out of the box.

---

# Custom trigger

Source: https://carlos3g.github.io/element-dropdown/docs/guides/custom-trigger

# How do I render a fully custom trigger?

The default `Dropdown` trigger is `renderLeftIcon` + label +
`renderRightIcon`. If you need a different layout — e.g. a chip
group, an avatar with subtitle, or a button-shaped control —
return your own JSX from `renderSelectedItem`.

```tsx
import { Image, Text, View } from 'react-native';
import { Dropdown } from '@carlos3g/element-dropdown';

type Country = { code: string; name: string; flag: string };

export function CountryTrigger({ value, data, onChange }) {
  const selected = data.find((c: Country) => c.code === value);

  return (
    <Dropdown
      data={data}
      labelField="name"
      valueField="code"
      value={value}
      onChange={(c) => onChange(c.code)}
      renderSelectedItem={(visible) => (
        <View
          style={{
            flexDirection: 'row',
            alignItems: 'center',
            gap: 8,
            padding: 10,
            borderRadius: 8,
            backgroundColor: visible ? '#EEF2FF' : '#F5F5F5',
          }}
        >
          {selected ? (
            <>
              <Image source={{ uri: selected.flag }} style={{ width: 20, height: 14 }} />
              <Text>{selected.name}</Text>
            </>
          ) : (
            <Text style={{ color: '#888' }}>Pick a country</Text>
          )}
          <Text style={{ marginLeft: 'auto' }}>{visible ? '▴' : '▾'}</Text>
        </View>
      )}
    />
  );
}
```

The function receives one argument:

- `visible: boolean` — whether the dropdown list is currently open.
  Use it to flip caret direction or change the trigger background
  while the list is showing.

## What about `renderLeftIcon` / `renderRightIcon`?

When `renderSelectedItem` is provided it **replaces** the entire
default trigger body — `renderLeftIcon`, the label `<Text>`, and
`renderRightIcon` are not rendered. Compose them inside your
custom JSX if you still want them.

## Trigger versus list rows

- `renderSelectedItem` controls the **trigger** (the always-visible
  control).
- `renderItem` controls each **row inside the list**.

They're independent — you can use both, either, or neither.

---

# Modal header

Source: https://carlos3g.github.io/element-dropdown/docs/guides/modal-header

# How do I add a header above the list?

Set `renderModalHeader` to render any view at the top of the
modal — above the search input, above the list. The function
receives a `close()` callback so you can wire a close/back button.

```tsx
import { Pressable, StyleSheet, Text, View } from 'react-native';
import { Dropdown } from '@carlos3g/element-dropdown';

export function CategoryPicker({ value, onChange, data }) {
  return (
    <Dropdown
      mode="modal"
      search
      data={data}
      labelField="name"
      valueField="id"
      value={value}
      onChange={onChange}
      placeholder="Pick a category"
      renderModalHeader={(close) => (
        <View style={styles.header}>
          <Text style={styles.title}>Categories</Text>
          <Pressable onPress={close} hitSlop={8}>
            <Text style={styles.close}>Close</Text>
          </Pressable>
        </View>
      )}
    />
  );
}

const styles = StyleSheet.create({
  header: {
    flexDirection: 'row',
    alignItems: 'center',
    justifyContent: 'space-between',
    padding: 16,
    borderBottomWidth: StyleSheet.hairlineWidth,
    borderBottomColor: '#DDD',
  },
  title: { fontSize: 17, fontWeight: '600' },
  close: { color: '#007AFF', fontSize: 16 },
});
```

The header sticks to the top of the list container and is
unaffected by `inverted` / `dropdownPosition="top"` — it always
renders at the top of the rendered modal section.

## Use cases

- Title + close button on `mode="modal"` (full-screen) selectors.
- "Apply" / "Reset" actions for `MultiSelect`.
- Brand / logo above a long list.
- Live counter (`"3 of 8 selected"`) for `MultiSelect`.

## See also

- [Custom trigger](./custom-trigger) — replace the trigger body.
- [Disabled items](./disabled-items) — combine with `disabledField`
  to communicate why some rows are non-interactive.

---

# Selected-item ordering & visibility

Source: https://carlos3g.github.io/element-dropdown/docs/guides/selected-ordering

# How do I control where selected items appear in the list?

Three small props let you tune how the dropdown list reacts to
the current selection. They're independent — mix and match.

## Hide selected items

`hideSelectedFromList` removes selected items from the rendered
list entirely. Available on **both** `Dropdown` (single-select)
and `MultiSelect` (multi-select).

```tsx
<MultiSelect
  data={tags}
  value={chosen}
  onChange={setChosen}
  labelField="label"
  valueField="value"
  hideSelectedFromList
/>
```

Useful when the chip row already shows what's selected, so the
list only ever has "things you can still pick".

## Push selected items to the top (MultiSelect)

`selectedToTop` keeps the full list visible but reorders it so
already-selected items come first. No-op when
`hideSelectedFromList` is `true` — they'd be hidden anyway.

```tsx
<MultiSelect
  data={tags}
  value={chosen}
  onChange={setChosen}
  labelField="label"
  valueField="value"
  selectedToTop
/>
```

Helpful for long, sparsely-selected lists where users want to
double-check their selection without scrolling.

## Close the modal on each toggle (MultiSelect)

By default `MultiSelect` keeps the list open after a toggle so
users can keep selecting. Set `closeModalWhenSelectedItem` to
`true` to flip that — useful for "checkbox-style" selectors where
you want the user to think about each pick.

```tsx
<MultiSelect
  data={options}
  value={chosen}
  onChange={setChosen}
  labelField="label"
  valueField="value"
  closeModalWhenSelectedItem
/>
```

`Dropdown` already had this prop with the opposite default
(`true`), since closing on selection is the natural single-select
behavior.

## See also

- [Disabled items](./disabled-items) — gray out specific rows.
- [Exclude items](./exclusion) — drop items from the list /
  search independently of selection state.

---

# Search input passthrough

Source: https://carlos3g.github.io/element-dropdown/docs/guides/search-input-props

# How do I customize the search keyboard, selection color, etc.?

The built-in search input is a regular React Native `<TextInput>`.
Two props let you reach it without writing your own
`renderInputSearch`:

## `searchKeyboardType`

Quick shorthand for the `keyboardType` of the search input — the
single most common thing people want to change.

```tsx
<Dropdown
  search
  searchKeyboardType="email-address"
  data={users}
  labelField="email"
  valueField="id"
  onChange={setUser}
/>
```

Accepts every `KeyboardTypeOptions` value RN supports (`'numeric'`,
`'phone-pad'`, `'decimal-pad'`, `'email-address'`,
`'number-pad'`, etc.).

## `searchInputProps`

Pass any other `TextInputProps` straight through. Useful for
selection color, return-key type, autocapitalization, secure
entry, autofocus — anything `<TextInput>` accepts.

```tsx
<Dropdown
  search
  searchInputProps={{
    selectionColor: '#007AFF',
    returnKeyType: 'search',
    autoCapitalize: 'none',
    autoCorrect: false,
    autoFocus: true,
  }}
  data={users}
  labelField="name"
  valueField="id"
  onChange={setUser}
/>
```

The handful of props the dropdown manages internally (`value`,
`onChangeText`, `placeholder`, `placeholderTextColor`,
`allowFontScaling`, `keyboardType`) are excluded from the
`searchInputProps` type so you can't accidentally fight the
component for control of them. Use `searchPlaceholder`,
`searchPlaceholderTextColor`, `searchKeyboardType`,
`allowFontScaling`, and the existing `inputSearchStyle` for those.

## When to drop down to `renderInputSearch`

If you need a totally different search affordance — a microphone
button, an inline filter chip row, a debounced controlled input
managed elsewhere — `renderInputSearch` still gives you the full
escape hatch.

## See also

- [Custom search field](./custom-search-field) — pick which field(s)
  to match against.
- [Custom search matcher](./custom-search-matcher) — bring your own
  matching function.

---

# Sectioned lists

Source: https://carlos3g.github.io/element-dropdown/docs/guides/sectioned-lists

# How do I group dropdown items under headings?

Pass `sections` instead of `data`. Both `Dropdown` and
`MultiSelect` accept it. When present, the component renders a
`SectionList` with sticky headers; all other behavior (search,
selection, `onChange`, `disabledField`, etc.) is unchanged.

```tsx
import { Dropdown } from '@carlos3g/element-dropdown';

type Fruit = { label: string; value: string };

const sections = [
  {
    title: 'Berries',
    data: [
      { label: 'Strawberry', value: 'str' },
      { label: 'Blueberry', value: 'blu' },
      { label: 'Raspberry', value: 'ras' },
    ],
  },
  {
    title: 'Citrus',
    data: [
      { label: 'Lemon', value: 'lem' },
      { label: 'Orange', value: 'ora' },
      { label: 'Grapefruit', value: 'gra' },
    ],
  },
];

export function FruitPicker({ value, onChange }) {
  return (
    <Dropdown
      sections={sections}
      labelField="label"
      valueField="value"
      value={value}
      onChange={(item) => onChange(item.value)}
      search
      placeholder="Pick a fruit"
    />
  );
}
```

## `data` vs `sections`

- Use **`data`** when your list is a flat array.
- Use **`sections`** when items logically group under a title.

The two are mutually exclusive. If you pass `sections`, `data` is
ignored. If you pass neither, the list is empty.

## Search filters per-section

When `search` is enabled, typing filters items **inside each
section**. Sections that lose all their matches are hidden — you
won't see a lonely header with no rows underneath.

## Default header styling

The built-in section header is an uppercase label on a light gray
background:

- `backgroundColor: '#F5F5F5'`
- `fontSize: 12`, `fontWeight: 600`, `textTransform: 'uppercase'`
- `hairline` bottom border

Tweak it without writing a full renderer:

```tsx
<Dropdown
  sections={sections}
  sectionHeaderStyle={{ backgroundColor: '#EEF2FF' }}
  sectionHeaderTextStyle={{ color: '#4338CA', fontWeight: '700' }}
  // …
/>
```

## Fully custom header

For anything beyond styling tweaks, return your own JSX from
`renderSectionHeader`. The callback receives the full section:

```tsx
import { View, Text } from 'react-native';

<Dropdown
  sections={sections}
  renderSectionHeader={(section) => (
    <View
      style={{
        flexDirection: 'row',
        justifyContent: 'space-between',
        paddingHorizontal: 16,
        paddingVertical: 10,
        backgroundColor: '#0f172a',
      }}
    >
      <Text style={{ color: 'white', fontWeight: '600' }}>
        {section.title}
      </Text>
      <Text style={{ color: '#94a3b8' }}>{section.data.length}</Text>
    </View>
  )}
  // …
/>;
```

Typical uses:

- Counter chips (`"3 items"`) per group
- Collapsible headers driven by local state
- Brand-colored dividers

## Interaction with other props

| Prop | How it interacts with sections |
|---|---|
| `search` / `searchField` / `searchQuery` | Matching runs per-section; sections with no remaining matches are hidden. |
| `disabledField` | Works per-row exactly like in flat mode. |
| `activeColor` / `activeItemTextStyle` | Applied to the selected row wherever it lives. |
| `excludeItems` / `excludeSearchItems` | Applied to each section's `data`. |
| `hideSelectedFromList` | Drops the current selection (or, for MultiSelect, every current selection) from all sections. |
| `selectedToTop` (MultiSelect) | Sorts **within** each section, not across. |
| `renderItem` | Still controls how each row renders. Sections only affect grouping + headers. |
| `autoScroll` | Skipped in sectioned mode — section headers shift offsets, so we don't try to restore scroll to a specific row. |
| `flatListProps` | Ignored — the inner list is a `SectionList`. Use `renderSectionHeader` and the style props for customization. |

## See also

- [Custom search field](./custom-search-field) — works identically
  when sections are used; pass `searchField` or an array of fields.
- [Pagination with `onEndReached`](./end-reached-pagination) —
  fires at the end of the full sectioned list.

---

# Animations

Source: https://carlos3g.github.io/element-dropdown/docs/guides/animations

# How do I animate Dropdown and MultiSelect?

**`@carlos3g/element-dropdown` deliberately ships no animation peer
dependencies.** Animation is your app's concern, not the library's —
we just expose render callbacks you can wrap in whatever your stack
already uses: `react-native-reanimated`, `moti`, RN's built-in
`Animated`, RN's built-in `LayoutAnimation`, or something else.

This guide collects the common recipes. Every snippet works without
any change to the library itself — the callbacks are there today.

## Rotate the chevron on open

`renderRightIcon(visible)` receives the current open/closed state.
Drive any rotation hook off it.

```tsx
// With Reanimated v3
import Animated, {
  useAnimatedStyle,
  withTiming,
} from 'react-native-reanimated';
import { Dropdown } from '@carlos3g/element-dropdown';

function AnimatedChevron({ visible }: { visible?: boolean }) {
  const style = useAnimatedStyle(() => ({
    transform: [{ rotate: withTiming(visible ? '180deg' : '0deg') }],
  }));
  return (
    <Animated.Text style={[{ fontSize: 16 }, style]}>▾</Animated.Text>
  );
}

<Dropdown
  data={data}
  labelField="label"
  valueField="value"
  onChange={onChange}
  renderRightIcon={(visible) => <AnimatedChevron visible={visible} />}
/>
```

## Stagger row enter animations

`renderItem` is called with `(item, selected, index)`. Use the
index to offset each row's entering animation.

```tsx
// With Moti
import { MotiView } from 'moti';
import { Dropdown } from '@carlos3g/element-dropdown';

<Dropdown
  data={data}
  labelField="label"
  valueField="value"
  onChange={onChange}
  renderItem={(item, selected, index = 0) => (
    <MotiView
      from={{ opacity: 0, translateY: -8 }}
      animate={{ opacity: 1, translateY: 0 }}
      transition={{ delay: index * 40 }}
      style={{ padding: 16 }}
    >
      <Text style={{ fontWeight: selected ? '600' : '400' }}>
        {item.label}
      </Text>
    </MotiView>
  )}
/>
```

The same pattern with Reanimated's `FadeIn.delay(index * 40)`:

```tsx
import Animated, { FadeIn } from 'react-native-reanimated';

renderItem={(item, _selected, index = 0) => (
  <Animated.View
    entering={FadeIn.delay(index * 40)}
    style={{ padding: 16 }}
  >
    <Text>{item.label}</Text>
  </Animated.View>
)}
```

## Animate chip add / remove (MultiSelect)

`renderSelectedItem` wraps each chip in the chip row. Return an
animated container and let Reanimated's layout animation handle
enter/exit.

```tsx
import Animated, {
  FadeIn,
  FadeOut,
  LinearTransition,
} from 'react-native-reanimated';
import { MultiSelect } from '@carlos3g/element-dropdown';

<MultiSelect
  data={data}
  labelField="label"
  valueField="value"
  value={value}
  onChange={setValue}
  renderSelectedItem={(item, unSelect) => (
    <Animated.View
      entering={FadeIn}
      exiting={FadeOut}
      layout={LinearTransition}
      style={{
        flexDirection: 'row',
        alignItems: 'center',
        paddingHorizontal: 10,
        paddingVertical: 6,
        borderRadius: 999,
        backgroundColor: '#EEF2FF',
        marginRight: 6,
        marginBottom: 6,
      }}
    >
      <Text>{item.label}</Text>
      <Text onPress={() => unSelect?.(item)} style={{ marginLeft: 8 }}>
        ×
      </Text>
    </Animated.View>
  )}
/>
```

## Zero-dependency option: RN `LayoutAnimation`

React Native ships `LayoutAnimation` — a native-driven animation of
the next layout pass. It's free, requires no peer dep, and works
well for chip rows and list filters that don't need per-row
orchestration.

On Android you must opt in once at startup:

```ts
import { Platform, UIManager } from 'react-native';

if (
  Platform.OS === 'android' &&
  UIManager.setLayoutAnimationEnabledExperimental
) {
  UIManager.setLayoutAnimationEnabledExperimental(true);
}
```

Then call `LayoutAnimation.configureNext(...)` right before the
state change you want animated:

```tsx
import { LayoutAnimation } from 'react-native';
import { MultiSelect } from '@carlos3g/element-dropdown';

<MultiSelect
  data={data}
  labelField="label"
  valueField="value"
  value={value}
  onChange={(next) => {
    LayoutAnimation.configureNext(LayoutAnimation.Presets.easeInEaseOut);
    setValue(next);
  }}
/>
```

The next render's layout changes (chip added or removed, list
reflow) animate natively. Good tradeoff when you don't already have
Reanimated in the tree.

## Open / close the modal itself

Use [`modalAnimationType`](../components/dropdown#container-and-layout) —
forwarded to the underlying React Native `<Modal>`. The library
also honors the OS "Reduce Motion" setting and forces `'none'`
regardless of the prop. See the [Accessibility](../accessibility)
page for the full story.

```tsx
<Dropdown
  // ...
  modalAnimationType="fade"
/>
```

If you need a fully custom modal backdrop (e.g. animated blur),
that's intentionally **not** exposed — replacing the `<Modal>`
wholesale has too many edge cases (accessibility scope, Android
back-button handling, reduce-motion plumbing). If you have a
concrete use case, open an issue.

## What the library will never do

- **Ship an animation peer dependency.** Your app picks the stack.
- **Bake animations into defaults.** Opting in via a callback is
  the only path — no surprise motion when you upgrade.
- **Expose `Animated.Value` / shared values.** Those are
  stack-specific; the render callbacks give you strings and
  booleans, and your animation code owns the hooks.

---