# Native Select

Choose one option with the browser's own select element, styled like the Select trigger.

Request owner native select

[Complete TSX file](/examples/native-select/default.tsx)

```tsx
"use client";

import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@/siteplane/components/field";
import {
  NativeSelect,
  NativeSelectOption,
} from "@/siteplane/components/native-select";

const members = [
  { value: "mara", label: "Mara Ellis" },
  { value: "jon", label: "Jon Okafor" },
  { value: "priya", label: "Priya Shah" },
  { value: "lea", label: "Lea Novak" },
];

export default function Example() {
  return (
    <Field className="w-full max-w-sm">
      <FieldLabel>Owner</FieldLabel>
      <NativeSelect defaultValue="mara">
        {members.map((member) => (
          <NativeSelectOption key={member.value} value={member.value}>
            {member.label}
          </NativeSelectOption>
        ))}
      </NativeSelect>
      <FieldDescription>The person who answers this request.</FieldDescription>
    </Field>
  );
}
```

## Installation

Complete [one-time setup](/docs/installation/) first.

```bash
pnpm dlx shadcn@4.18.0 add @siteplane/native-select
```

With npm: `npx shadcn@4.18.0 add @siteplane/native-select`. [Registry JSON](/registry/native-select.json) lists source files and dependencies.

For this page’s examples, also install:

```bash
pnpm dlx shadcn@4.18.0 add @siteplane/button @siteplane/form @siteplane/input
```

Field is installed with Input.

## Usage

```tsx
import {
  NativeSelect,
  NativeSelectOption,
} from "@/siteplane/components/native-select";

<NativeSelect aria-label="Region" defaultValue="eu">
  <NativeSelectOption value="eu">Europe</NativeSelectOption>
  <NativeSelectOption value="us">United States</NativeSelectOption>
</NativeSelect>;
```

Native Select is the browser's `select` element on the kit's field. The platform opens its list, a picker on a phone, and the chosen value is a form value like that of any other input. The field looks like a [Select](/docs/components/select/) trigger, with the same caret, sizes, hover, invalid and disabled states, so the two stand side by side in a form. While the select has focus, which it keeps while its list is open, the field shows the active edge of every focused field, 1 px in the accent color, or in the error color while it is invalid. It holds a single choice.

## Composition

```text
NativeSelect
├── NativeSelectOption
└── NativeSelectOptGroup → NativeSelectOption
```

## Field

In a [Field](/docs/components/field/), as in the example at the top of this page, the select is the Field's control: FieldLabel names it, FieldDescription and FieldError describe it, and the Field reads its value and its validity. Its description and error take the size of the field, 12 px on an 18 px line beside an `sm` select and 14 px on a 20 px line beside a larger one.

## Option groups

Group related options with `NativeSelectOptGroup` and its `label`. The browser draws the group labels in its list, and they cannot be chosen.

Time zone native select with groups

[Complete TSX file](/examples/native-select/groups.tsx)

```tsx
"use client";

import { Field, FieldLabel } from "@/siteplane/components/field";
import {
  NativeSelect,
  NativeSelectOptGroup,
  NativeSelectOption,
} from "@/siteplane/components/native-select";

const zones = [
  {
    label: "Europe",
    items: [
      { value: "Europe/Berlin", label: "Berlin" },
      { value: "Europe/London", label: "London" },
      { value: "Europe/Madrid", label: "Madrid" },
    ],
  },
  {
    label: "Americas",
    items: [
      { value: "America/New_York", label: "New York" },
      { value: "America/Chicago", label: "Chicago" },
      { value: "America/Los_Angeles", label: "Los Angeles" },
    ],
  },
  {
    label: "Asia Pacific",
    items: [
      { value: "Asia/Singapore", label: "Singapore" },
      { value: "Asia/Tokyo", label: "Tokyo" },
      { value: "Australia/Sydney", label: "Sydney" },
    ],
  },
];

export default function Example() {
  return (
    <Field className="w-full max-w-sm">
      <FieldLabel>Time zone</FieldLabel>
      <NativeSelect defaultValue="Europe/Berlin">
        {zones.map((zone) => (
          <NativeSelectOptGroup key={zone.label} label={zone.label}>
            {zone.items.map((item) => (
              <NativeSelectOption key={item.value} value={item.value}>
                {item.label}
              </NativeSelectOption>
            ))}
          </NativeSelectOptGroup>
        ))}
      </NativeSelect>
    </Field>
  );
}
```

## Sizes

Omit `size` to inherit the provider's control size. Each size sets the field's height, 36, 40, 44 or 48 px, its text, 14 px at `sm` and 16 px from `md`, and the inline padding where the value starts, 12, 12, 14 or 16 px, as on a Select trigger. The caret is 16 px at every size, in the tertiary text color at 80 % like every icon in a field; it ends at that padding, and the value ends 8 px before it. It is the Select's caret but stays still, where a Select's turns while its list is open, since the page cannot see the browser's list. On a touch screen the value is 16 px at every size, as in an [Input](/docs/components/input/#sizes), so the browser does not zoom into the field.

Native select sizes

[Complete TSX file](/examples/native-select/sizes.tsx)

```tsx
"use client";

import { Field, FieldLabel } from "@/siteplane/components/field";
import {
  NativeSelect,
  NativeSelectOption,
} from "@/siteplane/components/native-select";

const roles = [
  { value: "viewer", label: "Viewer" },
  { value: "editor", label: "Editor" },
  { value: "admin", label: "Admin" },
];

const sizes = [
  { size: "sm", label: "small" },
  { size: "md", label: "medium" },
  { size: "lg", label: "large" },
  { size: "xl", label: "extra large" },
] as const;

export default function Example() {
  return (
    <div className="grid w-full max-w-sm gap-4">
      {sizes.map(({ size, label }) => (
        <Field key={size}>
          <FieldLabel>Role, {label}</FieldLabel>
          <NativeSelect defaultValue="editor" size={size}>
            {roles.map((role) => (
              <NativeSelectOption key={role.value} value={role.value}>
                {role.label}
              </NativeSelectOption>
            ))}
          </NativeSelect>
        </Field>
      ))}
    </div>
  );
}
```

## Variants

`default` rests raised, as the Select trigger does. `outline` rests transparent inside the hairline rim of an outline [Button](/docs/components/button/) and takes a light tint on hover and press, as a Select trigger with [`variant="outline"`](/docs/components/select/) does: use it in a filter bar or a toolbar, beside an inset search field. Focus, invalid and disabled stay the same in both.

Native select surface variants

[Complete TSX file](/examples/native-select/variants.tsx)

```tsx
"use client";

import { Field, FieldLabel } from "@/siteplane/components/field";
import {
  NativeSelect,
  NativeSelectOption,
} from "@/siteplane/components/native-select";

const statuses = [
  { value: "all", label: "All statuses" },
  { value: "open", label: "Open" },
  { value: "closed", label: "Closed" },
];

export default function Example() {
  return (
    <div className="grid w-full max-w-sm gap-4">
      {(["default", "outline"] as const).map((variant) => (
        <Field key={variant}>
          <FieldLabel>Status, {variant}</FieldLabel>
          <NativeSelect defaultValue="all" variant={variant}>
            {statuses.map((status) => (
              <NativeSelectOption key={status.value} value={status.value}>
                {status.label}
              </NativeSelectOption>
            ))}
          </NativeSelect>
        </Field>
      ))}
    </div>
  );
}
```

## Disabled and invalid

`disabled` on the select, or on the Field around it, blocks the choice: the field fades by as much as every other field, takes the light gray fill of a disabled field and shows the not-allowed cursor. An invalid Field, or `aria-invalid` on the select, draws the invalid frame of a field; explain the problem with FieldError.

Disabled and invalid native selects

[Complete TSX file](/examples/native-select/states.tsx)

```tsx
"use client";

import { Field, FieldError, FieldLabel } from "@/siteplane/components/field";
import {
  NativeSelect,
  NativeSelectOption,
} from "@/siteplane/components/native-select";

const plans = [
  { value: "starter", label: "Starter" },
  { value: "team", label: "Team" },
  { value: "business", label: "Business" },
];

export default function Example() {
  return (
    <div className="grid w-full max-w-sm gap-4">
      <Field disabled>
        <FieldLabel>Billing plan</FieldLabel>
        <NativeSelect defaultValue="team">
          {plans.map((plan) => (
            <NativeSelectOption key={plan.value} value={plan.value}>
              {plan.label}
            </NativeSelectOption>
          ))}
        </NativeSelect>
      </Field>
      <Field invalid>
        <FieldLabel>Seats</FieldLabel>
        <NativeSelect defaultValue="5">
          <NativeSelectOption value="5">5 seats</NativeSelectOption>
          <NativeSelectOption value="10">10 seats</NativeSelectOption>
          <NativeSelectOption value="25">25 seats</NativeSelectOption>
        </NativeSelect>
        <FieldError match>
          Your workspace has 8 members. Choose at least 10 seats.
        </FieldError>
      </Field>
    </div>
  );
}
```

## Form integration

Set `name` on the select, or on the Field around it, to send the chosen value with a form. For a required choice, start with an option whose value is empty, such as “Choose a region”, and set `required`: inside a [Form](/docs/components/form/), a submit without a choice is blocked, the select takes focus and FieldError shows its message. An uncontrolled select resets with the form; a controlled one needs your own reset handler.

Data region native select in a form

[Complete TSX file](/examples/native-select/form.tsx)

```tsx
"use client";

import { useState } from "react";
import { Button } from "@/siteplane/components/button";
import { Field, FieldError, FieldLabel } from "@/siteplane/components/field";
import { Form } from "@/siteplane/components/form";
import {
  NativeSelect,
  NativeSelectOption,
} from "@/siteplane/components/native-select";

const regions = [
  { value: "eu", label: "Europe (Frankfurt)" },
  { value: "us", label: "United States (Virginia)" },
  { value: "ap", label: "Asia Pacific (Singapore)" },
];

export default function Example() {
  const [saved, setSaved] = useState("");

  return (
    <Form
      className="grid w-full max-w-sm gap-4"
      onReset={() => setSaved("")}
      onSubmit={(event) => {
        event.preventDefault();
        const region = new FormData(event.currentTarget).get("region");
        const label = regions.find((item) => item.value === region)?.label;
        setSaved(label ? `Data is stored in ${label}.` : "");
      }}
    >
      <Field name="region">
        <FieldLabel>Data region</FieldLabel>
        <NativeSelect defaultValue="" required>
          <NativeSelectOption value="">Choose a region</NativeSelectOption>
          {regions.map((region) => (
            <NativeSelectOption key={region.value} value={region.value}>
              {region.label}
            </NativeSelectOption>
          ))}
        </NativeSelect>
        <FieldError match="valueMissing">Choose a data region.</FieldError>
      </Field>
      <div className="flex gap-2">
        <Button type="submit">Save</Button>
        <Button type="reset" variant="outline">
          Reset
        </Button>
      </div>
      <p className="min-h-5 text-muted-foreground text-sm" role="status">
        {saved}
      </p>
    </Form>
  );
}
```

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| NativeSelect.size | sm \| md \| lg \| xl | provider / sm | The control size: 36, 40, 44 or 48 px high, with the text, padding and caret place of a field of that size. |
| NativeSelect.value / defaultValue | string \| number \| readonly string[] | uncontrolled | The value of the chosen option, controlled or initial. |
| NativeSelect.onChange | ChangeEventHandler<HTMLSelectElement> | unset | Called when a person chooses an option; read the value from event.currentTarget.value. |
| NativeSelect.name | string | unset | The name of the value in the form data. A Field's name comes first. |
| NativeSelect.disabled | boolean | false | Blocks the choice and fades the field. A disabled Field disables the select. |
| NativeSelect.required | boolean | false | Asks for a choice: an empty value is invalid. |
| NativeSelect.variant | default \| outline | default | The surface: default rests raised, as the Select trigger does; outline rests transparent inside the hairline rim of an outline Button, for a filter bar or a toolbar. |
| NativeSelect.width | full \| fit | full | full fills the container, like Input; fit is as wide as the value and the caret, at the width the browser gives the select, that of its widest option. |
| NativeSelect.className / style | string / CSSProperties | unset | Style the wrapper that draws the field, not the select element: a margin or a width moves the whole field. |
| NativeSelect.ref | Ref<HTMLSelectElement> | unset | The select element. |
| NativeSelectOption | option props | — | An option of the select: the native option element, with value, disabled and children. |
| NativeSelectOptGroup.label | string | unset | The name of a group of options, the native optgroup element. Give every group one. |
`NativeSelectProps` extends the props of a `select` element, except its native
`size`, which the control size replaces. `className` and `style` style the
field, as on every field; the other props, such as `id`, `form`, `autoComplete`
and the `aria-*` attributes, reach the select element, and `hidden` hides the
whole field. The select renders inside a `span` that draws the field and holds
the caret: it carries `data-slot="native-select-wrapper"`, `data-size`,
`data-variant` and `data-width`, and the select `data-slot="native-select"`. In
a Field the select also carries the Field's state attributes, such as
`data-invalid` and `data-disabled`. `NativeSelectOption` and
`NativeSelectOptGroup` accept the props of `option` and `optgroup`. The type
`NativeSelectProps` is exported.

[Read the installed source](/source/native-select).

## Usage notes

Use Native Select where the platform's own list serves people best: on a phone, where it opens the system picker, in a long form of plain choices, or where the page should work before its scripts run. Its options are plain text. For options with icons, avatars or descriptions, a list in the kit's own popup, or several choices, use [Select](/docs/components/select/); for a list that people search in, use [Combobox](/docs/components/combobox/).

Native Select stands on its own, as a field of a form. It does not go inside another component: a select in a segment of an [Input Group](/docs/components/input-group/#with-a-select), such as a country code before a phone number or a currency after an amount, is a Select with `variant="segment"` on its trigger.

The list is the browser's: its look, its position and its keyboard behavior are the platform's, and they differ between browsers and systems. Where a browser draws the options with the colors of the select, they take the system's background and text colors, so they stay legible on a dark page.

The field has no placeholder of its own: a first option with an empty value stands in for one. It is a single select. A `multiple` select is a list box, which the field does not lay out; use Select with `multiple` instead. A floating label is not available: keep the label above the field. Always name the select with a visible label or an `aria-label`.
