Select

Componente estável e recomendada para novos projetos.

Anatomia, uso, comportamento visual e recomendações conceituais são mantidos pelo Padrão Digital de Governo. Esta página documenta a implementação Web Components e sua API executável.

Visão Geral

O componente br-select é o controle oficial de seleção do GovBR-DS, desenvolvido para permitir que o usuário escolha uma ou múltiplas opções a partir de uma lista expansível. Compatível com o padrão WAI-ARIA Combobox, ele reúne em um único componente acessível o campo de acionamento/digitação, a lista suspensa e as opções selecionáveis, integrando-se nativamente a formulários HTML e frameworks modernos.

Para que serve

O br-select gerencia todo o fluxo de interação de seleção:

• Seleção simples e múltipla: Permite selecionar uma única opção ou múltiplas opções (multiple), incluindo a opção de selecionar ou desmarcar todas em lote.
• Busca e filtragem: Oferece filtro local integrado (conforme o usuário digita) e suporte a busca remota assíncrona (search-mode="remote"), disparando eventos para carregamento sob demanda via API.
• Agrupamento de opções: Organiza opções contíguas por categoria, preservando virtualização, busca local e semântica nativa de formulário.
• Integração com formulários: É associado a formulários nativos (formAssociated), comunicando seu valor, estado de validação (válido/inválido), mensagens de erro contextuais e eventos padrão (change, input).
• Navegação acessível: Suporta controle total via teclado (setas para cima/baixo, Enter, Escape, Home, End), foco gerenciado e anúncios para leitores de tela.

Navegação por teclado

O foco permanece no campo combobox enquanto a lista está aberta; a opção em destaque é comunicada por aria-activedescendant. Ao receber foco, o campo abre a lista sem alterar a seleção atual.

• ArrowDown / ArrowUp: abre a lista e destaca a próxima opção na direção pressionada; com a lista aberta, move o destaque sem mover o foco físico.
• Home / End: em modo não filtrável, destaca a primeira ou a última opção habilitada; em modo filtrável, preserva o movimento do cursor no texto.
• Enter: abre a lista quando fechada e confirma a opção destacada quando aberta.
• Espaço: confirma a opção destacada em modo não filtrável; em modo filtrável, insere um espaço no campo de busca.
• Escape: fecha a lista, remove o destaque e devolve o foco ao campo.
• Tab: fecha a lista e deixa o navegador mover o foco para o próximo controle, sem alterar a seleção implicitamente.
• Busca incremental: em modo não filtrável, caracteres consecutivos destacam a primeira opção habilitada correspondente; em modo filtrável, a digitação filtra a lista.
• Alt+ArrowDown / Alt+ArrowUp: abre ou fecha a lista sem alterar a seleção.

Quando utilizar

• Utilize quando:
  • O número de opções for moderado a grande (mais de 5 a 7 itens), onde listar todas diretamente na tela consumiria muito espaço visual.
  • For necessário filtrar opções por texto (digitação em lista longa).
  • As opções forem carregadas dinamicamente de uma API externa (busca remota/paginada).
  • O espaço no leiaute for restrito e exigir um controle compacto e expansível.
• Evite e prefira outro componente quando:
  • Houver poucas opções fixas (de 2 a 4 opções mutuamente exclusivas): prefira br-radio ou br-radio-group para manter as alternativas imediatamente visíveis.
  • Houver uma escolha binária (sim/não, ativo/inativo): prefira br-switch ou br-checkbox.
  • Houver seleção múltipla com até 4 alternativas: prefira br-checkbox ou um grupo de checkboxes visíveis.

Composição e Subcomponentes

O ecossistema do Select é composto pelo elemento principal orquestrador e três subcomponentes especializados:

Subcomponente	Papel	Regra de uso
br-select-input	Campo de acionamento. Exibe o valor selecionado, o rótulo (label), o campo de busca/digitação e o botão de expandir/recolher.	Coordenado automaticamente pelo br-select; utilize isoladamente apenas em composições arquiteturais avançadas.
br-select-list	Lista suspensa virtualizada. Contêiner flutuante que renderiza as opções de forma otimizada com suporte a rolagem e virtualização.	Gerenciada exclusivamente pelo br-select; não deve ser usada como controle autônomo.
br-select-option	Item individual de opção. Representa um valor selecionável, exibindo texto, estado de seleção e checkbox/radio associado.	Deve ser declarado dentro do slot padrão do br-select para cada opção desejada.
br-select	Orquestrador principal. Gerencia o valor, ciclo de vida, acessibilidade, busca, formulário e renderização dos elementos internos.	Deve ser o único componente diretamente instanciado no template da aplicação.

Além dos subcomponentes, o br-select oferece slots dedicados:

• default: Slot principal onde são passados os elementos br-select-option.
• feedback: Slot para exibição de mensagens de validação (ex.: br-message).
• loading: Slot para indicador de carregamento durante busca remota.
• validation-loading: Slot para indicador visual durante validação assíncrona.

Como fornecer opções

O br-select possui uma API declarativa canônica e uma API imperativa para atualizações dinâmicas:

1. Slot com br-select-option: é a forma declarativa canônica para código novo. O pai lê os atributos e o conteúdo de cada opção e os transforma em dados para a lista. Em frameworks, a coleção também pode ser renderizada como vários elementos br-select-option.
2. Método setOptions(): substitui a coleção de forma imperativa e deve ser reservado para dados dinâmicos, especialmente respostas de busca remota. A lista recebe os objetos e cria internamente somente a janela visível de opções.

br-select-input e br-select-list não substituem essas fontes. Eles são peças internas da composição: o primeiro controla o campo de acionamento e busca; o segundo recebe a coleção normalizada e renderiza a lista virtualizada.

Evite misturar slot e dados imperativos sem necessidade. Na inicialização, opções declaradas no slot têm precedência quando existem. Depois que options é alterada ou setOptions() é chamado, a coleção imperativa passa a ser a fonte de dados e alterações posteriores no slot não são sincronizadas.

A prop options é uma API legada e está depreciada. Ela continua funcionando apenas para preservar compatibilidade: no HTML, recebe uma string JSON; em JavaScript e frameworks, recebe um array por property binding. Não a adote em código novo; use br-select-option ou, para respostas dinâmicas/remotas, setOptions().

Cada objeto deve conter value string e pode conter label, selected, disabled, indeterminate e content. content é renderizado como HTML na lista; não use esse campo com conteúdo não confiável.

O Conceito "Lego" e a Diferença entre os Componentes

O ecossistema de seleção do GovBR-DS foi projetado seguindo o conceito de peças de Lego: modular, flexível e combinável:

1. br-select (Componente Principal / Modelo Pronto): É o componente principal. Já vem montado com todas as peças essenciais integradas: o acionador (br-select-input), a lista flutuante virtualizada (br-select-list), a navegação por teclado e a integração nativa com formulários (formAssociated). Na quase totalidade das aplicações (99% dos casos), você deve usar apenas <br-select>.

2. br-select-option (Peça de Conteúdo): É a peça de Lego que você encaixa diretamente no slot padrão do <br-select> para definir cada valor selecionável.

3. br-select-input e br-select-list (Subcomponentes Internos): São as peças internas que formam a estrutura do br-select. No uso comum, não devem ser declarados manualmente, pois o br-select já os instancia e os sincroniza automaticamente.

Quando usar apenas <br-select>?

Use apenas <br-select> em quase todos os fluxos. Para opções fixas, declare os itens <br-select-option> no slot padrão; para opções dinâmicas, alimente a coleção com setOptions(). A prop options permanece disponível somente para compatibilidade legada.

Quando montar os componentes separadamente?

A montagem separada das peças avulsas de Lego (br-select-input + br-select-list + br-select-option) destina-se exclusivamente a composições arquiteturais avançadas, onde o leiaute exige desacoplar fisicamente o campo de acionamento da lista suspensa (ex.: campo de busca fixo na barra superior e a lista exibida dentro de um drawer ou modal lateral). Nesse caso, a aplicação precisa implementar manualmente a sincronização de foco, abertura, navegação por teclado e repasse de valor ao formulário.

Como os subcomponentes se relacionam

A arquitetura do br-select segue o padrão de orquestrador centralizado:

1. O componente pai coordena o estado: A aplicação declara o <br-select> com múltiplos <br-select-option> filhos ou usa setOptions() para dados dinâmicos. O br-select projeta internamente o <br-select-input> e a <br-select-list>, garantindo sincronia total de foco, estados de abertura, termos pesquisados e eventos. A prop options não é uma alternativa para código novo; existe somente para compatibilidade legada.
2. Evite montagem manual desarticulada: Tentar declarar manualmente br-select-input e br-select-list fora do br-select quebra as relações de acessibilidade WAI-ARIA (combobox, controles expandidos, aria-activedescendant) e desvincula o controle da validação nativa de formulários (ElementInternals).
3. Comunicação por eventos: Para busca remota ou resposta a seleção, a aplicação escuta os eventos disparados diretamente pelo br-select (brSearch, change, input), sem precisar interceptar nós internos da lista ou do campo de texto.

Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o Design System do GovBR.

Exemplo

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

PadrãoSeleção múltiplaDesabilitadoOpções agrupadasOpção com imagem e textoLista virtualizada com 1000 itensBusca remota

Compartilhar URL

Ativar movimento reduzido

Mudar fundo

Abrir no StackBlitz

Mais opções

Tela cheia

Carregando preview…

HTML

Controles do componente

Console: logs, eventos e erros

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Desfazer alteração

Refazer alteração

Comparar alterações

Formatar código

Resetar código para o estado inicial

Escolher formato para copiar

Como fornecer opções

O caminho declarativo canônico é compor o br-select com elementos br-select-option no slot. Em frameworks, renderize um br-select-option para cada item da coleção. O pai transforma esses elementos em dados para a mesma lista virtualizada.

Para opções fixas, use br-select-option no slot padrão:

<br-select label="Estado">
  <br-select-option value="df" label="Distrito Federal"></br-select-option>
  <br-select-option value="sp" label="São Paulo"></br-select-option>
</br-select>

Quando a lista reúne categorias diferentes, informe group em opções contíguas. O grupo passa a compor a lista virtualizada, a busca local, o nome acessível de cada opção e os elementos <optgroup> usados na integração com formulários:

<br-select label="Serviço público">
  <br-select-option group="Federais" value="inss" label="Meu INSS"></br-select-option>
  <br-select-option group="Federais" value="receita" label="Receita Federal"></br-select-option>
  <br-select-option group="Estaduais" value="detran" label="Detran"></br-select-option>
</br-select>

Mantenha juntas as opções do mesmo grupo. Se um nome reaparecer depois de outro grupo, ele inicia uma nova seção visual e um novo <optgroup>.

Para respostas dinâmicas, especialmente em busca remota, use setOptions():

const select = document.querySelector('br-select');

await select.setOptions([
  { value: 'df', label: 'Distrito Federal' },
  { value: 'sp', label: 'São Paulo' },
]);

API depreciada: a prop options continua funcionando somente para compatibilidade. Ela aceita um array por property binding ou uma string JSON no atributo HTML, mas não deve ser adotada em código novo. Use br-select-option no slot ou, para respostas dinâmicas/remotas, setOptions().

Como a sincronização funciona

1. O br-select lê cada br-select-option projetado e transforma seus atributos e conteúdo em dados (value, label, selected e demais estados).
2. Quando recebe dados por options ou setOptions(), normaliza os objetos e os entrega ao br-select-list.
3. O br-select-list cria internamente elementos br-select-option apenas para a janela visível. Os elementos declarados no slot são a fonte declarativa; não são os itens visuais finais da lista virtualizada.
4. O br-select mantém seleção, valor, input, eventos, ARIA e formulário sincronizados.

Se houver opções no slot durante a inicialização, elas têm precedência sobre a prop options. Depois que options é alterada ou setOptions() é chamado, a coleção imperativa passa a ser a fonte de dados; evite misturar as duas formas sem uma regra clara de atualização.

Os objetos podem conter value, label, group, selected, disabled, indeterminate e content. Como content é renderizado como HTML, não passe nesse campo conteúdo vindo de fonte não confiável.

br-select-input e br-select-list não devem ser usados para substituir essa API. Eles são subcomponentes internos coordenados pelo br-select: o primeiro é o campo de acionamento e busca; o segundo é o painel virtualizado. Usá-los isoladamente exige que a aplicação coordene foco, teclado, abertura, seleção, ARIA e integração com formulários.

Propriedades

autocomplete

Atributo	autocomplete
Descrição	Controla o autocomplete do campo de busca interno. Aceita on ou off; valores inválidos são ignorados.
Tipo	"off" | "on"
Valor padrão	---

borderless

Atributo	borderless
Descrição	Remove a borda do input quando o componente não está em foco.
Tipo	boolean
Valor padrão	false

customId

Atributo	custom-id
Descrição	Identificador público do controle.
Tipo	string
Valor padrão	generateUniqueId('br-select')

density

Atributo	density
Descrição	Define a densidade visual compartilhada pelo campo e pela lista de opções. Aceita small, medium ou large. Valores inválidos usam medium. A opção sintética de selecionar todos permanece com densidade small.
Tipo	"large" | "medium" | "small"
Valor padrão	'medium'

disabled

Atributo	disabled
Descrição	Desativa toda a interação do select.
Tipo	boolean
Valor padrão	false

filterable

Atributo	filterable
Descrição	Habilita a filtragem textual das opções por rótulo ou valor.
Tipo	boolean
Valor padrão	true

hideDividers

Atributo	hide-dividers
Descrição	Oculta os divisores entre opções consecutivas, sem alterar a altura das linhas.
Tipo	boolean
Valor padrão	false

inline

Atributo	inline
Descrição	Exibe rótulo e controle em linha. Quando informada, tem precedência sobre isInline.
Tipo	boolean
Valor padrão	---

inputWidth

Atributo	input-width
Descrição	Controla a largura do campo de entrada.
Exemplo de uso	'20rem'
Tipo	string
Valor padrão	undefined

isInline Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Atributo	is-inline
Depreciação	Use inline.
Descrição	Exibe label e campo na mesma linha.
Tipo	boolean
Valor padrão	false

isMultiple Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Atributo	is-multiple
Depreciação	Use multiple.
Descrição	Habilita o modo de seleção múltipla.
Tipo	boolean
Valor padrão	false

isOpen Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Atributo	is-open
Depreciação	Use open.
Descrição	Controla o estado aberto/fechado da lista.
Tipo	boolean
Valor padrão	false

itemHeight

Atributo	item-height
Descrição	Informa a altura base de cada opção ou cabeçalho para o cálculo de virtual scroll. Deve ser um número finito positivo; valores inválidos usam 40.
Tipo	number
Valor padrão	40

keepOpenOnSelect Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Atributo	keep-open-on-select
Depreciação	O comportamento atual usa o fechamento padrão do select; mantenha esta prop apenas para compatibilidade com integrações legadas.
Descrição	Mantém a lista aberta depois de uma seleção.
Tipo	boolean
Valor padrão	false

label

Atributo	label
Descrição	Texto exibido como rótulo do campo.
Tipo	string
Valor padrão	---

loading

Atributo	loading
Descrição	Indica que uma busca remota de opções está pendente. Enquanto ativo, novas opções não podem ser selecionadas; a aplicação continua responsável por debounce, cancelamento, erros e autenticação.
Tipo	boolean
Valor padrão	false

maxSelections

Atributo	max-selections
Descrição	Quantidade máxima de opções selecionadas no modo múltiplo. Deve ser um inteiro não negativo; valores inválidos usam 0.
Tipo	number
Valor padrão	0

minSelections

Atributo	min-selections
Descrição	Quantidade mínima de opções selecionadas no modo múltiplo. Deve ser um inteiro não negativo; valores inválidos usam 0.
Tipo	number
Valor padrão	0

multiple

Atributo	multiple
Descrição	Habilita seleção múltipla. Quando informada, tem precedência sobre isMultiple.
Tipo	boolean
Valor padrão	---

name

Atributo	name
Descrição	Nome do campo para integração com formulários.
Tipo	string
Valor padrão	---

open

Atributo	open
Descrição	Controla o estado aberto. Quando informada, tem precedência sobre isOpen.
Tipo	boolean
Valor padrão	---

options Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Atributo	options
Depreciação	Use br-select-option no slot padrão ou setOptions() para respostas dinâmicas/remotas.
Descrição	Fornece opções como array ou JSON, além das opções projetadas por slot. Use property binding para arrays em JavaScript e frameworks; no atributo HTML, informe uma string JSON válida. Na inicialização, opções no slot têm precedência quando existem. Depois de uma alteração nesta prop ou de uma chamada a setOptions(), a coleção imperativa passa a ser a fonte de dados. Não use em código novo. Declare br-select-option no slot padrão ou, para respostas dinâmicas/remotas, atualize a coleção com setOptions().
Exemplo de uso	<!-- Compatibilidade legada; prefira elementos br-select-option. --> <br-select options='[{"label":"Distrito Federal","value":"df"}]'></br-select>
Tipo	SelectOptionData[] | string | { group?: string; label: string; value: string; selected?: boolean; }[]
Valor padrão	[]

overscan

Atributo	overscan
Descrição	Define quantas opções extras são renderizadas antes e depois da área visível no virtual scroll. Deve ser um inteiro não negativo; valores inválidos usam 1.
Tipo	number
Valor padrão	1

placeholder

Atributo	placeholder
Descrição	Texto exibido quando não há seleção.
Tipo	string
Valor padrão	''

required

Atributo	required
Descrição	Indica que o preenchimento do select é obrigatório.
Tipo	boolean
Valor padrão	false

searchMode

Atributo	search-mode
Descrição	Define se as opções são filtradas localmente ou fornecidas por uma busca remota. Em remote, o componente emite brSelectSearch; a aplicação deve buscar, validar e aplicar as opções por setOptions().
Tipo	"local" | "remote"
Valor padrão	'local'

selectAllLabel

Atributo	select-all-label
Descrição	Rótulo apresentado para a opção de selecionar todos no modo múltiplo.
Tipo	string
Valor padrão	Select.SELECT_ALL_LABEL

showSearchIcon

Atributo	show-search-icon
Descrição	Exibe o ícone de busca no campo de entrada.
Tipo	boolean
Valor padrão	false

unselectAllLabel

Atributo	unselect-all-label
Descrição	Rótulo apresentado quando todas as opções já estão selecionadas no modo múltiplo.
Tipo	string
Valor padrão	Select.DESELECT_ALL_LABEL

validator Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.

Atributo	validator
Descrição	Validação síncrona ou assíncrona executada no método validate(). Recebe uma string no modo simples e um array de strings no modo múltiplo.
Exemplo de uso	const select = document.querySelector('br-select'); select.validator = (value) => (Array.isArray(value) ? value.length > 0 : Boolean(value)) ? null : 'Selecione uma opção';
Tipo	((value: string | string[]) => string | Promise<string>) | string
Valor padrão	---

value

Atributo	value
Descrição	Valor público do select baseado nas opções atualmente selecionadas.
Exemplo de uso	const select = document.querySelector('br-select'); select.multiple = true; select.value = ['df', 'sp'];
Observações	Em modo múltiplo, o valor público é um array de strings.
Tipo	string | string[]
Valor padrão	''

visibleItems

Atributo	visible-items
Descrição	Define quantas linhas visuais ficam visíveis na janela da lista. Cabeçalhos de grupo também ocupam uma linha quando existem. Deve ser um inteiro positivo; valores inválidos usam 6.
Tipo	number
Valor padrão	6

Slots

Nome	Descrição
"default"	Opções declaradas com elementos br-select-option.
"feedback"	Mensagem de validação, normalmente um br-message.
"loading"	Indicador exibido durante a busca remota de opções.
"validation-loading" Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.	Indicador exibido durante validação assíncrona.

Eventos

Evento	Descrição	Depreciação	Propagação
brSelectSearch	Emitido uma vez por edição do campo de busca, inclusive ao limpar a consulta. O detail contém { query }; o evento é informativo e não cancelável. A aplicação deve controlar debounce, transporte e ciclo de vida da busca.	---	true
brSelectStateChange	Evento emitido quando o estado público do select muda.	---	true
brSelectValidationChange Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.	Informa o início e o resultado de uma validação síncrona ou assíncrona. O detail contém validating, valid e message.	---	true
closed Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.	Emitido quando a lista é fechada.	Use brSelectStateChange.	true
opened Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.	Emitido quando a lista é aberta.	Use brSelectStateChange.	true
optionHover Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.	Emite a opção que recebeu foco ou hover.	Use a navegação e os eventos de estado atuais.	true
valueChange Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.	Evento emitido quando o valor público do select é alterado.	Use os eventos nativos input e change.	true

Métodos

checkValidity

Descrição
Assinatura	checkValidity() => Promise<boolean>
Parâmetros	---

clear Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Descrição	Limpa a seleção atual.
Assinatura	clear() => Promise<void>
Depreciação	Use setValue('') ou a API de formulário.
Parâmetros	---

close

Descrição	Fecha a lista de opções quando o componente está habilitado.
Assinatura	close() => Promise<void>
Parâmetros	---

disable

Descrição	Desabilita o select e impede novas interações.
Assinatura	disable() => Promise<void>
Parâmetros	---

enable

Descrição	Habilita o select para interação do usuário.
Assinatura	enable() => Promise<void>
Parâmetros	---

getValidationState

Descrição
Assinatura	getValidationState() => Promise<FormValidationState>
Parâmetros	---

getValue Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Descrição	Retorna o valor público atual.
Assinatura	getValue() => Promise<string | string[]>
Depreciação	Leia a propriedade value diretamente.
Parâmetros	---

reportValidity

Descrição
Assinatura	reportValidity() => Promise<boolean>
Parâmetros	---

setCustomValidity

Descrição
Assinatura	setCustomValidity(message: string) => Promise<void>
Parâmetros	message:

setFocus Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Descrição	Move o foco para o campo interno.
Assinatura	setFocus() => Promise<void>
Depreciação	Use o foco nativo do componente quando possível.
Parâmetros	---

setOption

Descrição	Adiciona ou atualiza uma única opção na coleção interna.
Assinatura	setOption(option: SelectOptionData) => Promise<void>
Parâmetros	option: Opção que deve ser inserida ou atualizada.

setOptions

Descrição	Substitui a coleção atual de opções por uma nova lista.
Assinatura	setOptions(options: SelectOptionData[]) => Promise<void>
Parâmetros	options: Opções que devem ser exibidas pela lista interna.
Em search-mode="remote", a seleção atual é preservada mesmo quando não
aparece na resposta recebida.

setValue Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Descrição	Define o valor público do select.
Assinatura	setValue(value: string | string[]) => Promise<void>
Depreciação	Atribua a propriedade value diretamente.
Parâmetros	value:

show

Descrição	Abre a lista de opções quando o componente está habilitado.
Assinatura	show() => Promise<void>
Parâmetros	---

toggleOpen

Descrição	Alterna entre os estados aberto e fechado do select.
Assinatura	toggleOpen() => Promise<void>
Parâmetros	---

validate Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.

Descrição
Assinatura	validate() => Promise<boolean>
Parâmetros	---

CSS Shadow Parts

Nome	Descrição
"container"	Contêiner visual principal do select.
"empty-option"	Alias legado para a opção vazia da lista.
"feedback"	Área de mensagem de validação.
"hidden-select"	Select nativo invisível usado na integração com formulários.
"input-action-button"	Botão interno da ação.
"input-action"	Botão de abertura e fechamento.
"input-container"	Contêiner visual do campo.
"input-field"	Campo input nativo.
"input-group"	Grupo visual do campo.
"input-icon"	Ícone do campo.
"input-label"	Rótulo do campo.
"input"	Campo de seleção e busca.
"list"	Lista de opções.
"option-checkbox"	Alias legado para o checkbox da opção.
"option-group"	Cabeçalho visual de um grupo de opções.
"option-radio"	Alias legado para o radio da opção.
"option"	Opção individual.
"select-all"	Alias legado para a opção de selecionar todos.
"validation-loading" Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.	Área do indicador de validação assíncrona.

Validação

Para o contrato geral e a matriz de componentes, consulte o guia de formulários. Esta seção documenta o contrato específico do br-select.

br-select suporta required e, para seleções múltiplas, min-selections e max-selections. Leia event.target.value nos eventos nativos e use getValidationState() para consultar a validade.

Para regras de domínio, passe validator como propriedade JavaScript. Ele recebe string no modo simples ou string[] no modo múltiplo e retorna uma mensagem, null para sucesso ou uma Promise:

const select = document.querySelector('br-select');
select.validator = (value) => Array.isArray(value) && value.length === 0
  ? 'Selecione ao menos uma opção.'
  : null;

const valid = await select.validate();

Em React, Angular e Vue, use property binding (validator={fn}, [validator]="fn" ou :validator="fn"). A validação automática ocorre no change, nunca a cada tecla. Durante uma validação assíncrona, o campo expõe aria-busy="true", aceita validation-loading e emite brSelectValidationChange. O slot feedback ou o br-message padrão exibe a mensagem.

Regras de domínio podem ser aplicadas com setCustomValidity(). O reset restaura as opções iniciais sem emitir input ou change.

Acessibilidade

Forneça um rótulo visível com label. O componente expõe um combobox ligado a uma listbox e mantém aria-expanded, aria-activedescendant, aria-selected e aria-invalid sincronizados.

Enter ou Espaço abre a lista quando o campo não é editável. As setas percorrem as opções; Home e End vão para os extremos; Escape fecha a lista e devolve o foco ao campo; Tab fecha a lista e continua a navegação. No modo múltiplo, o estado de cada opção é anunciado separadamente.

Não adicione role ou tabindex ao host. Use disabled para bloquear interação e mantenha instruções e mensagens de erro em texto, associadas ao campo.

Eventos nativos

Elemento HTML de referência

br-select referencia <select>, mas combina campo de busca, listbox e um <select> oculto para sincronização. O host é o controle público.

Como ouvir os eventos

const select = document.querySelector('br-select');
select.addEventListener('change', () => console.log(select.value));

Eventos nativos suportados

Evento	Quando ocorre	Bubbles	Composed	Cancelable	Host	Observações
change	seleção é confirmada	Sim	Sim	Não	Sim	Imediatamente após input.
input	seleção muda	Sim	Sim	Não	Sim	Sintético após atualizar value.
teclado, click e foco	navegação/interação	conforme o tipo	Sim	conforme o tipo	Sim	O navegador ajusta o alvo externo para o host.

Eventos não suportados ou ainda não caracterizados

Eventos de edição no campo de busca não representam mudança de seleção e não vazam como input do select; use brSelectSearch quando precisar iniciar uma consulta. Seleção múltipla e todos os caminhos de teclado ainda aguardam matriz nos três engines.

Eventos customizados

brSelectSearch é emitido uma vez por edição quando filterable está ativo. Seu detail é { query: string } e serve para iniciar consultas remotas; ele não é emitido por escrita programática ou reset.

valueChange é um alias depreciado. Use input e change para acompanhar alterações de seleção.

Valor, frameworks e acessibilidade

Leia event.target.value; no modo múltiplo o valor é uma lista. FormData, required e métodos de validade pertencem ao host. Wrappers usam o par padrão. O teclado segue o padrão combobox/listbox documentado pelo componente.

Evidência de teste

src/shared/contracts/platform-contract.e2e.tsx cobre seleção simples real, ordem, target e caminho em Chromium headless; _tests/select.e2e.tsx cobre navegação e seleção múltipla.

Atributos nativos

O host FACE aceita name, form, required, disabled e multiple. autocomplete é encaminhado ao campo interno. Opções declarativas e por dados suportam label, value, selected e disabled; a opção oculta também recebe disabled.

size, autofocus e a API IDL de HTMLSelectElement não se aplicam à lista composta. O foco deve ser controlado pelo método show() ou pela interação normal do campo.

Documentações relacionadas

Consulte o guia geral de dados remotos para o fluxo completo de busca, loading, cancelamento, validação do payload e atualização de opções.

Também são relacionados:

• Input e Textarea, para consultas e validações assíncronas de valores textuais;
• Pagination, quando os resultados remotos são paginados;
• Formulários, para validação da seleção.

Dependências

Subcomponentes

• br-select-input
• br-select-list
• br-select-option

Usado por

• br-pagination

Depende de

• br-select-input
• br-select-list
• br-message

Gráfico

Migração de <br-select> (1.x → 2.x)

O br-select mantém rótulo, placeholder, seleção simples ou múltipla e opções por dados. Na 2.x, ele também participa de formulários, aceita opções declarativas e usa eventos nativos para mudanças de valor. Para opções fixas, prefira declarar br-select-option no slot; para resultados dinâmicos ou remotos, use setOptions().

Propriedades e eventos

API 1.x	API 2.x	Ação na migração
—	name, required, disabled	Use para integração com formulários.
label, placeholder	mesmos nomes	Mantenha.
multiple	multiple	Mantenha para permitir mais de uma seleção.
options	options, setOptions() ou br-select-option	Mantenha options para compatibilidade; prefira br-select-option para opções fixas e setOptions() para dados dinâmicos.
selectAllLabel, unselectAllLabel	mesmos nomes	Mantenha no modo múltiplo.
showSearchIcon	showSearchIcon	Mantenha quando o campo de busca precisar do ícone.
evento Vue change	input / change	Leia a seleção em event.target.value.

Exemplo

1.x:

<br-select :options="options" multiple @change="onChange"></br-select>

2.x:

<br-select name="orgaos" label="Órgãos" multiple required>
  <br-select-option value="saude" label="Saúde"></br-select-option>
  <br-select-option value="educacao" label="Educação"></br-select-option>
</br-select>

Ao atualizar opções remotamente, use search-mode="remote", trate brSelectSearch e aplique a resposta com setOptions(). Não monte br-select-input e br-select-list manualmente para esse fluxo: eles são subcomponentes internos do br-select. Debounce, cancelamento e erros da requisição continuam sob responsabilidade da aplicação.