Select List

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.

Subcomponente de Composição

O br-select-list é o subcomponente responsável pela renderização da lista suspensa virtualizada de opções. É orquestrado internamente pelo componente principal <br-select>.

Visão Geral

Painel suspenso com lista virtualizada do br-select.

É gerenciado internamente pelo br-select para exibir as opções com alta performance, mesmo em listas grandes. Não é necessário utilizá-lo de forma avulsa.

Propriedades

activeOptionIndex

Atributo	active-option-index
Descrição	Índice da opção atualmente ativa para navegação por teclado. Deve ser um inteiro maior ou igual a -1; valores inválidos usam -1.
Observações	Esse valor é usado para refletir visualmente o foco lógico da lista.
Tipo	number
Valor padrão	-1

density

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

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

itemHeight

Atributo	item-height
Descrição	Informa a altura base usada no cálculo de posicionamento das opções. Deve ser um número finito positivo; valores inválidos usam 56.
Tipo	number
Valor padrão	56

loading

Atributo	loading
Descrição	Indica que os resultados remotos estão sendo carregados.
Tipo	boolean
Valor padrão	false

options

Atributo	---
Descrição	Coleção de opções exibidas pela lista.
Tipo	SelectOptionData[]
Valor padrão	[]

overscan

Atributo	overscan
Descrição	Define quantas opções extras são renderizadas fora da viewport quando o virtual scroll está ativo. Deve ser um inteiro não negativo; valores inválidos usam 0.
Tipo	number
Valor padrão	0

searchMode

Atributo	search-mode
Descrição	Define se searchTerm filtra as opções (local) ou se as opções já chegam filtradas pelo servidor (remote). Nos dois modos, um termo sem resultados exibe a mensagem de lista vazia. Valores inválidos usam local.
Tipo	"local" | "remote"
Valor padrão	'local'

searchTerm

Atributo	search-term
Descrição	Termo usado para filtrar opções por rótulo ou valor.
Tipo	string
Valor padrão	''

selectAllLabel

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

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	SelectList.DESELECT_ALL_LABEL

visibleItems

Atributo	visible-items
Descrição	Define quantas linhas visuais permanecem visíveis na viewport 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
"loading"	Indicador exibido enquanto resultados remotos são carregados. Padrão: spinner com o texto "Pesquisando…".

Métodos

close

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

focusOption

Descrição	Garante visibilidade e foco para uma opção específica.
Assinatura	focusOption(index: number) => Promise<boolean>
Parâmetros	index: Índice lógico da opção alvo.

getOptions

Descrição	Retorna uma cópia das opções atualmente controladas pela lista.
Assinatura	getOptions() => Promise<SelectOptionData[]>
Parâmetros	---

open

Descrição	Abre a lista e agenda a medição das opções quando necessário.
Assinatura	open() => Promise<void>
Parâmetros	---

revealOption

Descrição	Torna o item ativo visível sem retirar o foco do campo.
Assinatura	revealOption(index: number) => Promise<boolean>
Parâmetros	index:

scrollFirstSelectedOptionToTop

Descrição	Posiciona no topo a primeira opção selecionada na ordem visual da lista. A opção auxiliar de selecionar tudo não participa dessa escolha.
Assinatura	scrollFirstSelectedOptionToTop() => Promise<boolean>
Parâmetros	---

scrollOptionToTop

Descrição	Posiciona uma opção no topo da viewport virtual, respeitando o limite final da lista.
Assinatura	scrollOptionToTop(index: number) => Promise<boolean>
Parâmetros	index: Índice lógico da opção alvo.

setMultiple

Descrição	Alterna a lista entre modo simples e múltiplo.
Assinatura	setMultiple(isMultiple: boolean) => Promise<void>
Parâmetros	isMultiple: Define se a lista deve operar em seleção múltipla.

setOption

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

setOptionSelected

Descrição	Aciona a seleção programática de uma opção específica.
Assinatura	setOptionSelected(index: number, selected?: boolean) => Promise<boolean>
Parâmetros	index: Índice lógico da opção alvo. selected: Estado desejado para a opção. Quando omitido, a própria opção alterna o valor atual.

setOptions

Descrição	Substitui todas as opções renderizadas pela lista.
Assinatura	setOptions(options: SelectOptionData[]) => Promise<void>
Parâmetros	options: Nova coleção de opções normalizadas.

setSearchTerm

Descrição	Atualiza o termo de busca e reinicia a janela virtual no topo.
Assinatura	setSearchTerm(term: string) => Promise<void>
Parâmetros	term: Termo que deve filtrar a coleção. String vazia restaura todas as opções.

CSS Shadow Parts

Nome	Descrição
"empty-option"
"list"	Contêiner visual da lista virtualizada.
"loading"	Área do indicador de carregamento.
"option-divider"
"option-group"	Cabeçalho visual de um grupo de opções.

Dependências

Componente pai

• br-select

Usado por

• br-select

Depende de

• br-select-option
• br-divider
• br-loading

Gráfico

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

Na 1.x, listas simples e múltiplas eram implementadas separadamente por br-select-simple-list e br-select-multiple-list. Na 2.x, br-select-list reúne os dois modos e é coordenado por br-select.

Não troque os elementos antigos diretamente pelo novo subcomponente. Migre a configuração para o pai:

<br-select label="Serviços" multiple>
  <br-select-option value="um" label="Serviço um"></br-select-option>
  <br-select-option value="dois" label="Serviço dois"></br-select-option>
</br-select>

Em composições avançadas, a prop options do br-select-list define a coleção normalizada, setMultiple() alterna o modo, searchTerm filtra a lista e visibleItems, itemHeight e overscan ajustam a janela virtual. Essa prop é um contrato interno da lista e não deve ser confundida com a prop options do br-select. No uso normal, informe opções fixas com br-select-option no slot do pai ou use setOptions() no br-select para dados dinâmicos/remotos. A aplicação só deve coordenar abertura, foco e seleção manualmente quando realmente montar uma composição própria.