Select

Installation

pnpm dlx shadcn@latest add @uitopia/select

Usage

import {
  Select,
  SelectItem,
  SelectPopup,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select"

const items = [
  { label: "Select framework", value: null },
  { label: "Next.js", value: "next" },
  { label: "Vite", value: "vite" },
  { label: "Astro", value: "astro" },
]

<Select items={items}>
  <SelectTrigger>
    <SelectValue />
  </SelectTrigger>
  <SelectPopup>
    {items.map((item) => (
      <SelectItem key={item.value} value={item}>
        {item.label}
      </SelectItem>
    ))}
  </SelectPopup>
  </Select>

Examples

For accessible labelling and validation, prefer using the Field component to wrap selects. See the related example: Select field.

Small Size

Large Size

Disabled

Without Item Alignment

With Groups

Multiple Selection

Form Integration

Comparing with Radix / shadcn

If you’re already familiar with Radix UI and shadcn/ui, this guide highlights the small differences and similarities so you can get started with ui/topia quickly.

Important: Base UI changes how options are provided. Instead of deriving options from children only (Radix pattern), you should pass an items prop (array or record) so values and labels are known before hydration. This avoids SSR pitfalls and improves mount performance. Alternatively, provide a function child to SelectValue to format the label. See the Base UI Select docs.

Prop Mapping

Quick Checklist

• Set items prop on Select
• Remove placeholder from Select
• Prefer SelectPopup instead of SelectContent
• If you used asChild on parts, switch to the render prop

Additional Notes

Size Comparison

ui/topia select sizes are more compact compared to shadcn/ui, making them better suited for dense applications:

So, for example, if you were using the default size in shadcn/ui and you want to preserve the original height, you should use the lg size in ui/topia.

New Prop

Base UI introduces the alignItemWithTrigger prop to control whether the SelectContent overlaps the SelectTrigger so the selected item's text is aligned with the trigger's value text.

Comparison Example

<Select>
  <SelectTrigger>
    <SelectValue placeholder="Select a framework" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="next">Next.js</SelectItem>
    <SelectItem value="vite">Vite</SelectItem>
    <SelectItem value="astro">Astro</SelectItem>
  </SelectContent>
</Select>

<Select
  items={[
    { label: "Select a framework", value: null },
    { label: "Next.js", value: "next" },
    { label: "Vite", value: "vite" },
    { label: "Astro", value: "astro" },
  ]}
>
  <SelectTrigger>
    <SelectValue />
  </SelectTrigger>
  <SelectPopup alignItemWithTrigger={false}>
    {items.map((item) => (
      <SelectItem key={item.value} value={item}>
        {item.label}
      </SelectItem>
    ))}
  </SelectPopup>
</Select>