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.

Peça de Lego Interna

O br-select-list é um subcomponente interno do ecossistema Select, responsável pela lista suspensa virtualizada. O br-select injeta nele uma coleção de dados pela prop options; a lista cria internamente apenas a janela visível de br-select-option. Essa prop da lista é um contrato de composição e não é a API de opções do br-select.

Na quase totalidade das aplicações, utilize diretamente o componente principal <br-select>, que já orquestra a lista, o campo de acionamento, a seleção, o foco, o ARIA e o formulário. Para fornecer opções, use br-select-option no slot para conteúdo fixo ou setOptions() para dados dinâmicos/remotos.

Consulte O Conceito Lego no Select para entender os papéis e quando montar componentes separadamente.

Visão Geral

Subcomponente de lista virtualizada de opções, projetado para renderizar o conjunto de escolhas do br-select.

Papel na composição

• Atua como o painel suspenso (popup listbox) que exibe os itens br-select-option.
• Implementa virtualização de itens para oferecer alta performance mesmo em listas extensas com centenas ou milhares de opções.
• Mantém o posicionamento flutuante e controla a rolagem de visualização do item ativo em navegação por teclado.

Regra de uso e relacionamento

Gerenciado exclusivamente pelo componente pai br-select, que injeta a coleção normalizada em options, controla o estado de exibição (aberto/fechado), a seleção múltipla e o índice ativo. A prop options desta lista é um contrato interno de composição e não substitui a API de opções do br-select. A lista cria internamente elementos br-select-option para a janela virtualizada, em vez de exibir diretamente os filhos declarados no slot do pai. Não utilize br-select-list como controle autônomo de formulário, pois ele não possui associação nativa com formulários (formAssociated) nem campo de acionamento próprio.

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

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 e do indicador de carregamento. Aceita small, medium ou large. Valores inválidos usam medium.
Tipo	"large" | "medium" | "small"
Valor padrão	'medium'

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

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.

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

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