Subcomponente de Composição
O br-select-option representa uma opção individual dentro do seletor. Deve ser declarado dentro do slot padrão do componente orquestrador <br-select>.
Visão Geral
Representa uma opção dentro do br-select. Use no slot padrão do componente.
Defina value para o valor de formulário e label para o texto exibido. Use selected para marcar a opção como selecionada inicialmente e disabled para desabilitá-la. Para agrupamento, utilize group.
<br-select-option value="df" label="Distrito Federal"></br-select-option>
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 ao ativar a opção por clique, teclado ou setSelectedState(). Fora de br-select, também informa alterações de selected e disabled. Dentro de br-select, a sincronização dessas props não é uma nova interação. | --- | 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
Usado por
Depende de
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.
