Siteplane UI

Native Select

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

Markdown

The person who answers this request.

"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

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

Complete the one-time setup first. Registry JSON lists source files and dependencies.

For this page’s examples, also install:

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

Field is installed with Input.

Usage

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

NativeSelect
├── NativeSelectOption
└── NativeSelectOptGroup → NativeSelectOption

Field

In a 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.

"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, so the browser does not zoom into the field.

"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 and takes a light tint on hover and press, as a Select trigger with variant="outline" does: use it in a filter bar or a toolbar, beside an inset search field. Focus, invalid and disabled stay the same in both.

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

Your workspace has 8 members. Choose at least 10 seats.
"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, 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.

"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

Component properties
PropTypeDefaultDescription
NativeSelect.sizesm | md | lg | xlprovider / smThe control size: 36, 40, 44 or 48 px high, with the text, padding and caret place of a field of that size.
NativeSelect.value / defaultValuestring | number | readonly string[]uncontrolledThe value of the chosen option, controlled or initial.
NativeSelect.onChangeChangeEventHandler<HTMLSelectElement>unsetCalled when a person chooses an option; read the value from event.currentTarget.value.
NativeSelect.namestringunsetThe name of the value in the form data. A Field's name comes first.
NativeSelect.disabledbooleanfalseBlocks the choice and fades the field. A disabled Field disables the select.
NativeSelect.requiredbooleanfalseAsks for a choice: an empty value is invalid.
NativeSelect.variantdefault | outlinedefaultThe 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.widthfull | fitfullfull 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 / stylestring / CSSPropertiesunsetStyle the wrapper that draws the field, not the select element: a margin or a width moves the whole field.
NativeSelect.refRef<HTMLSelectElement>unsetThe select element.
NativeSelectOptionoption props—An option of the select: the native option element, with value, disabled and children.
NativeSelectOptGroup.labelstringunsetThe 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.

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; for a list that people search in, use 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, 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.