componentes / formulário

Select

Escolha uma opção numa lista que abre a partir do botão.

1.2 kB gzip client componentbase ui · select

framework

select-default.tsx

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

const frameworks = [
  { value: "next", label: "Next.js" },
  { value: "astro", label: "Astro" },
  { value: "remix", label: "React Router" },
  { value: "vite", label: "Vite" },
];

export default function SelectDefault() {
  return (
    <Field className="w-full max-w-xs">
      <FieldLabel>framework</FieldLabel>
      <Select defaultValue="next" items={frameworks}>
        <SelectTrigger>
          <SelectValue />
        </SelectTrigger>
        <SelectPopup>
          {frameworks.map((f) => (
            <SelectItem key={f.value} value={f.value}>
              {f.label}
            </SelectItem>
          ))}
        </SelectPopup>
      </Select>
    </Field>
  );
}

Instalação

$ npx shadcn@latest add https://cd-ui.vercel.app/r/select.json

primeira vez? configure o components.json e o tema antes: veja instalação.

Uso

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

<Select items={items} defaultValue="next">
  <SelectTrigger><SelectValue /></SelectTrigger>
  <SelectPopup>
    {items.map((i) => <SelectItem key={i.value} value={i.value}>{i.label}</SelectItem>)}
  </SelectPopup>
</Select>

Exemplos

Grupos e lista longa

SelectGroup, SelectGroupLabel e SelectSeparator organizam as opções. Quando a lista é maior que a tela, ela rola e setas aparecem nas bordas.

time zone

select-grouped.tsx

import { Field, FieldLabel } from "@/components/ui/field";
import { Select, SelectGroup, SelectGroupLabel, SelectItem, SelectPopup, SelectSeparator, SelectTrigger, SelectValue } from "@/components/ui/select";

const groups = [
  {
    label: "Americas",
    zones: [
      { value: "america/sao_paulo", label: "Sao Paulo (GMT-3)" },
      { value: "america/new_york", label: "New York (GMT-5)" },
      { value: "america/chicago", label: "Chicago (GMT-6)" },
      { value: "america/denver", label: "Denver (GMT-7)" },
      { value: "america/los_angeles", label: "Los Angeles (GMT-8)" },
    ],
  },
  {
    label: "Europe",
    zones: [
      { value: "europe/london", label: "London (GMT+0)" },
      { value: "europe/paris", label: "Paris (GMT+1)" },
      { value: "europe/berlin", label: "Berlin (GMT+1)" },
      { value: "europe/athens", label: "Athens (GMT+2)" },
      { value: "europe/moscow", label: "Moscow (GMT+3)" },
    ],
  },
  {
    label: "Asia and Pacific",
    zones: [
      { value: "asia/dubai", label: "Dubai (GMT+4)" },
      { value: "asia/kolkata", label: "Kolkata (GMT+5:30)" },
      { value: "asia/singapore", label: "Singapore (GMT+8)" },
      { value: "asia/tokyo", label: "Tokyo (GMT+9)" },
      { value: "australia/sydney", label: "Sydney (GMT+10)" },
      { value: "pacific/auckland", label: "Auckland (GMT+12)" },
    ],
  },
];

const items = groups.flatMap((g) => g.zones);

export default function SelectGrouped() {
  return (
    <Field className="w-full max-w-xs">
      <FieldLabel>time zone</FieldLabel>
      <Select defaultValue="europe/london" items={items}>
        <SelectTrigger>
          <SelectValue />
        </SelectTrigger>
        <SelectPopup>
          {groups.map((group, i) => (
            <SelectGroup key={group.label}>
              {i > 0 && <SelectSeparator />}
              <SelectGroupLabel>{group.label}</SelectGroupLabel>
              {group.zones.map((zone) => (
                <SelectItem key={zone.value} value={zone.value}>
                  {zone.label}
                </SelectItem>
              ))}
            </SelectGroup>
          ))}
        </SelectPopup>
      </Select>
    </Field>
  );
}

API

Select

Base UI · Select.Root

Raiz. Passe items para o valor exibido usar o rótulo certo antes da lista abrir.

prop	tipo	padrão
`items` Lista de opções (usada pelo `SelectValue`).	`{ value, label }[]`	-
`value · defaultValue` Valor controlado ou inicial.	`string`	-
`onValueChange` Chamado ao escolher.	`(value) => void`	-
`name` Para enviar em formulário.	`string`	-

SelectTrigger · SelectValue

Base UI · Select.Trigger · Select.Value

Botão que abre a lista e o texto do valor atual.

prop	tipo	padrão
`className` Classes extras, mescladas com `cn` (a sua vence).	`string`	-

SelectPopup

Base UI · Select.Popup

Lista. Abre abaixo do gatilho em 160ms, fecha em 120ms e rola com setas quando é longa.

prop	tipo	padrão
`alignItemWithTrigger` Põe o item escolhido sobre o gatilho, como no macOS. Desligado por padrão: a lista não pula por cima do botão.	`boolean`	`false`
`className` Classes extras, mescladas com `cn` (a sua vence).	`string`	-

SelectGroup · SelectGroupLabel · SelectSeparator

Base UI · Select.Group · Select.GroupLabel · Select.Separator

SelectGroup agrupa opções, SelectGroupLabel dá nome ao grupo e SelectSeparator desenha uma linha entre grupos.

prop	tipo	padrão
`className` Classes extras, mescladas com `cn` (a sua vence).	`string`	-

SelectItem

Base UI · Select.Item

Opção com check amarelo à direita quando escolhida.

prop	tipo	padrão
`value` Valor da opção.	`string`	-
`className` Classes extras, mescladas com `cn` (a sua vence).	`string`	-

Teclado

tecla	ação
`SpaceEnter↓`	Abre a lista.
`↑↓`	Navega entre opções.
`Enter`	Escolhe a opção.
`Esc`	Fecha sem mudar.
`A-Z`	Pula para a opção que começa com a letra.

import { Field, FieldLabel } from "@/components/ui/field"; import { Select, SelectItem, SelectPopup, SelectTrigger, SelectValue } from "@/components/ui/select"; const frameworks = [ { value: "next", label: "Next.js" }, { value: "astro", label: "Astro" }, { value: "remix", label: "React Router" }, { value: "vite", label: "Vite" }, ]; export default function SelectDefault() { return ( <Field className="w-full max-w-xs"> <FieldLabel>framework</FieldLabel> <Select defaultValue="next" items={frameworks}> <SelectTrigger> <SelectValue /> </SelectTrigger> <SelectPopup> {frameworks.map((f) => ( <SelectItem key={f.value} value={f.value}> {f.label} </SelectItem> ))} </SelectPopup> </Select> </Field> ); }

Uso

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

<Select items={items} defaultValue="next">
  <SelectTrigger><SelectValue /></SelectTrigger>
  <SelectPopup>
    {items.map((i) => <SelectItem key={i.value} value={i.value}>{i.label}</SelectItem>)}
  </SelectPopup>
</Select>

Exemplos

Grupos e lista longa

SelectGroup, SelectGroupLabel e SelectSeparator organizam as opções. Quando a lista é maior que a tela, ela rola e setas aparecem nas bordas.

time zone

select-grouped.tsx

import { Field, FieldLabel } from "@/components/ui/field";
import { Select, SelectGroup, SelectGroupLabel, SelectItem, SelectPopup, SelectSeparator, SelectTrigger, SelectValue } from "@/components/ui/select";

const groups = [
  {
    label: "Americas",
    zones: [
      { value: "america/sao_paulo", label: "Sao Paulo (GMT-3)" },
      { value: "america/new_york", label: "New York (GMT-5)" },
      { value: "america/chicago", label: "Chicago (GMT-6)" },
      { value: "america/denver", label: "Denver (GMT-7)" },
      { value: "america/los_angeles", label: "Los Angeles (GMT-8)" },
    ],
  },
  {
    label: "Europe",
    zones: [
      { value: "europe/london", label: "London (GMT+0)" },
      { value: "europe/paris", label: "Paris (GMT+1)" },
      { value: "europe/berlin", label: "Berlin (GMT+1)" },
      { value: "europe/athens", label: "Athens (GMT+2)" },
      { value: "europe/moscow", label: "Moscow (GMT+3)" },
    ],
  },
  {
    label: "Asia and Pacific",
    zones: [
      { value: "asia/dubai", label: "Dubai (GMT+4)" },
      { value: "asia/kolkata", label: "Kolkata (GMT+5:30)" },
      { value: "asia/singapore", label: "Singapore (GMT+8)" },
      { value: "asia/tokyo", label: "Tokyo (GMT+9)" },
      { value: "australia/sydney", label: "Sydney (GMT+10)" },
      { value: "pacific/auckland", label: "Auckland (GMT+12)" },
    ],
  },
];

const items = groups.flatMap((g) => g.zones);

export default function SelectGrouped() {
  return (
    <Field className="w-full max-w-xs">
      <FieldLabel>time zone</FieldLabel>
      <Select defaultValue="europe/london" items={items}>
        <SelectTrigger>
          <SelectValue />
        </SelectTrigger>
        <SelectPopup>
          {groups.map((group, i) => (
            <SelectGroup key={group.label}>
              {i > 0 && <SelectSeparator />}
              <SelectGroupLabel>{group.label}</SelectGroupLabel>
              {group.zones.map((zone) => (
                <SelectItem key={zone.value} value={zone.value}>
                  {zone.label}
                </SelectItem>
              ))}
            </SelectGroup>
          ))}
        </SelectPopup>
      </Select>
    </Field>
  );
}

API

Select

Base UI · Select.Root

Raiz. Passe items para o valor exibido usar o rótulo certo antes da lista abrir.

prop	tipo	padrão
`items` Lista de opções (usada pelo `SelectValue`).	`{ value, label }[]`	-
`value · defaultValue` Valor controlado ou inicial.	`string`	-
`onValueChange` Chamado ao escolher.	`(value) => void`	-
`name` Para enviar em formulário.	`string`	-

SelectTrigger · SelectValue

Base UI · Select.Trigger · Select.Value

Botão que abre a lista e o texto do valor atual.

prop	tipo	padrão
`className` Classes extras, mescladas com `cn` (a sua vence).	`string`	-

SelectPopup

Base UI · Select.Popup

Lista. Abre abaixo do gatilho em 160ms, fecha em 120ms e rola com setas quando é longa.

prop	tipo	padrão
`alignItemWithTrigger` Põe o item escolhido sobre o gatilho, como no macOS. Desligado por padrão: a lista não pula por cima do botão.	`boolean`	`false`
`className` Classes extras, mescladas com `cn` (a sua vence).	`string`	-

SelectGroup · SelectGroupLabel · SelectSeparator

Base UI · Select.Group · Select.GroupLabel · Select.Separator

SelectGroup agrupa opções, SelectGroupLabel dá nome ao grupo e SelectSeparator desenha uma linha entre grupos.

prop	tipo	padrão
`className` Classes extras, mescladas com `cn` (a sua vence).	`string`	-

SelectItem

Base UI · Select.Item

Opção com check amarelo à direita quando escolhida.

prop	tipo	padrão
`value` Valor da opção.	`string`	-
`className` Classes extras, mescladas com `cn` (a sua vence).	`string`	-

tecla

ação

SpaceEnter↓

Abre a lista.

↑↓

Navega entre opções.

Enter

Escolhe a opção.

Esc

Fecha sem mudar.

A-Z

Pula para a opção que começa com a letra.