# NativeSelect

A native select styled as a field, which opens the browser's own picker.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/NativeSelect.tsx)

Figma: [Native select](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=3059-449)

## Overview

A native select is a 48px field with a chevron at its end. It renders a native `<select>`, so the browser draws the options in the platform picker, such as the wheel on a phone.

## Examples

### Basic

```tsx
import { Field, NativeSelect, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Environment</Field.Label>
      <NativeSelect defaultValue="">
        <option disabled value="">
          Select environment
        </option>
        <option value="production">Production</option>
        <option value="staging">Staging</option>
        <option value="development">Development</option>
      </NativeSelect>
      <Field.Description>Keys only work in the environment they belong to</Field.Description>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '20rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/NativeSelect/Basic.tsx)

### Invalid

Set `invalid` on `Field.Root`, or on the select itself, to fill it red with a 1px red border. Explain the problem in a `Field.Error`.

```tsx
import { Field, NativeSelect, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Field.Root invalid {...styles.field()}>
      <Field.Label>Environment</Field.Label>
      <NativeSelect defaultValue="">
        <option disabled value="">
          Select environment
        </option>
        <option value="production">Production</option>
        <option value="staging">Staging</option>
      </NativeSelect>
      <Field.Error match>Select an environment for this key.</Field.Error>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '20rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/NativeSelect/Invalid.tsx)

### Disabled

Set `disabled` on `Field.Root` to disable the select and fade its chevron.

```tsx
import { Field, NativeSelect, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Field.Root disabled {...styles.field()}>
      <Field.Label>Environment</Field.Label>
      <NativeSelect defaultValue="production">
        <option value="production">Production</option>
        <option value="staging">Staging</option>
      </NativeSelect>
      <Field.Description>Keys keep the environment they were created in</Field.Description>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '20rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/NativeSelect/Disabled.tsx)

## Anatomy

Import the component and nest native options in it.

```tsx
import { NativeSelect } from '@tempoxyz/ds'

<NativeSelect>
  <option />
</NativeSelect>
```

## Guidelines

### When to Use

* Choose one value from a short list in a form, such as an environment, a network, or a country.
* Use the platform picker on touch devices, where it fits the screen and the keyboard.

### When Not to Use

* Use [Select](/docs/components/select) when the options need icons, logos, or a styled popup.
* Use [ChoiceGroup](/docs/components/choice-group) or [RadioGroup](/docs/components/radio-group) when a few options fit on screen.
* Use [Combobox](/docs/components/combobox) when the list is long enough to need search.

### Lead With a Placeholder Option

Start with a disabled, empty `option` that names the choice, and set `defaultValue=""` so it shows until a value is picked. A disabled placeholder cannot be picked again.

**Do:** Name the choice in the placeholder option.

```tsx
<Field.Root style={{ width: 240 }}>
  <Field.Label>Environment</Field.Label>
  <NativeSelect defaultValue="">
    <option disabled value="">
      Select environment
    </option>
    <option value="production">Production</option>
  </NativeSelect>
</Field.Root>
```

**Don't:** Start with an empty option that people can pick as a value.

```tsx
<Field.Root style={{ width: 240 }}>
  <Field.Label>Environment</Field.Label>
  <NativeSelect defaultValue="">
    <option value="">--</option>
    <option value="production">Production</option>
  </NativeSelect>
</Field.Root>
```

### Keep the Label Visible

Give the select a `Field.Label`. The placeholder option disappears once a value is picked, so it cannot name the field.

## Content

* Name the choice in the placeholder, such as Select environment.
* Write option labels in sentence case, and keep each to a few words.
* Order options by frequency of use, or alphabetically when no order applies.

## Accessibility

`NativeSelect` renders a native `<select>` registered as the control of its `Field.Root`. The browser handles the keys and the picker.

### Semantics

* **Select (combobox):** A native select, announced with its label and its selected option.
* **Invalid State (aria-invalid):** Marks the select invalid and fills it red. Explain the problem in an error.

### Keyboard

* **Move Focus In and Out (Tab):** Moves focus to the select, and out of it again, as for any field.
* **Open the Picker (Space or Alt+Down Arrow):** Opens the platform picker. Other keys follow the native select.

### Your Responsibilities

* **Label the Select (Field.Label):** Give it a visible label in a field, or set `aria-label` when none fits.
* **Explain Errors (Field.Error):** Say how to fix an invalid value in a `Field.Error`, not in red alone.

## Related

[Select](/docs/components/select)

Use for options with icons or a styled popup.

[Field](/docs/components/field)

Use for labels, descriptions, and errors.

[RadioGroup](/docs/components/radio-group)

Use for a few options shown at once.

[Forms](/docs/patterns/forms)

Covers laying out fields and actions.
