Capítulo 29 de 108

Native Select

Core Idea

Elemento HTML <select> nativo estilizado com integração consistente ao design system. Use quando quiser comportamento nativo do navegador, melhor performance ou dropdowns otimizados para mobile, em vez de um popup customizado.

Key Concepts

  • NativeSelect: wrapper que envolve o <select> nativo.
  • NativeSelectOption: opção individual (value, disabled).
  • NativeSelectOptGroup: agrupa opções relacionadas com label e disabled opcionais.
  • disabled: no NativeSelect desabilita o controle inteiro.
  • aria-invalid: string "true" no NativeSelect sinaliza estado de erro (com data-invalid no Field para estilo).
  • Sem dependência extra: ao contrário de Checkbox/Select, não requer instalar @base-ui/react (é <select> nativo estilizado).

Code Examples

import {
  NativeSelect,
  NativeSelectOption,
} from "@/components/ui/native-select"

export function NativeSelectDemo() {
  return (
    <NativeSelect>
      <NativeSelectOption value="">Select status</NativeSelectOption>
      <NativeSelectOption value="todo">Todo</NativeSelectOption>
      <NativeSelectOption value="in-progress">In Progress</NativeSelectOption>
      <NativeSelectOption value="done">Done</NativeSelectOption>
    </NativeSelect>
  )
}
  • O que demonstra: uso básico com opção vazia como placeholder.
<NativeSelect>
  <NativeSelectOption value="">Select department</NativeSelectOption>
  <NativeSelectOptGroup label="Engineering">
    <NativeSelectOption value="frontend">Frontend</NativeSelectOption>
    <NativeSelectOption value="backend">Backend</NativeSelectOption>
  </NativeSelectOptGroup>
  <NativeSelectOptGroup label="Sales">
    <NativeSelectOption value="sales-rep">Sales Rep</NativeSelectOption>
  </NativeSelectOptGroup>
</NativeSelect>
  • O que demonstra: agrupamento de opções com NativeSelectOptGroup.

Reference Tables

NativeSelectOption

PropTypeDefault
valuestring
disabledbooleanfalse

NativeSelectOptGroup

PropTypeDefault
labelstring
disabledbooleanfalse

Composição simples (sem grupos):

NativeSelect
├── NativeSelectOption
├── NativeSelectOption
├── NativeSelectOption
└── NativeSelectOption

Composição com grupos:

NativeSelect
├── NativeSelectOptGroup
│   ├── NativeSelectOption
│   └── NativeSelectOption
└── NativeSelectOptGroup
    ├── NativeSelectOption
    └── NativeSelectOption

Anti-patterns

  • Usar NativeSelect quando precisa de estilização/animação avançada do popup: nesse caso o componente correto é Select (Base UI), não NativeSelect.

Key Takeaways

  1. Escolha NativeSelect para comportamento nativo, performance e melhor UX mobile; escolha Select para popup customizado, animações e interações complexas.
  2. NativeSelectOption com value="" funciona como placeholder/opção vazia, igual ao padrão de items com value: null do Select.
  3. NativeSelectOptGroup mapeia diretamente para <optgroup> nativo, aceitando disabled para desabilitar o grupo inteiro.
  4. Estado inválido usa aria-invalid="true" (string) no NativeSelect, diferente do Select/Checkbox que usam a prop booleana implícita.
  5. Não requer @base-ui/react: instalação manual só copia o componente, sem dependência extra.

Connects To

  • Select: par direto para decidir entre popup customizado (Select) vs. <select> nativo (NativeSelect); a doc do Select referencia esta página e vice-versa.
  • Field: fornece label, descrição e wrapper de erro (data-invalid) ao redor do NativeSelect.
AnteriorSelectPróximoSwitch