Select Option

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.

Peça de Lego de Conteúdo

O br-select-option é a peça de encaixe do ecossistema Select e a API declarativa canônica para opções em código novo. Ele deve ser declarado dentro do slot padrão do componente principal <br-select>. Em frameworks, renderize um elemento para cada item da coleção.

O elemento declarado no slot é lido pelo br-select e convertido em dados. A lista virtualizada cria internamente os itens visuais para a janela atual; por isso, o br-select-option do slot é a fonte declarativa, não uma instância que precisa ser posicionada manualmente dentro de br-select-list.

Para opções dinâmicas ou remotas, use setOptions() no br-select. Evite misturar o slot com options ou setOptions() sem necessidade: após uma atualização imperativa, a coleção de dados passa a ser a fonte principal.

Consulte O Conceito Lego no Select para entender a composição e o relacionamento entre os componentes.

Visão Geral

Subcomponente que representa uma opção individual dentro de um br-select.

Papel na composição

• Define o valor de submissão (value) e o rótulo legível exibido para o usuário.
• Identifica opcionalmente o grupo visual e semântico ao qual a opção pertence.
• Exibe os estados de seleção (selected), desativação (disabled) e, no modo de seleção múltipla, o checkbox correspondente.
• Suporta marcação com destaque textual correspondente aos filtros de busca aplicados.

Regra de uso e relacionamento

Deve ser declarado no slot padrão do br-select (ou projetado pela lista). É a forma declarativa canônica de fornecer opções em código novo, inclusive quando um framework repete o elemento a partir de uma coleção. O br-select lê seus atributos e conteúdo, transforma-os em dados e entrega uma janela virtualizada à lista; portanto, o elemento declarado no slot é a fonte declarativa, não o item visual final da lista. Evite misturá-lo com a prop legada options ou com setOptions() sem necessidade, pois a coleção imperativa passa a ter precedência depois de ser utilizada. O item comunica suas mudanças de estado ao br-select pai, que por sua vez atualiza o valor geral do formulário e o resumo no campo de entrada. O br-select-option não deve ser utilizado fora do contexto de seleção.

Para a documentação completa de design, consulte o Design System do GovBR.

Propriedades

active

Atributo	active
Descrição	Marca a opção como ativa para navegação por teclado.
Tipo	boolean
Valor padrão	false

density

Atributo	density
Descrição	Define a densidade visual da opção e do item interno. Aceita small, medium ou large. Valores inválidos usam medium.
Tipo	"large" | "medium" | "small"
Valor padrão	'medium'

disabled

Atributo	disabled
Descrição	Desativa a interação da opção.
Tipo	boolean
Valor padrão	false

group

Atributo	group
Descrição	Nome do grupo visual e semântico da opção dentro do br-select. String vazia é tratada como ausência de grupo.
Tipo	string
Valor padrão	---

indeterminate

Atributo	indeterminate
Descrição	Indica o estado intermediário da opção.
Observações	Usado principalmente pela opção sintética de selecionar todos.
Tipo	boolean
Valor padrão	false

label

Atributo	label
Descrição	Rótulo textual exibido para a opção.
Tipo	string
Valor padrão	---

selected

Atributo	selected
Descrição	Indica se a opção está selecionada.
Tipo	boolean
Valor padrão	false

showCheckbox

Atributo	show-checkbox
Descrição	Exibe o checkbox de seleção ao lado do conteúdo.
Tipo	boolean
Valor padrão	false

value

Atributo	value
Descrição	Valor semântico associado à opção.
Tipo	string
Valor padrão	undefined

Slots

Nome	Descrição
"default"	Conteúdo ou rótulo visual da opção.

Eventos

Evento	Descrição	Depreciação	Propagação
brSelectOptionPropsChange Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.	Evento legado emitido quando as propriedades da opção são alteradas.	Use brSelectOptionStateChange.	true
brSelectOptionStateChange	Evento emitido quando o estado da opção muda.	---	true

Métodos

getItemHeight

Descrição	Retorna a altura efetiva da opção para cálculo de virtual scroll.
Assinatura	getItemHeight() => Promise<number>
Parâmetros	---

setFocus

Descrição	Encaminha o foco para o elemento interativo interno da opção.
Assinatura	setFocus() => Promise<void>
Parâmetros	---

setSelectedState

Descrição	Atualiza programaticamente o estado selecionado da opção.
Assinatura	setSelectedState(selected?: boolean) => Promise<void>
Parâmetros	selected: Estado desejado. Quando omitido, o valor atual é invertido.

CSS Shadow Parts

Nome	Descrição
"checkbox"	Checkbox exibido no modo múltiplo.
"option"	Item visual da opção.

Dependências

Componente pai

• br-select

Usado por

• br-pagination
• br-select-list

Depende de

• br-item
• br-checkbox

Gráfico

Migração para <br-select-option>

Na 1.x, as opções eram objetos passados a br-select; não existia um elemento público para cada opção. Na 2.x, os dados continuam aceitos, mas também podem ser declarados com br-select-option. Para opções fixas, a declaração no slot é a forma preferencial; para dados dinâmicos ou remotos, use setOptions() no br-select.

<br-select name="estado" label="Estado">
  <br-select-option value="df" label="Distrito Federal"></br-select-option>
  <br-select-option value="go" label="Goiás" disabled></br-select-option>
</br-select>

Use value como identificador enviado pelo formulário, label como texto da opção, selected para a seleção inicial e disabled para impedir interação. No modo múltiplo, o br-select controla showCheckbox e os demais estados visuais.

O br-select lê os elementos declarados no slot e cria internamente os itens visuais da lista virtualizada. Portanto, não posicione manualmente esses elementos dentro de br-select-list. Evite misturar o slot com options ou setOptions() sem necessidade; depois de uma atualização imperativa, a coleção de dados passa a ser a fonte principal.

Para acompanhar o valor do campo, ouça input ou change no br-select. brSelectOptionStateChange existe para a coordenação entre os subcomponentes e normalmente não precisa ser tratado pela aplicação.