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

Design System

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

Exemplo

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Compartilhar URL

Mudar fundo

Abrir no StackBlitz

Tela cheia

HTML

Controles

JS

CSS

Console

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Expandir controles e código

Busca remota

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Compartilhar URL

Mudar fundo

Abrir no StackBlitz

Tela cheia

HTML

Controles

JS

CSS

Console

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Expandir controles e código

Propriedades

autocomplete

Atributo	autocomplete
Descrição	Controla o autocomplete do campo de busca interno.
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	br-select-${selectId++}

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

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.
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 para o cálculo de virtual scroll.
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
Descrição	Mantém a lista aberta depois de uma seleção.
Tipo	boolean
Valor padrão	false
apenas para compatibilidade com integrações legadas.

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.
Tipo	number
Valor padrão	0

minSelections

Atributo	min-selections
Descrição	Quantidade mínima de opções selecionadas no modo múltiplo.
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	O formato de opções tipado atual é preferível; o formato legado permanece aceito.
Descrição	Opções fornecidas como array ou JSON, além das opções projetadas por slot.
Tipo	SelectOptionData[] | 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.
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

Atributo	validator
Descrição	Validação síncrona ou assíncrona executada no método validate().
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.
Tipo	string | string[]
Valor padrão	''

visibleItems

Atributo	visible-items
Descrição	Define quantas opções ficam visíveis na janela da lista.
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"	Indicador exibido durante validação assíncrona.

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-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"	Área do indicador de 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	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

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

Dependências

Subcomponentes

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

Usado por

• br-pagination

Depende de

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

Gráfico

Migração: Vue 1.x → Stencil 2.x

Propriedades

🟦 Propriedades renomeadas

Propriedade Vue	Propriedade Stencil	Descrição	Tipo	Padrão

🟥 Propriedades removidas

Propriedade	Descrição	Tipo	Padrão

🟩 Novas propriedades

Propriedade	Descrição	Tipo	Padrão

Eventos

🟦 Eventos renomeados

Evento Vue	Evento Stencil	Descrição

🟥 Eventos removidos

Propriedade	Descrição	Tipo	Padrão

🟩 Novos eventos

Evento	Descrição

Slots

🟦 Slots renomeados

Slot Vue	Slot Stencil	Descrição

🟥 Eventos removidos

Propriedade	Descrição	Tipo	Padrão

🟩 Slots criados

Slot	Descrição

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 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 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/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.

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.