Select

A rich dropdown for picking a single option from a list. Built on base-ui Select — it renders a portaled, fully styleable popup, so items can carry icons, descriptions, groups, and separators that a native <select> can’t.

Reach for this over NativeSelect when you need custom-rendered options or a consistent look across platforms; the NativeSelect is lighter and better for plain text options or mobile-first forms. Reach for Combobox instead when the list is long enough to need type-ahead filtering — Select has no search input. Long lists scroll inside a ScrollArea with edge hints.

Compose the parts: Select (root, owns the value), SelectTrigger (the button), SelectValue (renders the current selection or placeholder), SelectContent (the popup), SelectItem (one option), and SelectGroup + SelectLabel + SelectSeparator for sectioning.

Basic

A trigger, a value, and a flat list of items. Give SelectValue a placeholder for the empty state, and seed an initial selection with defaultValue on the root.

import {
  HStack,
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@vesyl/ui-next";

export default function SelectBasic() {
  return (
    <HStack justify="center">
      <Select defaultValue="usps">
        <SelectTrigger className="w-56">
          <SelectValue placeholder="Select a carrier" />
        </SelectTrigger>
        <SelectContent>
          <SelectItem value="usps">USPS</SelectItem>
          <SelectItem value="ups">UPS</SelectItem>
          <SelectItem value="fedex">FedEx</SelectItem>
          <SelectItem value="dhl">DHL Express</SelectItem>
        </SelectContent>
      </Select>
    </HStack>
  );
}

Grouped options

Wrap related items in SelectGroup, head each group with a SelectLabel, and divide groups with SelectSeparator. Useful for sectioned lists like warehouses by region.

import {
  HStack,
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectLabel,
  SelectSeparator,
  SelectTrigger,
  SelectValue,
} from "@vesyl/ui-next";

export default function SelectGroups() {
  return (
    <HStack justify="center">
      <Select>
        <SelectTrigger className="w-64">
          <SelectValue placeholder="Select a warehouse" />
        </SelectTrigger>
        <SelectContent>
          <SelectGroup>
            <SelectLabel>West Coast</SelectLabel>
            <SelectItem value="lax">Los Angeles, CA</SelectItem>
            <SelectItem value="sea">Seattle, WA</SelectItem>
            <SelectItem value="phx">Phoenix, AZ</SelectItem>
          </SelectGroup>
          <SelectSeparator />
          <SelectGroup>
            <SelectLabel>East Coast</SelectLabel>
            <SelectItem value="ewr">Newark, NJ</SelectItem>
            <SelectItem value="atl">Atlanta, GA</SelectItem>
            <SelectItem value="mia">Miami, FL</SelectItem>
          </SelectGroup>
        </SelectContent>
      </Select>
    </HStack>
  );
}

Dense

size="sm" on the root tightens the trigger and the popup list together — group labels hug the first row, items use the same inset as Combobox sm. The popup still uses ScrollArea when the list overflows.

import { Fragment } from 'react'
import {
  HStack,
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectLabel,
  SelectSeparator,
  SelectTrigger,
  SelectValue,
} from '@vesyl/ui-next'

const GROUPS = [
  {
    label: 'Order',
    items: [
      ['status', 'Order status'],
      ['tags', 'Order tags'],
      ['total', 'Order total (USD)'],
      ['weight', 'Order weight'],
      ['customer', 'Customer name'],
      ['phone', 'Has phone number'],
    ],
  },
  {
    label: 'Destination',
    items: [
      ['country', 'Country'],
      ['state', 'State'],
      ['city', 'City'],
      ['postal', 'Postal code'],
      ['po-box', 'Address is PO box'],
    ],
  },
  {
    label: 'Products',
    items: [
      ['sku', 'Product SKU'],
      ['name', 'Product name'],
      ['qty', 'Product quantity'],
      ['line-weight', 'Line item weight'],
    ],
  },
] as const

export default function SelectDense() {
  return (
    <HStack justify="center">
      <Select size="sm" defaultValue="country">
        <SelectTrigger className="w-64">
          <SelectValue placeholder="Select a field" />
        </SelectTrigger>
        <SelectContent>
          {GROUPS.map((group, index) => (
            <Fragment key={group.label}>
              {index > 0 ? <SelectSeparator /> : null}
              <SelectGroup>
                <SelectLabel>{group.label}</SelectLabel>
                {group.items.map(([value, label]) => (
                  <SelectItem key={value} value={value}>
                    {label}
                  </SelectItem>
                ))}
              </SelectGroup>
            </Fragment>
          ))}
        </SelectContent>
      </Select>
    </HStack>
  )
}

Disabled items

Mark an individual option unselectable with disabled on the SelectItem — it dims and skips keyboard focus while the rest of the list stays usable.

import {
  HStack,
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@vesyl/ui-next";

export default function SelectDisabledItems() {
  return (
    <HStack justify="center">
      <Select>
        <SelectTrigger className="w-56">
          <SelectValue placeholder="Select a service" />
        </SelectTrigger>
        <SelectContent>
          <SelectItem value="ground">Ground</SelectItem>
          <SelectItem value="priority">Priority</SelectItem>
          <SelectItem value="express">Express</SelectItem>
          <SelectItem value="overnight" disabled>
            Overnight (unavailable)
          </SelectItem>
        </SelectContent>
      </Select>
    </HStack>
  );
}

Controlled

Select is uncontrolled by default — pass defaultValue. To drive it yourself, pass value and onValueChange. When you control it, give SelectValue an items array ({ value, label }) so the trigger shows the option’s label instead of its raw value.

Current status: pending

import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
  Stack,
} from "@vesyl/ui-next";
import { useState } from "react";

const STATUSES = [
  { value: "pending", label: "Pending" },
  { value: "processing", label: "Processing" },
  { value: "shipped", label: "Shipped" },
  { value: "delivered", label: "Delivered" },
  { value: "cancelled", label: "Cancelled" },
];

export default function SelectControlled() {
  const [status, setStatus] = useState("pending");

  return (
    <Stack gap={3} align="center">
      <Select value={status} onValueChange={(v) => setStatus(v as string)}>
        <SelectTrigger className="w-56">
          <SelectValue items={STATUSES} placeholder="Select a status" />
        </SelectTrigger>
        <SelectContent>
          {STATUSES.map((s) => (
            <SelectItem key={s.value} value={s.value}>
              {s.label}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
      <p className="text-muted-foreground text-sm">
        Current status: <span className="text-foreground font-medium">{status}</span>
      </p>
    </Stack>
  );
}

Reference

Select

Root container. Extends base-ui Select.Root props.

Prop	Type	Default	Description
`defaultValue`	`any`	—	Initially selected value (uncontrolled)
`value`	`any`	—	Selected value (controlled)
`onValueChange`	`(value) => void`	—	Fires when the selection changes
`disabled`	`boolean`	`false`	Disables the whole control
`name`	`string`	—	Field name when used inside a form
`size`	`"md" \| "sm"`	`"md"`	Trigger height and popup list density

SelectTrigger

The button that opens the popup. Extends base-ui Select.Trigger props.

Prop	Type	Default	Description
`size`	`"md" \| "sm"`	`"md"`	Trigger height. Inherited from `Select` when omitted.
`className`	`string`	—	Merged onto the trigger

SelectTriggerButton is an alternative trigger that renders through the Button component (defaults to variant="ghost", size="sm") — use it when the trigger should blend into a toolbar or card header instead of looking like a bordered input.

SelectValue

Renders the current selection inside the trigger. Extends base-ui Select.Value props.

Prop	Type	Default	Description
`placeholder`	`string`	—	Shown when nothing is selected
`items`	`ReadonlyArray<{ value, label }>`	—	Look-up table so the trigger shows a label, not the raw value
`children`	`(value) => ReactNode`	—	Custom render function (alternative to `items`/`placeholder`)

SelectContent

The portaled popup. Extends base-ui Select.Popup plus positioning props.

Prop	Type	Default	Description
`side`	`"top" \| "right" \| "bottom" \| "left"`	`"bottom"`	Side of the trigger to open on
`sideOffset`	`number`	`4`	Gap between trigger and popup
`align`	`"start" \| "center" \| "end"`	`"center"`	Alignment along the trigger edge
`alignOffset`	`number`	`0`	Offset along the alignment axis
`alignItemWithTrigger`	`boolean`	`false`	Anchor the selected item over the trigger
`size`	`"md" \| "sm"`	inherited	Popup list density. Inherited from `Select`.

SelectItem

A single option. Extends base-ui Select.Item props.

Prop	Type	Default	Description
`value`	`any`	—	The value selecting this item sets
`disabled`	`boolean`	`false`	Prevents selection and keyboard focus

SelectGroup

Groups a set of items. Extends base-ui Select.Group props.

SelectLabel

A heading for a group. Extends base-ui Select.GroupLabel props.

SelectSeparator

A horizontal divider between groups. Extends base-ui Select.Separator props.