Select

Choose one option from a short, fixed list.

Default

Pass items so the trigger shows the selected label instead of the raw value.

Voice

import {
  Field,
  FieldLabel,
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@smallest-inc/ui";

const voices = [
  { value: "aria", label: "Aria" },
  { value: "kai", label: "Kai" },
  { value: "meera", label: "Meera" },
  { value: "rohan", label: "Rohan" },
  { value: "sofia", label: "Sofia" },
];

export default function SelectDefault() {
  return (
    <Field className="w-full max-w-xs">
      <FieldLabel>Voice</FieldLabel>
      <Select items={voices}>
        <SelectTrigger>
          <SelectValue placeholder="Select a voice" />
        </SelectTrigger>
        <SelectContent>
          {voices.map((voice) => (
            <SelectItem key={voice.value} value={voice.value}>
              {voice.label}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
    </Field>
  );
}

Sizes

The default size is sm (36px). md is 40px, for roomier forms.

import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@smallest-inc/ui";

const voices = [
  { value: "aria", label: "Aria" },
  { value: "kai", label: "Kai" },
  { value: "meera", label: "Meera" },
];

export default function SelectSizes() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-4">
      {(["sm", "md"] as const).map((size) => (
        <Select key={size} items={voices} defaultValue="aria">
          <SelectTrigger size={size} aria-label="Voice">
            <SelectValue />
          </SelectTrigger>
          <SelectContent>
            {voices.map((voice) => (
              <SelectItem key={voice.value} value={voice.value}>
                {voice.label}
              </SelectItem>
            ))}
          </SelectContent>
        </Select>
      ))}
    </div>
  );
}

Variants

Primary is a flat neutral-100 field and is the default everywhere. Secondary is white with shadow-sm, for tinted panels.

import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@smallest-inc/ui";

const languages = [
  { value: "en", label: "English" },
  { value: "hi", label: "Hindi" },
  { value: "es", label: "Spanish" },
];

export default function SelectVariants() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-4">
      {(["primary", "secondary"] as const).map((variant) => (
        <Select key={variant} items={languages}>
          <SelectTrigger variant={variant} aria-label="Language">
            <SelectValue placeholder="Select a language" />
          </SelectTrigger>
          <SelectContent>
            {languages.map((language) => (
              <SelectItem key={language.value} value={language.value}>
                {language.label}
              </SelectItem>
            ))}
          </SelectContent>
        </Select>
      ))}
    </div>
  );
}

Groups

Group options under a SelectLabel and divide groups with SelectSeparator.

Model

import {
  Field,
  FieldLabel,
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectLabel,
  SelectSeparator,
  SelectTrigger,
  SelectValue,
} from "@smallest-inc/ui";

const providers = [
  {
    label: "OpenAI",
    models: [
      { value: "gpt-4.1", label: "GPT-4.1" },
      { value: "gpt-4.1-mini", label: "GPT-4.1 mini" },
    ],
  },
  {
    label: "Anthropic",
    models: [
      { value: "claude-sonnet", label: "Claude Sonnet" },
      { value: "claude-haiku", label: "Claude Haiku" },
    ],
  },
  {
    label: "Google",
    models: [{ value: "gemini-2.5-flash", label: "Gemini 2.5 Flash" }],
  },
];

const models = providers.flatMap((provider) => provider.models);

export default function SelectGroups() {
  return (
    <Field className="w-full max-w-xs">
      <FieldLabel>Model</FieldLabel>
      <Select items={models} defaultValue="gpt-4.1">
        <SelectTrigger>
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          {providers.map((provider, index) => (
            <SelectGroup key={provider.label}>
              {index > 0 ? <SelectSeparator /> : null}
              <SelectLabel>{provider.label}</SelectLabel>
              {provider.models.map((model) => (
                <SelectItem key={model.value} value={model.value}>
                  {model.label}
                </SelectItem>
              ))}
            </SelectGroup>
          ))}
        </SelectContent>
      </Select>
    </Field>
  );
}

Descriptions

Pass description for a supporting line under each option. The selected row shows a trailing check.

Run as

import {
  Field,
  FieldLabel,
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@smallest-inc/ui";

const identities = [
  {
    value: "workspace",
    label: "Workspace",
    description: "Always run actions as the Smallest workspace.",
  },
  {
    value: "member",
    label: "Member",
    description: "Run as the signed-in member when connected; otherwise as the workspace.",
  },
  {
    value: "member-only",
    label: "Member only",
    description: "Run as the signed-in member only; fail if their account isn’t connected.",
  },
];

export default function SelectDescriptions() {
  return (
    <Field className="w-full max-w-xs">
      <FieldLabel>Run as</FieldLabel>
      <Select items={identities} defaultValue="workspace">
        <SelectTrigger>
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          {identities.map((identity) => (
            <SelectItem key={identity.value} value={identity.value} description={identity.description}>
              {identity.label}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
    </Field>
  );
}

Prefix and suffix

leading places a Central Icon before the label; trailing places a count or badge before the check.

Channel

import {
  BrowserIcon,
  Field,
  FieldLabel,
  Icon,
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@smallest-inc/ui";

const channels = [
  { value: "phone", label: "Phone", icon: <Icon name="IconTelephone" />, agents: 12 },
  { value: "web", label: "Web widget", icon: <BrowserIcon />, agents: 4 },
  { value: "chat", label: "Chat", icon: <Icon name="IconBubbleText" />, agents: 7 },
  { value: "api", label: "API", icon: <Icon name="IconCode" />, agents: 2 },
];

export default function SelectPrefixSuffix() {
  return (
    <Field className="w-full max-w-xs">
      <FieldLabel>Channel</FieldLabel>
      <Select items={channels} defaultValue="phone">
        <SelectTrigger>
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          {channels.map((channel) => (
            <SelectItem
              key={channel.value}
              value={channel.value}
              leading={channel.icon}
              trailing={<span className="text-fg-tertiary tabular-nums">{channel.agents}</span>}
            >
              {channel.label}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
    </Field>
  );
}

Fit content

Set fitContent on the trigger to size it to its label, for filters in a toolbar.

import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@smallest-inc/ui";

const statuses = [
  { value: "all", label: "All calls" },
  { value: "completed", label: "Completed" },
  { value: "transferred", label: "Transferred" },
  { value: "failed", label: "Failed" },
];

const agents = [
  { value: "all", label: "All agents" },
  { value: "support", label: "Support line" },
  { value: "booking", label: "Appointment booking" },
];

export default function SelectFitContent() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Select items={statuses} defaultValue="all">
        <SelectTrigger fitContent aria-label="Call status">
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          {statuses.map((status) => (
            <SelectItem key={status.value} value={status.value}>
              {status.label}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
      <Select items={agents} defaultValue="all">
        <SelectTrigger fitContent aria-label="Agent">
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          {agents.map((agent) => (
            <SelectItem key={agent.value} value={agent.value}>
              {agent.label}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
    </div>
  );
}

Long list

Cap the height with a max-h class on SelectContent; the list scrolls with a fade. Use Combobox once people need to search.

Calling hours time zone

import {
  Field,
  FieldLabel,
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@smallest-inc/ui";

const timeZones = [
  "Pacific/Honolulu",
  "America/Anchorage",
  "America/Los_Angeles",
  "America/Denver",
  "America/Chicago",
  "America/New_York",
  "America/Sao_Paulo",
  "Europe/London",
  "Europe/Berlin",
  "Europe/Istanbul",
  "Africa/Nairobi",
  "Asia/Dubai",
  "Asia/Karachi",
  "Asia/Kolkata",
  "Asia/Dhaka",
  "Asia/Bangkok",
  "Asia/Singapore",
  "Asia/Tokyo",
  "Australia/Sydney",
  "Pacific/Auckland",
].map((zone) => ({ value: zone, label: zone.replace("_", " ") }));

export default function SelectLongList() {
  return (
    <Field className="w-full max-w-xs">
      <FieldLabel>Calling hours time zone</FieldLabel>
      <Select items={timeZones} defaultValue="Asia/Kolkata">
        <SelectTrigger>
          <SelectValue />
        </SelectTrigger>
        <SelectContent className="max-h-64">
          {timeZones.map((zone) => (
            <SelectItem key={zone.value} value={zone.value}>
              {zone.label}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
    </Field>
  );
}

Disabled

Disable the whole Select, or a single SelectItem that is unavailable.

import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@smallest-inc/ui";

const plans = [
  { value: "starter", label: "Starter" },
  { value: "growth", label: "Growth" },
  { value: "enterprise", label: "Enterprise" },
];

export default function SelectDisabled() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-4">
      <Select items={plans} defaultValue="starter" disabled>
        <SelectTrigger aria-label="Plan">
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          {plans.map((plan) => (
            <SelectItem key={plan.value} value={plan.value}>
              {plan.label}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
      <Select items={plans} defaultValue="starter">
        <SelectTrigger aria-label="Plan">
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          {plans.map((plan) => (
            <SelectItem key={plan.value} value={plan.value} disabled={plan.value === "enterprise"}>
              {plan.label}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
    </div>
  );
}

Error

Set aria-invalid on the trigger for a danger ring, and explain the fix with FieldError.

Outbound number

Choose a number before you start the campaign.

import {
  Field,
  FieldError,
  FieldLabel,
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@smallest-inc/ui";

const numbers = [
  { value: "+14155550123", label: "+1 415 555 0123" },
  { value: "+442079460958", label: "+44 20 7946 0958" },
  { value: "+918045678901", label: "+91 80 4567 8901" },
];

export default function SelectError() {
  return (
    <Field invalid className="w-full max-w-xs">
      <FieldLabel>Outbound number</FieldLabel>
      <Select items={numbers}>
        <SelectTrigger aria-invalid>
          <SelectValue placeholder="Select a phone number" />
        </SelectTrigger>
        <SelectContent>
          {numbers.map((number) => (
            <SelectItem key={number.value} value={number.value}>
              {number.label}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
      <FieldError match>Choose a number before you start the campaign.</FieldError>
    </Field>
  );
}

Best practices

When to use

Use for one value from a short, known list (roughly 3–15 options), such as a voice, plan, or model.
Use Combobox when people need to type to find an option, Radio when comparing a few options side by side matters, and Multi Select for more than one value.

Behavior

Pass items ({ value, label }) to Select so the trigger shows the label, not the raw value.
Group related options with SelectGroup and SelectLabel, and divide groups with SelectSeparator.
Use description only when options need explaining, like “Run as: Member only”; the selected row then shows a trailing check.
Set fitContent on SelectTrigger for toolbar filters; form fields stay full width.
Cap long lists with a max-h class on SelectContent; the list scrolls with a fade.

Content

Write placeholders as an action, like “Select a voice”, and option labels as nouns in sentence case.
Use trailing for secondary facts such as a count, never for the primary label.

Accessibility

Wrap the Select in Field with FieldLabel, or give SelectTrigger an aria-label when there is no visible label.
Set aria-invalid on SelectTrigger and explain the fix in FieldError; do not rely on the red ring alone.

PreviousSearchbar NextSkeleton