Copiar página como Markdown para IA

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

O br-select permite escolher uma ou mais opções em uma lista suspensa expansível com suporte a busca e virtualização.

Declare as opções com <br-select-option> no slot padrão, ou forneça os dados dinamicamente com o método setOptions(). Para seleção múltipla, use multiple. Para habilitar busca por digitação, use filterable.

<br-select label="Estado" placeholder="Selecione um estado">
  <br-select-option value="df" label="Distrito Federal"></br-select-option>
  <br-select-option value="sp" label="São Paulo"></br-select-option>
  <br-select-option value="rj" label="Rio de Janeiro"></br-select-option>
</br-select>

Em formulários HTML, o componente integra-se nativamente via ElementInternals, enviando os valores selecionados no submit e validando campos obrigatórios com required.

Quando usar

Listas com 5 ou mais opções que ocupariam muito espaço visível se exibidas abertas.
Seleção que exige filtro ou busca por digitação.
Carregamento dinâmico ou remoto de opções a partir de uma API (search-mode="remote").

Quando evitar

Poucas opções fixas (2 a 4 opções): use br-radio ou br-radio-group.
Escolha simples de sim/não: use br-switch ou br-checkbox.

Consulte as diretrizes de design do GovBR.

Exemplos

Carregando preview…

Recolher controles e código

Como fornecer opções

Declare as opções do br-select inserindo elementos <br-select-option> no slot padrão. Em frameworks (React, Angular, Vue), renderize um <br-select-option> para cada item da lista:

<br-select label="Estado">
  <br-select-option value="df" label="Distrito Federal"></br-select-option>
  <br-select-option value="sp" label="São Paulo"></br-select-option>
</br-select>

Agrupamento de opções

Quando a lista reunir categorias diferentes, informe o atributo group em opções contíguas. O grupo organiza visualmente as opções e gera elementos <optgroup> para o formulário HTML:

<br-select label="Serviço público">
  <br-select-option group="Federais" value="inss" label="Meu INSS"></br-select-option>
  <br-select-option group="Federais" value="receita" label="Receita Federal"></br-select-option>
  <br-select-option group="Estaduais" value="detran" label="Detran"></br-select-option>
</br-select>

Mantenha juntas as opções do mesmo grupo.

Opções dinâmicas com `setOptions()`

Para carregar dados dinâmicos ou de APIs via JavaScript, use o método setOptions():

const select = document.querySelector('br-select');

await select.setOptions([
  { value: 'df', label: 'Distrito Federal' },
  { value: 'sp', label: 'São Paulo' },
]);

Nota de migração: a propriedade options foi mantida apenas para compatibilidade. Em código novo, utilize <br-select-option> no slot ou chame setOptions().

Busca remota

Use search-mode="remote" quando as opções vêm de uma API conforme o usuário digita. A resposta pode ser entregue de duas formas:

Forma	Como entregar	Quando usar
`br-select-option`	Renderize um `<br-select-option>` por resultado (`.map()`, `@for`, `v-for`).	Respostas limitadas (dezenas ou centenas de itens) em frameworks.
`setOptions()`	Chame `select.setOptions(itens)` com o array da resposta.	Respostas extensas ou JavaScript sem framework. Nenhuma opção vira elemento no DOM.

Escolha uma forma por select. Depois que setOptions() é chamado, a coleção imperativa passa a ser a fonte de dados e mudanças posteriores nos br-select-option não são sincronizadas.

O que o componente faz e o que fica com a aplicação

O br-select:

emite brSelectSearch com { query } a cada edição do campo, inclusive quando o termo é apagado ou limpo pelo botão "Limpar texto" (query vazio);
não emite busca ao apenas abrir a lista: nesse momento, exibe as opções que já tem;
exibe a resposta como ela chega, sem filtrá-la de novo pelo termo digitado;
mostra "Pesquisando…" enquanto loading estiver ativo e bloqueia a seleção;
mostra "Nenhum resultado encontrado" quando há termo e a resposta é vazia;
mantém a seleção (única ou múltipla com multiple) quando o item escolhido não aparece na resposta seguinte: valor, texto exibido e envio do formulário continuam corretos.

A aplicação é responsável por debounce, termo mínimo, cancelamento de requisições, tratamento de erros, autenticação e paginação da API.

Passos

Configure o campo. Declare search-mode="remote" e filterable, além de label e, em formulários, name.
Defina a lista inicial. É o que aparece ao abrir a lista antes de digitar: opções declaradas com br-select-option ou um setOptions() feito no carregamento da página. Pode ser uma lista curta de sugestões ou vazia.
Ouça brSelectSearch. Leia o termo em event.detail.query.
Aplique debounce. Como o evento sai a cada tecla, espere o usuário parar de digitar (cerca de 300 ms) antes de consultar a API. Prefira debounce a throttle: o throttle consulta no meio da digitação e, se não tiver disparo final, pode descartar o último termo.
Trate termo vazio e termo mínimo. Com query vazio, restaure a lista inicial sem consultar a API. Se a API exigir um mínimo de caracteres, não consulte abaixo dele.
Cancele a consulta anterior. Use AbortController (ou switchMap no RxJS) para que uma resposta atrasada não substitua a mais recente.
Sinalize o carregamento. Ative loading antes da consulta e desative ao final, inclusive em erro. Para trocar o "Pesquisando…" por texto, imagem ou HTML próprio, use o slot loading.
Entregue a resposta. Chame setOptions(itens) ou atualize a coleção que renderiza os br-select-option. Cada item precisa de value e label.
Informe erros. Desative loading, mantenha as opções atuais e exiba a falha fora da lista, por exemplo em um texto com role="status".

JavaScript com `setOptions()`

<br-select
  id="select-orgao"
  name="orgao"
  label="Órgão"
  placeholder="Digite para buscar"
  search-mode="remote"
  filterable
></br-select>
<p id="select-orgao-status" role="status"></p>

const select = document.querySelector('#select-orgao');
const status = document.querySelector('#select-orgao-status');
const sugestoes = [
  { value: 'inss', label: 'Instituto Nacional do Seguro Social' },
  { value: 'receita', label: 'Receita Federal' },
];
const MINIMO = 2;
let timer;
let controller;

await customElements.whenDefined('br-select');
await select.setOptions(sugestoes); // lista inicial

select.addEventListener('brSelectSearch', ({ detail: { query } }) => {
  clearTimeout(timer);
  controller?.abort();
  const termo = query.trim();

  if (termo.length < MINIMO) {
    select.loading = false;
    void select.setOptions(sugestoes);
    return;
  }

  timer = setTimeout(async () => {
    controller = new AbortController();
    select.loading = true;
    status.textContent = '';
    try {
      const resposta = await fetch(`/api/orgaos?q=${encodeURIComponent(termo)}`, {
        signal: controller.signal,
      });
      const itens = await resposta.json(); // [{ value, label }]
      await select.setOptions(itens);
    } catch (erro) {
      if (erro.name !== 'AbortError') status.textContent = 'Não foi possível consultar os órgãos.';
    } finally {
      if (!controller.signal.aborted) select.loading = false;
    }
  }, 300);
});

React com `br-select-option`

import { useEffect, useState } from 'react';
import { BrSelect, BrSelectOption } from '@govbr-ds/webcomponents-react';

export function SelectOrgao() {
  const [termo, setTermo] = useState('');
  const [itens, setItens] = useState(SUGESTOES);
  const [carregando, setCarregando] = useState(false);

  useEffect(() => {
    if (termo.trim().length < 2) {
      setItens(SUGESTOES);
      setCarregando(false);
      return;
    }

    const controller = new AbortController();
    const timer = setTimeout(async () => {
      setCarregando(true);
      try {
        const resposta = await fetch(`/api/orgaos?q=${encodeURIComponent(termo)}`, {
          signal: controller.signal,
        });
        setItens(await resposta.json());
      } catch (erro) {
        if (erro.name !== 'AbortError') console.error(erro);
      } finally {
        if (!controller.signal.aborted) setCarregando(false);
      }
    }, 300);

    return () => {
      clearTimeout(timer);
      controller.abort();
    };
  }, [termo]);

  return (
    <BrSelect
      name="orgao"
      label="Órgão"
      searchMode="remote"
      filterable
      loading={carregando}
      onBrSelectSearch={(event) => setTermo(event.detail.query)}
    >
      {itens.map((item) => (
        <BrSelectOption key={item.value} value={item.value} label={item.label} />
      ))}
    </BrSelect>
  );
}

Angular com `br-select-option`

import { Component, DestroyRef, inject } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { HttpClient } from '@angular/common/http';
import { Subject, catchError, debounceTime, distinctUntilChanged, finalize, map, of, switchMap } from 'rxjs';
import { BrSelect, BrSelectOption } from '@govbr-ds/webcomponents-angular/standalone';

interface Orgao {
  value: string;
  label: string;
}

@Component({
  selector: 'app-select-orgao',
  standalone: true,
  imports: [BrSelect, BrSelectOption],
  template: `
    <br-select
      name="orgao"
      label="Órgão"
      search-mode="remote"
      filterable
      [loading]="carregando"
      (brSelectSearch)="termos.next($event.detail.query)"
    >
      @for (item of itens; track item.value) {
        <br-select-option [value]="item.value" [label]="item.label"></br-select-option>
      }
    </br-select>
  `,
})
export class SelectOrgaoComponent {
  private readonly http = inject(HttpClient);
  readonly termos = new Subject<string>();
  itens: Orgao[] = SUGESTOES;
  carregando = false;

  constructor() {
    this.termos
      .pipe(
        map((termo) => termo.trim()),
        debounceTime(300),
        distinctUntilChanged(),
        // switchMap cancela a requisição anterior quando chega um novo termo.
        switchMap((termo) => {
          if (termo.length < 2) return of(SUGESTOES);
          this.carregando = true;
          return this.http.get<Orgao[]>('/api/orgaos', { params: { q: termo } }).pipe(
            catchError(() => of(this.itens)),
            finalize(() => (this.carregando = false)),
          );
        }),
        takeUntilDestroyed(inject(DestroyRef)),
      )
      .subscribe((itens) => (this.itens = itens));
  }
}

Vue com `br-select-option`

<script setup lang="ts">
import { ref, watch } from 'vue';
import { BrSelect, BrSelectOption } from '@govbr-ds/webcomponents-vue';

const termo = ref('');
const itens = ref(SUGESTOES);
const carregando = ref(false);

watch(termo, (valor, _anterior, onCleanup) => {
  if (valor.trim().length < 2) {
    itens.value = SUGESTOES;
    carregando.value = false;
    return;
  }

  const controller = new AbortController();
  const timer = setTimeout(async () => {
    carregando.value = true;
    try {
      const resposta = await fetch(`/api/orgaos?q=${encodeURIComponent(valor)}`, {
        signal: controller.signal,
      });
      itens.value = await resposta.json();
    } catch (erro) {
      if ((erro as Error).name !== 'AbortError') console.error(erro);
    } finally {
      if (!controller.signal.aborted) carregando.value = false;
    }
  }, 300);

  onCleanup(() => {
    clearTimeout(timer);
    controller.abort();
  });
});
</script>

<template>
  <BrSelect
    name="orgao"
    label="Órgão"
    search-mode="remote"
    filterable
    :loading="carregando"
    @brSelectSearch="(event) => (termo = event.detail.query)"
  >
    <BrSelectOption v-for="item in itens" :key="item.value" :value="item.value" :label="item.label" />
  </BrSelect>
</template>

Nos exemplos, SUGESTOES é a lista inicial e /api/orgaos representa a sua API, que deve devolver itens com value e label. Para experimentar o fluxo com 10.000 itens, use o preset "Busca remota" do Playground na documentação do componente.

Indicador de carregamento e botão de limpar

Para trocar o "Pesquisando…", use o slot loading com texto, imagem ou HTML:

<br-select label="Órgão" search-mode="remote" filterable loading>
  <span slot="loading">
    <img src="/assets/busca.gif" alt="" width="16" height="16" />
    Consultando órgãos…
  </span>
</br-select>

Durante a digitação, o botão "Limpar texto" aparece à esquerda da seta e apaga só o termo: a seleção é mantida, a lista continua aberta e uma nova busca é emitida com query vazio, que o passo 5 trata restaurando a lista inicial. Em campos com menos de 168px, o botão é omitido para preservar o valor e a seta.

Propriedades

autocomplete

Atributo	`autocomplete`
Descrição	Controla o autocomplete do campo de busca interno. Aceita `on` ou `off`; valores inválidos são ignorados.
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	`generateUniqueId('br-select')`

density

Atributo	`density`
Descrição	Define a densidade visual compartilhada pelo campo e pela lista de opções. Aceita `small`, `medium` ou `large`. Valores inválidos usam `medium`. A opção sintética de selecionar todos permanece com densidade `small`.
Tipo	`"large" \| "medium" \| "small"`
Valor padrão	`'medium'`

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`

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`

hideSearchIcon

Atributo	`hide-search-icon`
Descrição	Oculta a lupa mesmo quando `filterable` está ativo, sem desabilitar a busca. Tem precedência visual sobre `showSearchIcon` e não altera o comportamento padrão.
Tipo	`boolean`
Valor padrão	`false`

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.
Exemplo de uso	`'20rem'`
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 ou cabeçalho para o cálculo de virtual scroll. Deve ser um número finito positivo; valores inválidos usam 40.
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	O comportamento atual usa o fechamento padrão do select; mantenha esta prop apenas para compatibilidade com integrações legadas.
Descrição	Mantém a lista aberta depois de uma seleção.
Tipo	`boolean`
Valor padrão	`false`

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, a lista exibe o slot `loading` (padrão: "Pesquisando…") e 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. Deve ser um inteiro não negativo; valores inválidos usam 0.
Tipo	`number`
Valor padrão	`0`

minSelections

Atributo	`min-selections`
Descrição	Quantidade mínima de opções selecionadas no modo múltiplo. Deve ser um inteiro não negativo; valores inválidos usam 0.
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	Use `br-select-option` no slot padrão ou `setOptions()` para respostas dinâmicas/remotas.
Descrição	Fornece opções como array ou JSON, além das opções projetadas por slot. Use property binding para arrays em JavaScript e frameworks; no atributo HTML, informe uma string JSON válida. Na inicialização, opções no slot têm precedência quando existem. Depois de uma alteração nesta prop ou de uma chamada a `setOptions()`, a coleção imperativa passa a ser a fonte de dados. Não use em código novo. Declare `br-select-option` no slot padrão ou, para respostas dinâmicas/remotas, atualize a coleção com `setOptions()`.
Exemplo de uso	`<!-- Compatibilidade legada; prefira elementos br-select-option. --> <br-select options='[{"label":"Distrito Federal","value":"df"}]'></br-select>`
Tipo	`SelectOptionData[] \| string \| { group?: 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. Deve ser um inteiro não negativo; valores inválidos usam 1.
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` e exibe as opções recebidas sem filtrá-las de novo pelo termo digitado; a aplicação deve buscar, validar e aplicar a resposta com `setOptions()` ou re-renderizando os `br-select-option`. A seleção é preservada mesmo quando não aparece na resposta seguinte.
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 a lupa mesmo quando o select não é filtrável; selects com `filterable` já a exibem. A lupa é omitida quando o campo é estreito demais (menos de 128px) para comportar lupa, valor e seta.
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 Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.

Atributo	`validator`
Descrição	Validação síncrona ou assíncrona executada no método `validate()`. Recebe uma string no modo simples e um array de strings no modo múltiplo.
Exemplo de uso	`const select = document.querySelector('br-select'); select.validator = (value) => (Array.isArray(value) ? value.length > 0 : Boolean(value)) ? null : 'Selecione uma opção';`
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.
Exemplo de uso	`const select = document.querySelector('br-select'); select.multiple = true; select.value = ['df', 'sp'];`
Observações	Em modo múltiplo, o valor público é um array de strings.
Tipo	`string \| string[]`
Valor padrão	`''`

visibleItems

Atributo	`visible-items`
Descrição	Define quantas linhas visuais ficam visíveis na janela 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
`"default"`	Opções declaradas com elementos br-select-option.
`"feedback"`	Mensagem de validação, normalmente um br-message.
`"loading"`	Indicador exibido na lista enquanto `loading` está ativo. Padrão: spinner com o texto "Pesquisando…"; aceita texto, imagem ou qualquer HTML.
`"validation-loading"` Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.	Indicador exibido durante 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` Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.	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 Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.

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

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-clear"`	Botão de limpar o termo digitado durante a busca.
`"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-group"`	Cabeçalho visual de um grupo de opções.
`"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"` Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.	Área do indicador de validação assíncrona.

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 rótulo visível com label. O componente expõe um combobox ligado a uma listbox e mantém aria-expanded, aria-activedescendant, aria-selected e aria-invalid sincronizados.

Enter ou Espaço abre a lista quando o campo não é editável. As setas percorrem as opções; Home e End vão para os extremos; Escape fecha a lista e devolve o foco ao campo; Tab fecha a lista e continua a navegação. No modo múltiplo, o estado de cada opção é anunciado separadamente.

Não adicione role ou tabindex ao host. Use disabled para bloquear interação e mantenha instruções e mensagens de erro em texto, associadas ao campo.

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.

Sincronizações programáticas de value, selected ou disabled nas opções não representam uma nova interação: não emitem input/change nem restauram o foco. Após confirmar a seleção por clique ou teclado, o usuário pode sair do campo sem que a atualização das opções recupere o foco.

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

Atributos nativos

O host FACE aceita name, form, required, disabled e multiple. autocomplete é encaminhado ao campo interno. Opções declarativas e por dados suportam label, value, selected e disabled; a opção oculta também recebe disabled.

size, autofocus e a API IDL de HTMLSelectElement não se aplicam à lista composta. O foco deve ser controlado pelo método show() ou pela interação normal do campo.

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.

Dependências

Subcomponentes

Usado por

br-pagination

Depende de

Gráfico

Migração de `<br-select>` (1.x → 2.x)

O br-select mantém rótulo, placeholder, seleção simples ou múltipla e opções por dados. Na 2.x, ele também participa de formulários, aceita opções declarativas e usa eventos nativos para mudanças de valor. Para opções fixas e respostas remotas limitadas, prefira declarar br-select-option no slot; para coleções dinâmicas extensas, use setOptions().

Propriedades e eventos

API 1.x	API 2.x	Ação na migração
—	`name`, `required`, `disabled`	Use para integração com formulários.
`label`, `placeholder`	mesmos nomes	Mantenha.
`multiple`	`multiple`	Mantenha para permitir mais de uma seleção.
`options`	`options`, `setOptions()` ou `br-select-option`	Mantenha `options` para compatibilidade; prefira `br-select-option` para opções fixas ou respostas limitadas e `setOptions()` para coleções extensas.
`selectAllLabel`, `unselectAllLabel`	mesmos nomes	Mantenha no modo múltiplo.
`showSearchIcon`	`showSearchIcon`	Selects filtráveis já exibem a lupa; mantenha só para exibi-la em um select não filtrável.
evento Vue `change`	`input` / `change`	Leia a seleção em `event.target.value`.

Exemplo

1.x:

<br-select :options="options" multiple @change="onChange"></br-select>

2.x:

<br-select name="orgaos" label="Órgãos" multiple required>
  <br-select-option value="saude" label="Saúde"></br-select-option>
  <br-select-option value="educacao" label="Educação"></br-select-option>
</br-select>

Ao atualizar opções remotamente, use search-mode="remote", trate brSelectSearch e aplique a resposta com setOptions() ou re-renderizando os br-select-option com os resultados. Não monte br-select-input e br-select-list manualmente para esse fluxo: eles são subcomponentes internos do br-select. Debounce, cancelamento e erros da requisição continuam sob responsabilidade da aplicação.

Visão Geral​

Quando usar​

Quando evitar​

Como fornecer opções​

Agrupamento de opções​

Opções dinâmicas com setOptions()​

Busca remota​

O que o componente faz e o que fica com a aplicação​

Passos​

JavaScript com setOptions()​

React com br-select-option​

Angular com br-select-option​

Vue com br-select-option​

Indicador de carregamento e botão de limpar​

Propriedades​

autocomplete​

borderless​

customId​

density​

disabled​

filterable​

hideDividers​

hideSearchIcon​

inline​

inputWidth​

isInline Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.​

isMultiple Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.​

isOpen Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.​

itemHeight​

keepOpenOnSelect Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.​

label​

loading​

maxSelections​

minSelections​

multiple​

name​

open​

options Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.​

overscan​

placeholder​

required​

searchMode​

selectAllLabel​

showSearchIcon​

unselectAllLabel​

validator Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.​

value​

visibleItems​

Slots​

Eventos​

Métodos​

checkValidity​

clear Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.​

close​

disable​

enable​

getValidationState​

getValue Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.​

reportValidity​

setCustomValidity​

setFocus Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.​

setOption​

setOptions​

setValue Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.​

show​

toggleOpen​

validate Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.​

CSS Shadow Parts​

Validação​

Acessibilidade​

Eventos nativos​

Elemento HTML de referência​

Como ouvir os eventos​

Eventos nativos suportados​

Eventos não suportados ou ainda não caracterizados​

Eventos customizados​

Valor, frameworks e acessibilidade​

Evidência de teste​

Atributos nativos​

Documentações relacionadas​