Pharos
Navegar componentes
← Componentes

Selector

SelectorExemplo
Dropdown selector para escolher um único valor de uma lista de opções. Suporta rótulos, validação, descriptions e estados required/optional. Use em formulários e configurações ao apresentar um número moderado de opções.
Importação
import {Selector} from '@pharos-ds/core/Selector';

Exemplos

Área interativa

size
hasSearch
isDisabled
Maçã
Banana
Laranja
Uva
Código
import {Selector} from '@pharos-ds/core/Selector';

<Selector
  size="md"
  hasSearch={false}
  isDisabled={false}
 />

Boas práticas

  • Faça: Forneça um rótulo visível para que usuários entendam o que estão selecionando.
  • Faça: Use sections e dividers para organizar opções quando a lista exceder ~8 itens.
  • Faça: Use renderOption para linhas de opção customizadas. Não passe SelectorOption diretamente como JSX children.
  • Faça: Defina um placeholder significativo que indique a seleção esperada (ex. "Choose a country", não "Select...").
  • Faça: Use dentro de InputGroup apenas quando o selector precisar de um addon curto de prefixo ou sufixo como parte de uma superfície de input decorada.
  • Evite: Use para menus de ação; use Dropdown Menu para disparar comandos ou navegação.
  • Evite: Use quando há apenas duas opções; use SegmentedControl ou radio buttons.
  • Evite: Use Selector para navegação; links devem ser links, não opções de dropdown.
  • Evite: Use para escolhas sim/não ou ligado/desligado; use Switch ou CheckboxInput.
  • Evite: Coloque mais de ~20 opções sem sections; considere Typeahead para listas grandes.
  • Evite: Envolva um Selector desabilitado em Tooltip para explicar por que está desabilitado; triggers desabilitados absorvem os eventos de hover que o wrapper precisa. Use a prop disabledMessage.

Props

PropTipoPadrãoDescrição
label *string—Texto do rótulo para acessibilidade.
options *SelectorOption[]—Array de itens: strings, objetos com value/label/icon/disabled, dividers ({type: "divider"}), ou sections ({type: "section", title, items}).
valuestring—Valor atualmente selecionado.
onChange(value: string) => void—Callback disparado quando a seleção muda.
hasClearbooleanfalseMostra um botão de limpar (×) quando um valor está selecionado. Quando true, onChange também aceita null para sinalizar que o usuário limpou a seleção.
hasSearchbooleanfalseSe deve mostrar um input de busca para filtrar opções. Conforme o usuário digita, a contagem de correspondências (ou "No results found") é anunciada a leitores de tela via live region polite.
searchPlaceholderstring'Search...'Texto placeholder do input de busca.
placeholderstring'Select...'Texto placeholder exibido quando nenhum valor está selecionado.
size'sm' | 'md' | 'lg''md'Variant de tamanho do selector.
isDisabledbooleanfalseDesabilita o selector.
htmlNamestring—Atributo HTML name para envio de formulários. Renderiza um input hidden com o valor selecionado, como um select nativo.
disabledMessagestring—Explica por que o selector está desabilitado. Com isDisabled, mostra tooltip em hover/foco por teclado e mantém o trigger focável via aria-disabled (ativação permanece bloqueada). Use isso em vez de envolver um Selector desabilitado em Tooltip. Controles desabilitados absorvem os eventos de hover que um Tooltip externo precisa.
isLabelHiddenbooleanfalseOculta visualmente o rótulo, mantendo-o acessível.
descriptionstring—Texto auxiliar exibido abaixo do rótulo.
isOptionalbooleanfalseMarca o campo como opcional.
isRequiredbooleanfalseMarca o campo como obrigatório.
status{type: 'error' | 'warning' | 'success', message?: string}—Status de validação com message opcional.
statusVariant'attached' | 'detached''attached'Como a mensagem de status é posicionada em relação ao input. attached sobrepõe diretamente abaixo do input (tratamento com borda); detached flutua abaixo como elemento separado com espaçamento.
renderOption(option: SelectorOptionData) => ReactNode—Função de renderização customizada para cada opção selecionável no dropdown. Use isso em vez de JSX children; dividers e sections são renderizados pelo selector.
widthSizeValue—Largura do campo (número = pixels, string usada como está, ex. "100%"). Dimensiona o campo inteiro (rótulo, controle e status) para mantê-los alinhados.
xstyleStyleXStyles—Estilos StyleX para customização de layout (margens, posicionamento, dimensionamento). Deve ser um valor stylex.create(), não um objeto de estilo inline como style={{}}.
Pacote: @pharos-ds/core · Import: @pharos-ds/core/Selector
Selector · Pharos