gui/apps/gui.hanzo.ai/data/docs/components/select/1.40.0.mdx

---
title: Select
description: Show a menu of items that users can select from.
name: select
component: Select
package: select
demoName: Select
---

<HeroContainer>
  <SelectDemo />
</HeroContainer>

```tsx hero template=Select

```

<Highlights
  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 `hanzogui`, or you can install it independently:

```bash
npm install @hanzogui/select
```

## Anatomy

```tsx
import { Select } from '@hanzo/gui' // or '@hanzogui/select'

export default () => (
  <Select defaultValue="">
    <Select.Trigger>
      <Select.Value placeholder="Search..." />
    </Select.Trigger>
    <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>
)
```

<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

### Select

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.`,
    },
  ]}
/>

### Select.Trigger

Extends [ListItem](/docs/components/list-item) to give sizing, icons, and more.

#### Select.Value

Extends [Paragraph](/docs/components/text), adding:

<PropsTable
  data={[
    {
      name: 'placeholder',
      type: 'string',
      description: `Optional placeholder to show when no value selected`,
    },
  ]}
/>

#### SelectContent

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](/docs/components/stacks).

### Select.ScrollDownButton

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

Extends [YStack](/docs/components/stacks).

### Select.Viewport

Extends [ThemeableStack](/docs/components/stacks#themeablestack). Contains scrollable content items as children.

<PropsTable
  data={[
    {
      name: 'disableScroll',
      type: 'boolean',
      description: `Removes ability to scroll and all style and functionality related to scrolling`,
    },
    {
      name: 'unstyled',
      type: 'boolean',
      description: `Removes all default styles`,
    },
  ]}
/>

<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](/docs/components/stacks). Use only when grouping together items, alongside a Label as the first child.

### Select.Label

Extends [ListItem](/docs/components/list-item). Used to label Groups.

### Select.Item

Extends [ListItem](/docs/components/list-item). Used to add selectable values ot 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](/docs/components/text). Used inside Item to provide unselectable text that will show above once selected in the parent Select.

### 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 Gui wants to present the right abstractions for each platform.

See [Sheet](/docs/components/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 '@hanzo/gui' // or '@hanzogui/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>
)
```