Select

tsx

Select provides a dropdown menu for choosing from a list of options. It's fully accessible with keyboard navigation, supports typeahead search, and automatically stacks above other content.

Installation

Select is already installed in tamagui, or you can install it independently:

bash

npm install @tamagui/select

<Notice theme="blue"> For native apps, we recommend [setting up native portals](/docs/components/portal#native-portal-setup-recommended) to preserve React context inside Select content. </Notice>

Anatomy

tsx

import { Select } from 'tamagui' // or '@tamagui/select'

export default () => (
  <Select defaultValue="">
    <Select.Trigger>
      <Select.Value placeholder="Search..." />
    </Select.Trigger>
    <Select.FocusScope loop trapped focusOnIdle={true}>
      <Select.Content>
        <Select.ScrollUpButton />
        <Select.Viewport>
          <Select.Group>
            <Select.Label />
            <Select.Item>
              <Select.ItemText />
            </Select.Item>
          </Select.Group>
        </Select.Viewport>
        <Select.ScrollDownButton />
      </Select.Content>
    </Select.FocusScope>
  </Select>
)

<Notice> Note that Select only works on Native using the Adapt component to adapt it to a Sheet. See below for docs. </Notice>

API Reference

Contains every component for the select:

<PropsTable data={[ { name: 'id', type: 'string', description: Optional for usage with Label., }, { name: 'size', type: 'SizeTokens', description: Set the size of itself and pass to all inner elements., }, { name: 'children', type: 'React.ReactNode', description: Select children API components., }, { name: 'value', type: 'string', description: Controlled value., }, { name: 'defaultValue', type: 'string', description: Default value., }, { name: 'onValueChange', type: '(value: string) => void', description: Callback on value change., }, { name: 'open', type: 'boolean', description: Controlled open value., }, { name: 'defaultOpen', type: 'boolean', description: Default open value., }, { name: 'onOpenChange', type: '(open: boolean) => void', description: Callback on open change., }, { name: 'dir', type: 'Direction', description: Direction of text display., }, { name: 'name', type: 'string', description: For use in forms., }, { name: 'native', type: 'NativeValue', description: If passed, will render a native component instead of the custom one. Currently only \web` is supported., }, { name: 'renderValue', type: '(value: string) => ReactNode', description: Render function for the selected value. Useful for SSR when you need custom display text. By default, Select falls back to showing the raw value for SSR compatibility., }, { name: 'lazyMount', type: 'boolean', default: 'false', description: When true, defers mounting Select items until opened using React's startTransition. Significantly improves initial render performance for pages with many Selects. Should be combined with `renderValue` for best results., }, { name: 'zIndex', type: 'number', description: z-index for the select portal. Use when select dropdowns need to appear above other portaled content like dialogs or fixed headers. Defaults to automatic stacking (~100000).`, }, ]} />

Select.Trigger

Extends ListItem to give sizing, icons, and more.

Select.Value

Extends Paragraph, adding:

Select.Content

Main container for Select content, used to contain the up/down arrows, no API beyond children.

Select.ScrollUpButton

Inside Content first, displays when you can scroll up, stuck to the top.

Extends YStack.

Select.ScrollDownButton

Inside Content last, displays when you can scroll down, stuck to the bottom.

Extends YStack.

Select.Viewport

Extends ThemeableStack. Contains scrollable content items as children.

<Notice> Make sure to not pass `height` prop as that is managed internally because of UX reasons and having a fixed height will break that behavior. </Notice>

Select.Group

Extends YStack. Use only when grouping together items, alongside a Label as the first child.

Select.Label

Extends SizableText. Used to label Groups. Includes size-based padding and minHeight for consistent appearance with other Select items.

Select.Item

Extends ListItem. Used to add selectable values to the list. Must provide an index as React Native doesn't give any escape hatch for us to configure that automatically.

<PropsTable data={[ { name: 'index', type: 'number', required: true, description: Incrementally starting from 0, matching its appearance in the list., },

{
  name: 'value',
  type: 'string',
  description: `Provide a value that will be passed on selection.`,
},

]} />

Select.ItemText

Extends Paragraph. Used inside Item to provide unselectable text that will show above once selected in the parent Select.

Select.Indicator

An animated indicator that highlights the currently focused item. Place it inside Select.Viewport to enable a smooth sliding highlight animation as users navigate through options.

tsx

<Select.Viewport>
  <Select.Indicator transition="quick" />
  <Select.Group></Select.Group>
</Select.Viewport>

Use the transition prop to control the animation speed. You can use any animation name from your config like quick, quicker, or quickest.

<Notice> By default, Select uses the item's `hoverStyle` and `pressStyle` for hover feedback. Add `Select.Indicator` for a smoother animated effect. If using the indicator, you may want to set items to have transparent hover styles to avoid visual conflict. </Notice>

Select.FocusScope

Provides access to the underlying FocusScope component used by Select for focus management. Can be used to control focus behavior from a parent component.

<PropsTable data={[ { name: 'enabled', type: 'boolean', default: 'true', description: Whether focus management is enabled., }, { name: 'loop', type: 'boolean', default: 'false', description: When true, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tabbable., }, { name: 'trapped', type: 'boolean', default: 'false', description: When true, focus cannot escape the focus scope via keyboard, pointer, or programmatic focus., }, { name: 'focusOnIdle', type: 'boolean | number', default: 'false', description: When true, waits for idle before focusing. When a number, waits that many ms. This prevents reflows during animations., }, { name: 'onMountAutoFocus', type: '(event: Event) => void', description: Event handler called when auto-focusing on mount. Can be prevented., }, { name: 'onUnmountAutoFocus', type: '(event: Event) => void', description: Event handler called when auto-focusing on unmount. Can be prevented., }, ]} />

Performance

For pages with many Select components, you can significantly improve initial render performance by using the lazyMount prop combined with renderValue:

tsx

const labels = {
  apple: 'Apple',
  orange: 'Orange',
  banana: 'Banana',
}

<Select
  lazyMount
  renderValue={(value) => labels[value]}
  defaultValue="apple"
>
  <Select.Trigger>
    <Select.Value />
  </Select.Trigger>
  <Select.Content>
    <Select.Viewport>
      <Select.Item index={0} value="apple">
        <Select.ItemText>Apple</Select.ItemText>
      </Select.Item>
    </Select.Viewport>
  </Select.Content>
</Select>

How it works:

lazyMount defers mounting all Select items until the dropdown is first opened
The mount happens inside React's startTransition, keeping the trigger responsive
renderValue provides the display text synchronously, avoiding the need to mount items just to show the selected value
Once mounted, items stay mounted for fast subsequent opens

This is especially useful when rendering many Selects on a single page, as each Select with 20+ items would otherwise mount all those items on initial page load.

Select.Sheet

When used alongside <Adapt />, Select will render as a sheet when that breakpoint is active.

This is the only way to render a Select on Native for now, as mobile apps tend to show Select very differently from web and Tamagui wants to present the right abstractions for each platform.

See Sheet for more props.

Must use Select.Adapt.Contents inside the Select.Sheet.Frame to insert the contents given to Select.Content

tsx

import { Select } from 'tamagui' // or '@tamagui/select'

export default () => (
  <Select defaultValue="">
    <Select.Trigger>
      <Select.Value placeholder="Search..." />
    </Select.Trigger>

    <Adapt when="max-md" platform="touch">
      <Sheet>
        <Sheet.Frame>
          <Adapt.Contents />
        </Sheet.Frame>
        <Sheet.Overlay />
      </Sheet>
    </Adapt>

    <Select.Content>
      <Select.ScrollUpButton />
      <Select.Viewport>
        <Select.Group>
          <Select.Label />
          <Select.Item>
            <Select.ItemText />
          </Select.Item>
        </Select.Group>
      </Select.Viewport>
      <Select.ScrollDownButton />
    </Select.Content>
  </Select>
)