AutocompleteNew

Autocomplete extends the heroui-native Select (selection, open state, and presentation) and SearchField (in-content filtering). Selection lives on the trigger while the search input is rendered inside the portaled content — it is a searchable select, not a free-text combo box.

Import

import { Autocomplete } from 'heroui-native-pro';

Anatomy

<Autocomplete>
  <Label>...</Label>
  <Autocomplete.Trigger>
    <Autocomplete.Value />
    <Autocomplete.ClearButton />
    <Autocomplete.TriggerIndicator />
  </Autocomplete.Trigger>
  <Autocomplete.Portal>
    <Autocomplete.Overlay />
    <Autocomplete.Content presentation="popover" width="trigger">
      <Autocomplete.SearchField />
      <Autocomplete.List>
        <Autocomplete.Item value="..." label="..." />
      </Autocomplete.List>
      <Autocomplete.Empty />
    </Autocomplete.Content>
  </Autocomplete.Portal>
  <Description>...</Description>
</Autocomplete>

• Autocomplete: Root that wraps Select and manages the search text, item filtering, clear behavior, and form field context (for Label, Description, FieldError). Supports single and multiple selection, controlled and uncontrolled modes.
• Autocomplete.Trigger: Pressable field surface that toggles the overlay. Inherits invalid border styling from the root.
• Autocomplete.Value: Selected label(s) or placeholder (defaults to "Select an item").
• Autocomplete.ClearButton: Optional close button inside the trigger row that clears the selection and calls onClear. Hidden while nothing is selected.
• Autocomplete.TriggerIndicator: Chevron indicator that rotates with the open state.
• Autocomplete.Portal: Portal wrapper that re-provides the Autocomplete context across the portal boundary.
• Autocomplete.Overlay: Backdrop overlay behind the content. Tinted for the dialog and bottom-sheet presentations; transparent for popovers, where it only provides tap-outside dismissal.
• Autocomplete.Content: Content container. Supports "popover", "dialog", and "bottom-sheet" presentations.
• Autocomplete.SearchField: Search input wired to the autocomplete search text. Renders a default SearchField composition when no children are given.
• Autocomplete.List: Scrollable list container (keyboardShouldPersistTaps="handled") with a capped height.
• Autocomplete.Item: Selectable option filtered by the search text. textValue overrides label for matching.
• Autocomplete.ItemLabel / ItemDescription / ItemIndicator: Item content parts (same as Select).
• Autocomplete.ListLabel: Section label for grouped items.
• Autocomplete.Empty: Fallback shown when no item matches the search text (also covers an empty collection).
• Autocomplete.Close: Close button for the overlay (useful for dialog and bottom-sheet presentations).

Usage

Basic Usage

The autocomplete uses a popover presentation by default. Items are filtered as the user types with a case- and diacritic-insensitive "contains" match.

<Autocomplete>
  <Label>State</Label>
  <Autocomplete.Trigger>
    <Autocomplete.Value />
    <Autocomplete.TriggerIndicator />
  </Autocomplete.Trigger>
  <Autocomplete.Portal>
    <Autocomplete.Overlay />
    <Autocomplete.Content presentation="popover" width="trigger">
      <Autocomplete.SearchField />
      <Autocomplete.List>
        <Autocomplete.Item value="ca" label="California" />
        <Autocomplete.Item value="tx" label="Texas" />
        <Autocomplete.Item value="ny" label="New York" />
      </Autocomplete.List>
      <Autocomplete.Empty />
    </Autocomplete.Content>
  </Autocomplete.Portal>
</Autocomplete>

With Clear Button

Add Autocomplete.ClearButton to the trigger row. It stays hidden while nothing is selected; pressing it clears the selection and calls onClear from the root.

<Autocomplete onClear={handleClear}>
  <Autocomplete.Trigger>
    <Autocomplete.Value />
    <Autocomplete.ClearButton />
    <Autocomplete.TriggerIndicator />
  </Autocomplete.Trigger>
  <Autocomplete.Portal>...</Autocomplete.Portal>
</Autocomplete>

Multiple Selection

Set selectionMode="multiple". The trigger shows a formatted list of the selected labels, and items stay open on press.

import type { AutocompleteOption } from 'heroui-native-pro';
import { useState } from 'react';

const [selected, setSelected] = useState<AutocompleteOption[]>([]);

<Autocomplete
  selectionMode="multiple"
  value={selected}
  onValueChange={setSelected}
>
  <Autocomplete.Trigger>
    <Autocomplete.Value placeholder="Select states" />
    <Autocomplete.ClearButton />
    <Autocomplete.TriggerIndicator />
  </Autocomplete.Trigger>
  <Autocomplete.Portal>...</Autocomplete.Portal>
</Autocomplete>;

Controlled

Control the selected option with value / onValueChange, the overlay with isOpen / onOpenChange, and the search text with inputValue / onInputChange.

import type { AutocompleteOption } from 'heroui-native-pro';
import { useState } from 'react';

const [selected, setSelected] = useState<AutocompleteOption | undefined>({
  value: 'ca',
  label: 'California',
});
const [isOpen, setIsOpen] = useState(false);
const [search, setSearch] = useState('');

<Autocomplete
  value={selected}
  onValueChange={setSelected}
  isOpen={isOpen}
  onOpenChange={setIsOpen}
  inputValue={search}
  onInputChange={setSearch}
>
  <Autocomplete.Trigger>...</Autocomplete.Trigger>
  <Autocomplete.Portal>...</Autocomplete.Portal>
</Autocomplete>;

Custom Filter

Pass a filter predicate to replace the default "contains" match — e.g. a "starts with" match, or an always-true filter when the item collection is filtered externally (async search).

<Autocomplete
  filter={(textValue, inputValue) =>
    textValue.toLowerCase().startsWith(inputValue.trim().toLowerCase())
  }
>
  ...
</Autocomplete>

Filter Text Override

Use textValue on items to match against different text than the visible label (e.g. keywords).

<Autocomplete.Item value="ny" label="New York" textValue="New York NYC Big Apple" />

Sections

Group items with Autocomplete.ListLabel.

<Autocomplete.List>
  <Autocomplete.ListLabel>West Coast</Autocomplete.ListLabel>
  <Autocomplete.Item value="ca" label="California" />
  <Autocomplete.Item value="wa" label="Washington" />
  <Autocomplete.ListLabel>East Coast</Autocomplete.ListLabel>
  <Autocomplete.Item value="ny" label="New York" />
</Autocomplete.List>

Empty State

Autocomplete.Empty renders only when no registered item matches the current search text. String (or omitted) children render styled muted text; custom nodes render as-is.

<Autocomplete.Content presentation="popover" width="trigger">
  <Autocomplete.SearchField />
  <Autocomplete.List>...</Autocomplete.List>
  <Autocomplete.Empty>No matching states.</Autocomplete.Empty>
</Autocomplete.Content>

Dialog and Bottom Sheet Presentations

Match presentation between the root and Autocomplete.Content, exactly like Select.

The default Autocomplete.SearchField input autofocuses when the overlay opens, for every presentation. Because of that, the bottom sheet defaults to a fixed snapPoints={['90%']} with enableDynamicSizing={false} so its content sits above the keyboard from the start, together with keyboardBehavior="extend", keyboardBlurBehavior="restore", android_keyboardInputMode="adjustResize", and bottom-sheet-aware focus/blur handlers on the input. Selecting an item that closes the overlay also dismisses the keyboard. All of these props can be overridden (e.g. autoFocus={false} on Autocomplete.SearchField).

<Autocomplete presentation="bottom-sheet">
  <Autocomplete.Trigger>
    <Autocomplete.Value />
    <Autocomplete.TriggerIndicator />
  </Autocomplete.Trigger>
  <Autocomplete.Portal>
    <Autocomplete.Overlay />
    <Autocomplete.Content presentation="bottom-sheet">
      <Autocomplete.SearchField />
      <Autocomplete.List>...</Autocomplete.List>
      <Autocomplete.Empty />
    </Autocomplete.Content>
  </Autocomplete.Portal>
</Autocomplete>

For the dialog presentation, position the content below the top safe-area inset (instead of the centered default) so the keyboard cannot cover it:

import { useSafeAreaInsets } from 'react-native-safe-area-context';

const insets = useSafeAreaInsets();

<Autocomplete.Content
  presentation="dialog"
  classNames={{ wrapper: 'justify-start' }}
  styles={{ wrapper: { paddingTop: insets.top + 12 } }}
>
  ...
</Autocomplete.Content>;

Field States

Use root props for required, invalid, and disabled states. Combine isInvalid with FieldError to display validation messages; the trigger shows a danger border.

<Autocomplete isInvalid>
  <Label>State</Label>
  <Autocomplete.Trigger>
    <Autocomplete.Value />
    <Autocomplete.TriggerIndicator />
  </Autocomplete.Trigger>
  <Autocomplete.Portal>...</Autocomplete.Portal>
  <Description hideOnInvalid>Where you currently live.</Description>
  <FieldError>Please select a state.</FieldError>
</Autocomplete>

Example

import { Label } from 'heroui-native';
import { Autocomplete } from 'heroui-native-pro';
import { View } from 'react-native';

const STATES = [
  { value: 'ca', label: 'California' },
  { value: 'tx', label: 'Texas' },
  { value: 'fl', label: 'Florida' },
  { value: 'ny', label: 'New York' },
  { value: 'wa', label: 'Washington' },
];

export default function AutocompleteExample() {
  return (
    <View className="flex-1 justify-center px-5">
      <Autocomplete>
        <Label>State</Label>
        <Autocomplete.Trigger>
          <Autocomplete.Value placeholder="Select a state" />
          <Autocomplete.ClearButton />
          <Autocomplete.TriggerIndicator />
        </Autocomplete.Trigger>
        <Autocomplete.Portal>
          <Autocomplete.Overlay />
          <Autocomplete.Content presentation="popover" width="trigger">
            <Autocomplete.SearchField placeholder="Search states..." />
            <Autocomplete.List>
              {STATES.map((state) => (
                <Autocomplete.Item
                  key={state.value}
                  value={state.value}
                  label={state.label}
                />
              ))}
            </Autocomplete.List>
            <Autocomplete.Empty />
          </Autocomplete.Content>
        </Autocomplete.Portal>
      </Autocomplete>
    </View>
  );
}

API Reference

Autocomplete

Extends all Select root props (generic on selectionMode).

AutocompleteOption

AutocompleteFilter

type AutocompleteFilter = (textValue: string, inputValue: string) => boolean;

The default filter is a case- and diacritic-insensitive "contains" match (exported as defaultAutocompleteFilter).

Autocomplete.Trigger

Autocomplete.Value

Autocomplete.TriggerIndicator

Same as Select.TriggerIndicator — an animated chevron that rotates with the open state (animation, iconProps, isAnimatedStyleActive).

Autocomplete.ClearButton

Extends CloseButton (which extends Button). Hidden while nothing is selected. Renders as a compact 24px button (icon size 14) with hitSlop preserving the touch target.

Autocomplete.Portal / Autocomplete.Overlay / Autocomplete.Content / Autocomplete.ContentBackground

Same props as the corresponding Select parts. Autocomplete.Content is a union type discriminated by presentation ('popover' with width, 'dialog' with isSwipeable, 'bottom-sheet' with BottomSheetProps).

For the bottom-sheet presentation, the sheet defaults to a fixed snapPoints={['90%']} with enableDynamicSizing={false} — the search input autofocuses on open, so the sheet must be tall enough from the start to keep the content above the keyboard. Keyboard props default to keyboardBehavior="extend", keyboardBlurBehavior="restore", and android_keyboardInputMode="adjustResize". Pass any of these props explicitly to override.

Autocomplete.SearchField

Extends SearchField root props (minus value / onChange, which come from the root). The default input uses variant="secondary" and wires bottom-sheet-aware focus/blur handlers (no-ops outside a bottom sheet).

Autocomplete.List

Autocomplete.Item

Extends Select.Item.

Autocomplete.ItemLabel / ItemDescription / ItemIndicator / ListLabel / Close

Same props as the corresponding Select parts.

Autocomplete.Empty

Hooks

useAutocomplete

Hook to access the Autocomplete context. Must be used within an Autocomplete component.

import { useAutocomplete } from 'heroui-native-pro';

const { inputValue, onInputChange, visibleItemCount } = useAutocomplete();

Returns: AutocompleteContextValue

Selection and open state live in the wrapped Select — read them with useSelect from heroui-native inside the autocomplete subtree.