Native Select
Choose one option with the browser's own select element, styled like the Select trigger.
The person who answers this request.
Installation
pnpm dlx shadcn@4.18.0 add @siteplane/native-selectComplete 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/inputField 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 → NativeSelectOptionField
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.
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.
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.
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.
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.
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
Native | 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. |
Native | string | number | readonly string[] | uncontrolled | The value of the chosen option, controlled or initial. |
Native | ChangeEventHandler<HTMLSelectElement> | unset | Called when a person chooses an option; read the value from event.currentTarget.value. |
Native | string | unset | The name of the value in the form data. A Field's name comes first. |
Native | boolean | false | Blocks the choice and fades the field. A disabled Field disables the select. |
Native | boolean | false | Asks for a choice: an empty value is invalid. |
Native | 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. |
Native | 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. |
Native | string / CSSProperties | unset | Style the wrapper that draws the field, not the select element: a margin or a width moves the whole field. |
Native | Ref<HTMLSelectElement> | unset | The select element. |
Native | option props | — | An option of the select: the native option element, with value, disabled and children. |
Native | 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.
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.