SelectUpdated

Import

import { Select } from 'heroui-native';

Anatomy

<Select>
  <Select.Trigger>
    <Select.Value />
    <Select.TriggerIndicator />
  </Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content>
      <Select.Close />
      <Select.ListLabel>...</Select.ListLabel>
      <Select.Item>
        <Select.ItemLabel />
        <Select.ItemDescription>...</Select.ItemDescription>
        <Select.ItemIndicator />
      </Select.Item>
    </Select.Content>
  </Select.Portal>
</Select>

• Select: Main container that manages open/close state, value selection and provides context to child components.
• Select.Trigger: Clickable element that toggles the select visibility. Wraps any child element with press handlers. Supports variant prop ('default' or 'unstyled').
• Select.Value: Displays the selected value or placeholder text. Automatically updates when selection changes. Styling changes based on selection state.
• Select.TriggerIndicator: Optional visual indicator showing open/close state. Renders an animated chevron icon by default that rotates when the select opens/closes.
• Select.Portal: Renders select content in a portal layer above other content. Ensures proper stacking and positioning.
• Select.Overlay: Optional background overlay. Can be transparent or semi-transparent to capture outside clicks.
• Select.Content: Container for select content with three presentation modes: popover (floating with positioning), bottom sheet modal, or dialog modal.
• Select.Close: Close button for the select. Can accept custom children or uses default close icon.
• Select.ListLabel: Label for the list of items with pre-styled typography.
• Select.Item: Selectable option item. Handles selection state and press events.
• Select.ItemLabel: Displays the label text for an item.
• Select.ItemDescription: Optional description text for items with muted styling.
• Select.ItemIndicator: Optional indicator shown for selected items. Renders a check icon by default.

Usage

Basic Usage

The Select component uses compound parts to create dropdown selection interfaces.

<Select>
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content presentation="popover">
      <Select.Item value="1" label="Option 1" />
      <Select.Item value="2" label="Option 2" />
    </Select.Content>
  </Select.Portal>
</Select>

With Value Display

Display the selected value in the trigger using the Value component.

<Select>
  <Select.Trigger>
    <Select.Value placeholder="Choose an option" />
    <Select.TriggerIndicator />
  </Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content presentation="popover">
      <Select.Item value="apple" label="Apple" />
      <Select.Item value="orange" label="Orange" />
      <Select.Item value="banana" label="Banana" />
    </Select.Content>
  </Select.Portal>
</Select>

Popover Presentation

Use popover presentation for floating content with automatic positioning.

<Select>
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content presentation="popover" placement="bottom" align="center">
      <Select.Item value="1" label="Item 1" />
      <Select.Item value="2" label="Item 2" />
    </Select.Content>
  </Select.Portal>
</Select>

Width Control

Control the width of the select content using the width prop. This only works with popover presentation.

{
  /* Fixed width in pixels */
}
<Select>
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content presentation="popover" width={280}>
      <Select.Item value="1" label="Item 1" />
    </Select.Content>
  </Select.Portal>
</Select>;

{
  /* Match trigger width */
}
<Select>
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content presentation="popover" width="trigger">
      <Select.Item value="1" label="Item 1" />
    </Select.Content>
  </Select.Portal>
</Select>;

{
  /* Full width (100%) */
}
<Select>
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content presentation="popover" width="full">
      <Select.Item value="1" label="Item 1" />
    </Select.Content>
  </Select.Portal>
</Select>;

{
  /* Auto-size to content (default) */
}
<Select>
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content presentation="popover" width="content-fit">
      <Select.Item value="1" label="Item 1" />
    </Select.Content>
  </Select.Portal>
</Select>;

Bottom Sheet Presentation

Use bottom sheet for mobile-optimized selection experience.

<Select presentation="bottom-sheet">
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content presentation="bottom-sheet" snapPoints={['35%']}>
      <Select.Item value="1" label="Item 1" />
      <Select.Item value="2" label="Item 2" />
    </Select.Content>
  </Select.Portal>
</Select>

Dialog Presentation

Use dialog presentation for centered modal-style selection.

<Select presentation="dialog">
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content presentation="dialog">
      <Select.Close />
      <Select.ListLabel>Choose an option</Select.ListLabel>
      <Select.Item value="1" label="Item 1" />
      <Select.Item value="2" label="Item 2" />
    </Select.Content>
  </Select.Portal>
</Select>

Custom Item Content

Customize item appearance with custom content and indicators.

<Select>
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content presentation="popover">
      <Select.Item value="us" label="United States">
        <View className="flex-row items-center gap-3 flex-1">
          <Text>🇺🇸</Text>
          <Select.ItemLabel />
        </View>
        <Select.ItemIndicator />
      </Select.Item>
      <Select.Item value="uk" label="United Kingdom">
        <View className="flex-row items-center gap-3 flex-1">
          <Text>🇬🇧</Text>
          <Select.ItemLabel />
        </View>
        <Select.ItemIndicator />
      </Select.Item>
    </Select.Content>
  </Select.Portal>
</Select>

With Render Function

Use a render function on Select.Item to access state and customize content based on selection.

<Select>
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content presentation="popover">
      <Select.Item value="us" label="United States">
        {({ isSelected, value, isDisabled }) => (
          <>
            <View className="flex-row items-center gap-3 flex-1">
              <Text>🇺🇸</Text>
              <Select.ItemLabel
                className={
                  isSelected ? 'text-accent font-medium' : 'text-foreground'
                }
              />
            </View>
            <Select.ItemIndicator />
          </>
        )}
      </Select.Item>
      <Select.Item value="uk" label="United Kingdom">
        {({ isSelected }) => (
          <>
            <View className="flex-row items-center gap-3 flex-1">
              <Text>🇬🇧</Text>
              <Select.ItemLabel
                className={
                  isSelected ? 'text-accent font-medium' : 'text-foreground'
                }
              />
            </View>
            <Select.ItemIndicator />
          </>
        )}
      </Select.Item>
    </Select.Content>
  </Select.Portal>
</Select>

With Item Description

Add descriptions to items for additional context.

<Select>
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content presentation="popover">
      <Select.Item value="basic" label="Basic">
        <View className="flex-1">
          <Select.ItemLabel />
          <Select.ItemDescription>
            Essential features for personal use
          </Select.ItemDescription>
        </View>
        <Select.ItemIndicator />
      </Select.Item>
    </Select.Content>
  </Select.Portal>
</Select>

With Trigger Indicator

Add a visual indicator to show the open/close state of the select. The indicator rotates when the select opens/closes.

<Select>
  <Select.Trigger>
    <Select.Value placeholder="Select one" />
    <Select.TriggerIndicator />
  </Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content presentation="popover">
      <Select.Item value="1" label="Option 1" />
      <Select.Item value="2" label="Option 2" />
    </Select.Content>
  </Select.Portal>
</Select>

Custom Trigger with Unstyled Variant

Use the unstyled variant when composing a custom trigger with other components like Button.

<Select>
  <Select.Trigger variant="unstyled" asChild>
    <Button variant="secondary">
      <Select.Value placeholder="Select..." />
      <Select.TriggerIndicator />
    </Button>
  </Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content presentation="popover">
      <Select.Item value="1" label="Option 1" />
      <Select.Item value="2" label="Option 2" />
    </Select.Content>
  </Select.Portal>
</Select>

Controlled Mode

Control the select state programmatically.

const [value, setValue] = useState();
const [isOpen, setIsOpen] = useState(false);

<Select
  value={value}
  onValueChange={setValue}
  isOpen={isOpen}
  onOpenChange={setIsOpen}
>
  <Select.Trigger>
    <Select.Value placeholder="Select..." />
    <Select.TriggerIndicator />
  </Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content presentation="popover">
      <Select.Item value="1" label="Option 1" />
      <Select.Item value="2" label="Option 2" />
    </Select.Content>
  </Select.Portal>
</Select>;

Example

import { Select, Separator } from 'heroui-native';
import React, { useState } from 'react';

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

const US_STATES: SelectOption[] = [
  { value: 'CA', label: 'California' },
  { value: 'NY', label: 'New York' },
  { value: 'TX', label: 'Texas' },
  { value: 'FL', label: 'Florida' },
];

export default function SelectExample() {
  const [value, setValue] = useState<SelectOption | undefined>();

  return (
    <Select value={value} onValueChange={setValue}>
      <Select.Trigger>
        <Select.Value placeholder="Select one" />
        <Select.TriggerIndicator />
      </Select.Trigger>
      <Select.Portal>
        <Select.Overlay />
        <Select.Content presentation="popover" width="trigger">
          <Select.ListLabel className="mb-2">Choose a state</Select.ListLabel>
          {US_STATES.map((state, index) => (
            <React.Fragment key={state.value}>
              <Select.Item value={state.value} label={state.label} />
              {index < US_STATES.length - 1 && <Separator />}
            </React.Fragment>
          ))}
        </Select.Content>
      </Select.Portal>
    </Select>
  );
}

You can find more examples in the GitHub repository.

API Reference

Select

SelectRootAnimation

Animation configuration for Select component. Can be:

• false or "disabled": Disable only root animations
• "disable-all": Disable all animations including children
• true or undefined: Use default animations
• object: Custom animation configuration

SpringAnimationConfig

TimingAnimationConfig

Select.Trigger

Select.Value

Note: The value component automatically applies different text colors based on selection state:

• When a value is selected: text-foreground
• When no value is selected (placeholder): text-field-placeholder

Select.TriggerIndicator

Note: The following style properties are occupied by animations and cannot be set via className:

• transform (specifically rotate) - Animated for open/close rotation transitions

To customize this property, use the animation prop. To completely disable animated styles and use your own via className or style prop, set isAnimatedStyleActive={false}.

SelectTriggerIndicatorIconProps

SelectTriggerIndicatorAnimation

Animation configuration for Select.TriggerIndicator component. Can be:

• false or "disabled": Disable all animations
• true or undefined: Use default animations (rotation from 0° to -180°)
• object: Custom animation configuration

Select.Portal

Select.Overlay

SelectOverlayAnimation

Animation configuration for Select.Overlay component. Can be:

• false or "disabled": Disable all animations
• true or undefined: Use default animations (progress-based opacity for bottom-sheet/dialog, Keyframe animations for popover)
• object: Custom animation configuration

Select.Content (Popover Presentation)

SelectContentPopoverAnimation

Animation configuration for Select.Content component (popover presentation). Can be:

• false or "disabled": Disable all animations
• true or undefined: Use default Keyframe animations (translateY/translateX, scale, opacity based on placement)
• object: Custom animation configuration with entering and/or exiting Keyframe animations

Select.Content (Bottom Sheet Presentation)

Select.Content (Dialog Presentation)

styles

SelectContentAnimation

Animation configuration for Select.Content component (dialog presentation). Can be:

• false or "disabled": Disable all animations
• true or undefined: Use default Keyframe animations (scale and opacity transitions)
• object: Custom animation configuration with entering and/or exiting Keyframe animations

Select.Close

Select.Close extends CloseButton and automatically handles select dismissal when pressed.

Select.ListLabel

Select.Item

SelectItemRenderProps

When using a render function for children, the following props are provided:

Select.ItemLabel

Select.ItemDescription

Select.ItemIndicator

SelectItemIndicatorIconProps

Hooks

useSelect

Hook to access the Select root context. Returns the select state and control functions.

import { useSelect } from 'heroui-native';

const {
  isOpen,
  onOpenChange,
  isDefaultOpen,
  isDisabled,
  presentation,
  triggerPosition,
  setTriggerPosition,
  contentLayout,
  setContentLayout,
  nativeID,
  value,
  onValueChange,
} = useSelect();

Return Value

Note: This hook must be used within a Select component. It will throw an error if called outside of the select context.

useSelectAnimation

Hook to access the Select animation state values within custom components or compound components.

import { useSelectAnimation } from 'heroui-native';

const { selectState, progress, isDragging, isGestureReleaseAnimationRunning } =
  useSelectAnimation();

Return Value

Note: This hook must be used within a Select component. It will throw an error if called outside of the select animation context.

SelectOption

useSelectItem

Hook to access the Select Item context. Returns the item's value and label.

import { useSelectItem } from 'heroui-native';

const { itemValue, label } = useSelectItem();

Return Value

Special Notes

Element Inspector (iOS)

Select uses FullWindowOverlay on iOS. To enable the React Native element inspector during development, set disableFullWindowOverlay={true} on Select.Portal. Tradeoff: the select dropdown will not appear above native modals when disabled.