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.
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.
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().
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
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
closedComponente mantido por compatibilidade; prefira a alternativa indicada na documentação.
Emitido quando a lista é fechada.
Use brSelectStateChange.
true
openedComponente mantido por compatibilidade; prefira a alternativa indicada na documentação.
Emitido quando a lista é aberta.
Use brSelectStateChange.
true
optionHoverComponente 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
valueChangeComponente mantido por compatibilidade; prefira a alternativa indicada na documentação.
Evento emitido quando o valor público do select é alterado.
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:
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 label visível. O componente expõe a semântica de seleção/combobox apropriada ao modo usado, mantém o foco no controle interno e sincroniza aria-expanded, aria-selected e aria-invalid quando aplicável.
A navegação deve funcionar com Tab, setas e Escape conforme o modo. Não adicione role ou tabindex conflitante no 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.
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.
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.
