Select
Choose one option from a labelled list.
Overview
Select lets a user commit one value from an application-owned list. It presents a keyboard-accessible button and listbox while a hidden native select carries the value for forms and browser validation.
options, not children or SelectItem. Use onValueChange, not onChange; Select has no multiple selection.Use when
The user chooses one item from a short, stable list.
Use instead
Use Combobox when users need to search a larger list, or RadioGroup when every option should remain visible.
Usage
import { Field, Select } from "@smoothie-framework/whisk-react";
<Field label="Deployment region" required>
<Select
name="region"
placeholder="Choose a region"
options={[
{ value: "eu-west", label: "Europe West" },
{ value: "us-east", label: "US East" },
]}
/>
</Field>Examples
Variants
Choose the trigger treatment that fits the surrounding form surface.
import { Field, FieldGroup, Select } from "@smoothie-framework/whisk-react";
<FieldGroup>
<Field label="Filled">
<Select variant="filled" defaultValue="eu-west" options={[{ value: "eu-west", label: "Europe West" }]} />
</Field>
<Field label="Outline">
<Select variant="outline" defaultValue="eu-west" options={[{ value: "eu-west", label: "Europe West" }]} />
</Field>
<Field label="Flushed">
<Select variant="flushed" defaultValue="eu-west" options={[{ value: "eu-west", label: "Europe West" }]} />
</Field>
<Field label="Ghost">
<Select variant="ghost" defaultValue="eu-west" options={[{ value: "eu-west", label: "Europe West" }]} />
</Field>
</FieldGroup>Sizes
Choose the trigger size that matches the surrounding form density.
import { Field, FieldGroup, Select } from "@smoothie-framework/whisk-react";
<FieldGroup>
<Field label="Small">
<Select size="sm" defaultValue="eu-west" options={[{ value: "eu-west", label: "Europe West" }]} />
</Field>
<Field label="Medium">
<Select size="md" defaultValue="eu-west" options={[{ value: "eu-west", label: "Europe West" }]} />
</Field>
<Field label="Large">
<Select size="lg" defaultValue="eu-west" options={[{ value: "eu-west", label: "Europe West" }]} />
</Field>
</FieldGroup>Groups
Use groups when their names help someone scan a longer list. A disabled option explains what is unavailable without letting it be selected.
import { Field, Select } from "@smoothie-framework/whisk-react";
<Field label="Deployment region">
<Select
defaultValue="eu-west"
options={[
{ value: "eu-west", label: "Europe West", group: "Europe" },
{ value: "eu-central", label: "Europe Central", group: "Europe" },
{ value: "us-east", label: "US East", group: "North America" },
{
value: "us-west",
label: "US West",
group: "North America",
disabled: true,
description: "Not available for this workspace.",
},
]}
/>
</Field>Forms
Use react-hook-form with Controller because Select commits a string through value and onValueChange.
import { Controller, useForm } from "react-hook-form";
import { Box, Button, Field, Select, Stack } from "@smoothie-framework/whisk-react";
type RegionValues = { region: string };
function onSubmit(values: RegionValues) {
// Send values to your application.
}
export function RegionForm() {
const { control, handleSubmit } = useForm<RegionValues>({
defaultValues: { region: "" },
});
return (
<Box as="form" noValidate onSubmit={handleSubmit(onSubmit)}>
<Stack gap={3}>
<Controller
name="region"
control={control}
rules={{ required: "Choose a deployment region." }}
render={({ field, fieldState }) => (
<Field label="Deployment region" required error={fieldState.error?.message}>
<Select
value={field.value}
onValueChange={field.onChange}
options={[
{ value: "eu-west", label: "Europe West" },
{ value: "us-east", label: "US East" },
]}
/>
</Field>
)}
/>
<Button type="submit">Save</Button>
</Stack>
</Box>
);
}Controlled
Use value and onValueChange when application state owns the committed selection.
import { useState } from "react";
import { Field, Select } from "@smoothie-framework/whisk-react";
export function RegionSelect() {
const [region, setRegion] = useState("staging");
return (
<Field label="Deployment region">
<Select
value={region}
onValueChange={setRegion}
options={[
{ value: "production", label: "Production" },
{ value: "staging", label: "Staging" },
{ value: "preview", label: "Preview" },
]}
/>
</Field>
);
}Read-only
Use readOnly when the current choice must remain visible but unavailable for editing.
import { Field, Select } from "@smoothie-framework/whisk-react";
<Field label="Deployment region">
<Select
readOnly
defaultValue="production"
options={[{ value: "production", label: "Production" }]}
/>
</Field>Option icons
Use showSelectedIcon to carry an option's decorative leading icon into the trigger when no explicit startElement is supplied.
import { CloudIcon, BranchIcon, SparksIcon } from "@smoothie-framework/whisk-react/icons";
import { Field, Select } from "@smoothie-framework/whisk-react";
<Field label="Environment">
<Select
showSelectedIcon
defaultValue="production"
options={[
{ value: "production", label: "Production", startElement: <CloudIcon size="md" /> },
{ value: "staging", label: "Staging", startElement: <BranchIcon size="md" /> },
{ value: "preview", label: "Preview", startElement: <SparksIcon size="md" /> },
]}
/>
</Field>Disabled
Use disabled when the choice is unavailable. The selected value stays visible but cannot be changed.
import { Field, Select } from "@smoothie-framework/whisk-react";
<Field disabled label="Deployment region">
<Select
defaultValue="eu-west"
options={[{ value: "eu-west", label: "Europe West" }]}
/>
</Field>Invalid
Let Field expose invalid state and a specific error after application validation finds a problem.
import { Field, Select } from "@smoothie-framework/whisk-react";
<Field label="Billing region" error="Choose the region for billing.">
<Select
required
placeholder="Choose a region"
options={[
{ value: "eu", label: "Europe" },
{ value: "us", label: "United States" },
]}
/>
</Field>Option icons and suffixes
Option icons and suffixes stay aligned across sizes, whether they appear in the Flyout, trigger, or both. Small Selects use sm icons; medium and large Selects use md icons.
Plain
Option icons
Trigger and option icons
Trigger icon
import { BranchIcon, CloudIcon, SparksIcon } from "@smoothie-framework/whisk-react/icons";
import { Grid, Select, Text } from "@smoothie-framework/whisk-react";
const selectSizes = ["sm", "md", "lg"] as const;
const iconSizeForSelect = (size: (typeof selectSizes)[number]) =>
size === "sm" ? "sm" : "md";
const selectSizeName = (size: (typeof selectSizes)[number]) =>
size === "sm" ? "Small" : size === "md" ? "Medium" : "Large";
const environmentOptions = [
{ value: "production", label: "Production", suffix: "3 regions" },
{ value: "staging", label: "Staging", suffix: "2 regions" },
{ value: "preview", label: "Preview", suffix: "1 region" },
];
const environmentOptionsWithIcons = (size: (typeof selectSizes)[number]) =>
environmentOptions.map((option) => ({
...option,
startElement: option.value === "production"
? <CloudIcon size={iconSizeForSelect(size)} />
: option.value === "staging"
? <BranchIcon size={iconSizeForSelect(size)} />
: <SparksIcon size={iconSizeForSelect(size)} />,
}));
<Grid columns={4} gap={2}>
<Text textStyle="caption">Plain</Text>
<Text textStyle="caption">Option icons</Text>
<Text textStyle="caption">Trigger and option icons</Text>
<Text textStyle="caption">Trigger icon</Text>
{selectSizes.flatMap((size) => [
<Select key={`${size}-plain`} aria-label={`${selectSizeName(size)} environment, plain`} size={size} defaultValue="production" options={environmentOptions} />,
<Select key={`${size}-option-icons`} aria-label={`${selectSizeName(size)} environment, option icons`} size={size} defaultValue="production" options={environmentOptionsWithIcons(size)} />,
<Select
key={`${size}-both-icons`}
aria-label={`${selectSizeName(size)} environment, trigger and option icons`}
size={size}
startElement={<CloudIcon size={iconSizeForSelect(size)} />}
defaultValue="production"
options={environmentOptionsWithIcons(size)}
/>,
<Select
key={`${size}-trigger-icon`}
aria-label={`${selectSizeName(size)} environment, trigger icon`}
size={size}
startElement={<CloudIcon size={iconSizeForSelect(size)} />}
defaultValue="production"
options={environmentOptions}
/>,
])}
</Grid>Positioning
Use placement in new code. positioning is a compatibility alias and takes precedence only when both are present.
import { Field, Select } from "@smoothie-framework/whisk-react";
<Field label="Deployment region">
<Select
placement="top"
defaultValue="eu-west"
options={[
{ value: "eu-west", label: "Europe West" },
{ value: "us-east", label: "US East" },
]}
/>
</Field>Prefix and suffix
Use fixed trigger context only when it remains true for every selectable value. Prefixes and suffixes are visual-only, so screen readers announce the Field label and selected option label, not these adornments.
import { Field, Select } from "@smoothie-framework/whisk-react";
<Field label="Workspace URL" description="Workspaces use https://<name>.smoothie.dev.">
<Select
prefix="https://"
suffix=".smoothie.dev"
defaultValue="atlas"
options={[
{ value: "atlas", label: "atlas" },
{ value: "orbit", label: "orbit" },
]}
/>
</Field>Footer action
Use a footer action for one related task outside the option list. It is not an option and arrow keys do not reach it.
import { Field, FieldGroup, Select } from "@smoothie-framework/whisk-react";
function createRegion() {
// Open the application flow for a new region.
}
<FieldGroup>
<Field label="Sticky footer">
<Select
placeholder="Choose a deployment region"
options={[
{ value: "eu-west", label: "Europe West" },
{ value: "us-east", label: "US East" },
]}
footerAction={{ label: "Create region", position: "sticky", onClick: createRegion }}
/>
</Field>
<Field label="Scroll footer">
<Select
placeholder="Choose a deployment region"
options={[
{ value: "eu-west", label: "Europe West" },
{ value: "us-east", label: "US East" },
]}
footerAction={{ label: "Create region", position: "scroll", onClick: createRegion }}
/>
</Field>
</FieldGroup>Search
searchable adds a filter after the Select opens. It still commits one existing option. Use Combobox when entering search text is the main way people find a choice.
import { Field, Select } from "@smoothie-framework/whisk-react";
<Field label="Repository">
<Select
searchable
placeholder="Choose a repository"
searchPlaceholder="Find a repository"
noResultsMessage="No repositories match."
options={[
{ value: "framework", label: "Framework" },
{ value: "website", label: "Website" },
{ value: "studio", label: "Studio" },
]}
/>
</Field>Props
Component props
Shared props
SelectOption fields
SelectFooterAction fields
Accessibility
Give Select a visible Field label or an accessible name. Keep option labels distinct, mark unavailable choices disabled, and use groups only for meaningful categories. The trigger manages focus: Arrow keys, Home, End, and typing move the temporary highlight; Enter or Space commits it; Escape and Tab dismiss without changing the selection. Do not make option adornments interactive.
Content guidance
Use a label that names the decision, then keep option labels short, distinct, and parallel. Avoid an option called Select one when a useful placeholder can do that job.