GitHub

Select

Show a menu of items that users can select from

Features

  • Comes with styling, yet completely customizable and themeable.

  • Accepts animations, themes, size props and more.

  • Accessible, keyboard navigable, full-featured.

Installation

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

yarn add @tamagui/select

For native apps, we recommend setting up native portals to preserve React context inside Select content.

Anatomy

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



export default () => (

  <Select defaultValue="">

    <Select.Trigger>

      <Select.Value placeholder="Search..." />

    </Select.Trigger>

    {/* Optional: Control focus behavior */}

    <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>

)

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

API Reference

Select

Contains every component for the select:

Props

  • id

    string

    Optional for usage with Label.

  • size

    SizeTokens

    Set the size of itself and pass to all inner elements.

  • children

    React.ReactNode

    Select children API components.

  • value

    string

    Controlled value.

  • defaultValue

    string

    Default value.

  • onValueChange

    (value: string) => void

    Callback on value change.

  • open

    boolean

    Controlled open value.

  • defaultOpen

    boolean

    Default open value.

  • onOpenChange

    (open: boolean) => void

    Callback on open change.

  • dir

    Direction

    Direction of text display.

  • name

    string

    For use in forms.

  • native

    NativeValue

    If passed, will render a native component instead of the custom one. Currently only `web` is supported.

  • renderValue

    (value: string) => ReactNode

    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.

    • Select.Trigger

    Extends ListItem to give sizing, icons, and more.

    Select.Value

    Extends Paragraph, adding:

    Props

  • placeholder

    string

    Optional placeholder to show when no value selected.

    • 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.

    Props

  • disableScroll

    boolean

    Removes ability to scroll and all style and functionality related to scrolling.

  • unstyled

    boolean

    Removes all default styles.

    • 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.

    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.

    Props

  • index (required)

    number

    Incrementally starting from 0, matching its appearance in the list.

  • value

    string

    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.

    <Select.Viewport>

      <Select.Indicator transition="quick" />

      <Select.Group>{/* items */}</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.

    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.

    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.

    Props

  • enabled

    boolean

    Default: 

    true

    Whether focus management is enabled.

  • loop

    boolean

    Default: 

    false

    When true, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tabbable.

  • trapped

    boolean

    Default: 

    false

    When true, focus cannot escape the focus scope via keyboard, pointer, or programmatic focus.

  • focusOnIdle

    boolean | number

    Default: 

    false

    When true, waits for idle before focusing. When a number, waits that many ms. This prevents reflows during animations.

  • onMountAutoFocus

    (event: Event) => void

    Event handler called when auto-focusing on mount. Can be prevented.

  • onUnmountAutoFocus

    (event: Event) => void

    Event handler called when auto-focusing on unmount. Can be prevented.

    • 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

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

    

    export default () => (

      <Select defaultValue="">

        <Select.Trigger>

          <Select.Value placeholder="Search..." />

        </Select.Trigger>

    

        <Adapt when="maxMd" platform="touch">

          {/* or <Select.Sheet> */}

          <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>

    )

    Previous

    RadioGroup

    Next

    Slider

    Edit this page on GitHub.