Skip to content
Browse documentation
whisk/ui

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.

Coming from another library?
Use 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.

Choose the region for billing.
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.

Workspaces use https://<name>.smoothie.dev.
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

PropTypeDefaultDescription
optionsreadonly SelectOption[]noneProvide unique, nonempty values in display order. Each option has a label and can be disabled, grouped, described, or given decorative start and suffix content.
valuestringnoneControl the committed value. Pass value with onValueChange, never with defaultValue.
defaultValuestringnoneSeed an uncontrolled selection. An unknown value displays the placeholder rather than selecting the first option.
onValueChange(value: string) => voidnoneReceive an enabled option only when the user commits it. Moving the highlight, pressing Escape, or leaving the list does not change the value.
placeholderstringSelect an optionSet the empty prompt shown before a value is selected.
namestringnoneName the hidden native select for form submission.
formstringnoneAssociate the hidden native select with a form outside its ancestor tree.
requiredbooleanfalseRequire a committed value through the hidden native select's browser validation.
searchablebooleanfalseAdd a local filter inside the opened list. Use Combobox when the control itself should be an editable search field.
searchPlaceholderstringSearchName the local filter control when searchable is enabled.
emptyStateMessagestringnoneExplain an empty option collection before a search begins.
noResultsMessagestringNo options match your search. Try another term.Explain when a local search has no matching options.
sizesm | md | lgmdSet the trigger and default option density.
variantfilled | outline | flushed | ghostfilledChoose the trigger's background and border treatment.
optionSizesm | md | lgsizeOverride the list option density independently of the trigger.
disabledbooleanfalseBlock interaction while preserving the selected value.
readOnlybooleanfalseKeep the current value visible but prevent the list from opening.
invalidbooleanfalseExpose invalid state. Pair it with a visible Field error.
prefixReactNodenoneAdd fixed decorative content before the selected value.
suffixReactNodenoneAdd fixed decorative content after the selected value.
startElementReactNodenoneAdd fixed decorative leading trigger content, independent of the selected option.
endElementReactNodenoneAdd fixed decorative trailing trigger content. Do not put buttons or links in adornments.
showSelectedIconbooleanfalseShow the selected option's leading content when no explicit trigger startElement is supplied.
placementtop | bottombottomChoose where the flyout opens relative to the trigger.
positioningSelectPositioningnoneDeprecated: use placement. This compatibility alias takes precedence when both are supplied.
footerActionSelectFooterActionnoneAdd one host-owned action after the options.

Shared props

PropSupportedNotes
as / asChildNoSelect owns its trigger, hidden native select, and listbox structure.
Style propsNoSelect exposes semantic form and appearance props instead of the shared style-prop surface. See Style props.
className / styleYesApplied to the visible button trigger.
refYesForwards to the visible button trigger.
Native HTML attributesYesNative button attributes are forwarded to the trigger, except Select-owned selection and ARIA attributes.

SelectOption fields

PropTypeDefaultDescription
valuestringnoneUnique, nonempty submitted value.
labelstringnoneVisible and announced option name.
disabledbooleanfalseKeep an unavailable option visible but prevent selection.
groupstringnoneName a meaningful option group.
descriptionstringnoneAdd supporting option detail.
startElementReactNodenoneDecorative leading content; never an interactive control.
suffixReactNodenoneDecorative trailing content; include essential meaning in label or description.

SelectFooterAction fields

PropTypeDefaultDescription
labelstringnoneVisible name for the host-owned action.
onClick() => voidnoneHandle the action outside the option selection.
positionscroll | stickyscrollKeep the action after scrolling options or pinned below them.
disabledbooleanfalsePrevent the action while it is unavailable.
startElementReactNodenoneAdd decorative, noninteractive leading action content.
suffixReactNodenoneAdd decorative, noninteractive trailing action content.

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.