Slider

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 componente br-slider é o controle deslizante do GovBR-DS, desenvolvido para permitir que a pessoa usuária selecione um valor numérico único ou uma faixa contínua de valores dentro de um intervalo delimitado.

Para que serve

• Seleção numérica fluida: Permite escolher valores deslizando uma alça (thumb) ao longo de uma trilha graduada, com atualização em tempo real.
• Modo simples e composto (faixa / range): Suporta uma única alça para valor individual ou duas alças para delimitação de intervalo mínimo e máximo (ex.: faixa de preços, período de anos).
• Entrada numérica sincronizada: Oferece campo de entrada numérico integrado opcional para digitação exata com sincronização bidirecional.
• Acessibilidade WAI-ARIA: Suporta controle total por teclado (setas direcionais, Page Up, Page Down, Home e End) e comunica valores atuais via aria-valuenow.

Quando utilizar

• Utilize quando:
  • O usuário precisar definir grandezas graduais onde a exploração intuitiva seja mais conveniente do que a digitação manual isolada.
  • Para filtros de faixa de valores (ex.: "De R$ 100 até R$ 500").
• Evite e prefira outro componente quando:
  • A precisão exata for estritamente necessária e o intervalo for arbitrário (prefira br-input numérico).
  • O valor for uma escolha categórica sem escala quantitativa (prefira br-select ou br-radio).

Estrutura e Slots

O br-slider possui estrutura rica com slots de referência, validação e customização da alça:

• ref-start: Slot para customização do rótulo de início da trilha.
• ref-end: Slot para customização do rótulo de fim da trilha.
• feedback: Slot para mensagens de validação (como br-message).
• thumb-icon: Slot para ícone personalizado na alça de controle em modo simples.
• thumb-start-icon: Slot para ícone na alça inicial em modo composto (range).
• thumb-end-icon: Slot para ícone na alça final em modo composto (range).

Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o Design System do GovBR.

Exemplo(s)

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Padrão

Compartilhar URL

Ativar movimento reduzido

Mudar fundo

Abrir no StackBlitz

Mais opções

Tela cheia

Carregando preview…

HTML

Controles do componente

Console: logs, eventos e erros

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Desfazer alteração

Refazer alteração

Comparar alterações

Formatar código

Resetar código para o estado inicial

Escolher formato para copiar

Propriedades

customId

Atributo	custom-id
Descrição	Identificador único. Caso não seja fornecido, um ID gerado automaticamente será usado.
Tipo	string
Valor padrão	generateUniqueId()

density

Atributo	density
Descrição	Densidade visual do componente. Altera exclusivamente as dimensões da alça de controle (thumb). Valores aceitos: 'small' (16px), 'medium' (20px - padrão), 'large' (24px). 'high' e 'low' são aceitos como sinônimos de 'small' e 'large'.
Tipo	"high" | "large" | "low" | "medium" | "small"
Valor padrão	'medium'

disabled

Atributo	disabled
Descrição	Desativa o slider, tornando-o não interativo.
Tipo	boolean
Valor padrão	false

gradient

Atributo	gradient
Descrição	Habilita gradiente de cores na trilha e sincroniza dinamicamente a cor da alça (thumb) e da etiqueta de valor (tooltip) com a cor correspondente à posição atual. Pode ser um booleano (usa gradiente padrão verde -> amarelo -> vermelho) ou uma string com cores/gradiente customizado (ex.: '#168821, #ffcd07, #e52207' ou 'linear-gradient(...)').
Tipo	boolean | string
Valor padrão	---

label

Atributo	label
Descrição	Texto descritivo associado ao slider para acessibilidade.
Tipo	string
Valor padrão	---

max

Atributo	max
Descrição	Valor máximo aceito pelo slider. Deve ser maior que min; valores inválidos usam 100 e relações inválidas usam min + 100.
Tipo	number
Valor padrão	100

min

Atributo	min
Descrição	Valor mínimo aceito pelo slider. Valores inválidos usam 0.
Tipo	number
Valor padrão	0

name

Atributo	name
Descrição	Nome do campo, utilizado em formulários nativos (<form>).
Tipo	string
Valor padrão	---

orientation

Atributo	orientation
Descrição	Orientação canônica. Quando informada, tem precedência sobre vertical; valores inválidos usam horizontal.
Tipo	"horizontal" | "vertical"
Valor padrão	---

range

Atributo	range
Descrição	Ativa o modo composto com duas alças para seleção de faixa.
Tipo	boolean
Valor padrão	false

rangeValue

Atributo	---
Descrição	Valor estruturado das duas alças no modo range. Deve conter start e end finitos; valores inválidos mantêm o último valor efetivo. Passe o objeto por property binding.
Exemplo de uso	const slider = document.querySelector('br-slider'); slider.range = true; slider.rangeValue = { start: 20, end: 80 };
Tipo	{ start: number; end: number; }
Valor padrão	---

showBounds

Atributo	show-bounds
Descrição	Exibe os limites nas referências inicial e final: min no início e max no fim (limites fixos), tanto em modo simples quanto em modo composto (range). O valor selecionado por cada alça é exibido na etiqueta (show-label), não nas referências. Quando ativo, sobrescreve o conteúdo dos slots ref-start e ref-end.
Tipo	boolean
Valor padrão	false

showInput

Atributo	show-input
Descrição	Exibe um br-input numérico sincronizado com a alça. No modo range, exibe um campo para o início e outro para o fim; na orientação horizontal ficam nas extremidades esquerda e direita, e na vertical ficam acima e abaixo da trilha. Quando ativo, a etiqueta de valor não é exibida.
Tipo	boolean
Valor padrão	false

showLabel

Atributo	show-label
Descrição	Exibe etiqueta com o valor atual acima da alça (horizontal) ou à esquerda (vertical). Ignorado quando show-input está ativo.
Tipo	boolean
Valor padrão	false

showTickLabels

Atributo	show-tick-labels
Descrição	Exibe os valores das marcações derivadas de min, max e step.
Tipo	boolean
Valor padrão	false

showTicks

Atributo	show-ticks
Descrição	Exibe gradações na trilha como pequenos espaços que indicam os steps disponíveis, forçando a alça de controle a saltar entre os valores predefinidos e impossibilitando a seleção de valores aleatórios.
Tipo	boolean
Valor padrão	false

step

Atributo	step
Descrição	Incremento aplicado a cada passo. Deve ser maior que 0; valores inválidos usam 1.
Tipo	number
Valor padrão	1

steps

Atributo	steps
Descrição	Lista de passos customizados para o slider. Cada passo pode definir value, label (texto exibido no tooltip e/ou abaixo da trilha) e icon (nome do ícone exibido abaixo da marcação do passo). Aceita array de objetos SliderStep[], array de strings string[], ou string JSON.
Exemplo de uso	<br-slider steps='[{"value": 1, "label": "Péssimo", "icon": "fa-solid:face-frown"}, {"value": 5, "label": "Excelente", "icon": "fa-solid:face-laugh"}]' ></br-slider> const slider = document.querySelector('br-slider'); slider.steps = [ { value: 1, label: 'Péssimo', icon: 'fa-solid:face-frown' }, { value: 5, label: 'Excelente', icon: 'fa-solid:face-laugh' }, ];
Tipo	SliderStep[] | string
Valor padrão	---

thumbEndIcon

Atributo	thumb-end-icon
Descrição	Nome do ícone da alça final (no modo range, alça à direita/superior).
Tipo	string
Valor padrão	---

thumbIcon

Atributo	thumb-icon
Descrição	Nome do ícone a ser exibido no interior da alça de controle (thumb). No modo range, aplica-se a ambas as alças caso thumbStartIcon ou thumbEndIcon não sejam especificados. Exemplo: 'fa-solid:arrows-left-right', 'fa-solid:circle'.
Tipo	string
Valor padrão	---

thumbStartIcon

Atributo	thumb-start-icon
Descrição	Nome do ícone da alça inicial (no modo range, alça à esquerda/inferior).
Tipo	string
Valor padrão	---

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

Atributo	---
Descrição	Regra síncrona ou assíncrona aplicada ao número ou intervalo selecionado. No modo range, recebe um objeto com start e end.
Exemplo de uso	const slider = document.querySelector('br-slider'); slider.validator = (value) => { const minimum = typeof value === 'number' ? value : value.start; return minimum >= 18 ? null : 'O valor inicial deve ser pelo menos 18'; };
Tipo	(value: number | SliderRangeValue) => string | Promise<string>
Valor padrão	---

value

Atributo	value
Descrição	Valor atual do slider (alça inicial no modo composto). Valores não finitos usam o limite mínimo; valores fora do intervalo são limitados.
Tipo	number
Valor padrão	0

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

Atributo	value-end
Depreciação	Use rangeValue.
Descrição	Valor da alça final no modo composto (range). Quando não fornecido em modo composto, assume o valor de max. Valores não finitos usam max, valores fora do intervalo são limitados.
Tipo	number
Valor padrão	NaN

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

Atributo	vertical
Depreciação	Use orientation.
Descrição	Exibe o slider na orientação vertical.
Tipo	boolean
Valor padrão	false

Slots

Nome	Descrição
"feedback"	Mensagem de validação, normalmente um br-message.
"ref-end"	Conteúdo exibido como referência final abaixo da trilha.
"ref-start"	Conteúdo exibido como referência inicial abaixo da trilha.
"thumb-end-icon"	Ícone customizado na alça final em modo composto.
"thumb-icon"	Ícone customizado na alça de controle em modo simples.
"thumb-start-icon"	Ícone customizado na alça inicial em modo composto.

Eventos

Evento	Descrição	Depreciação	Propagação
brDidChangeValue Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.	Disparado após alteração do valor da alça inicial.	Use o evento nativo input.	true
brDidChangeValueEnd Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.	Disparado após alteração do valor da alça final (modo composto).	Use o evento nativo input e leia event.target.rangeValue.	true
brSliderValidationChange Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.	Emitido ao iniciar e concluir a validação customizada.	---	true

Métodos

checkValidity

Descrição	Retorna se o slider atende às constraints configuradas.
Assinatura	checkValidity() => Promise<boolean>
Parâmetros	---

getValidationState

Descrição	Retorna um snapshot serializável da Constraint Validation API.
Assinatura	getValidationState() => Promise<FormValidationState>
Parâmetros	---

reportValidity

Descrição	Valida e solicita ao navegador a apresentação do erro atual.
Assinatura	reportValidity() => Promise<boolean>
Parâmetros	---

setCustomValidity

Descrição	Define ou limpa uma mensagem de validade customizada.
Assinatura	setCustomValidity(message: string) => Promise<void>
Parâmetros	message:

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

Descrição	Executa o validator do slider e retorna se o valor atual é válido.
Assinatura	validate() => Promise<boolean>
Parâmetros	---

CSS Shadow Parts

Nome	Descrição
"base"	Contêiner principal do slider.
"body"	Área que agrupa trilha e referências.
"feedback"	Contêiner da mensagem de validação.
"filled-track"	Trecho preenchido da trilha.
"input-wrapper"	Contêiner do campo numérico.
"input"	Campo numérico sincronizado com o slider.
"layout"	Contêiner de layout do slider.
"reference-bound"	Valor fixo de limite renderizado por show-bounds.
"reference-end"	Referência final.
"reference-start"	Referência inicial.
"references"	Contêiner das referências inicial e final.
"step"	Botão indicador de passo customizado individual.
"steps"	Contêiner das marcações de passos customizados.
"thumb-end"	Alça final do slider em modo composto.
"thumb-start"	Alça inicial do slider.
"thumb"	Alça de controle do slider.
"tick-label"	Etiqueta de uma marcação intermediária.
"tick-labels"	Contêiner das etiquetas das marcações.
"track-visual"	Trilha visual do slider.
"track"	Área interativa da trilha.
"value-label-arrow"	Seta da etiqueta de valor.
"value-label"	Etiqueta com o valor da alça.

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

Defina min, max e step para validar o valor escalar. Em intervalos, use range-value com { start, end }; o intervalo deve estar dentro dos limites e ordenado.

input representa alteração contínua e change o commit. Regras de domínio podem usar setCustomValidity(); consulte os flags por getValidationState().

A mensagem é renderizada como br-message quando não existe feedback. Use o slot feedback para fornecer o conteúdo e manter a referência ARIA sem mensagens duplicadas.

Para regras de domínio síncronas ou assíncronas, use validator. Ele recebe o número selecionado ou { start, end } no modo range. A validação também pode ser acionada por await slider.validate() e emite brSliderValidationChange.

Acessibilidade

Forneça label e limites que expliquem a escala. As setas alteram o valor em um step, Home e End vão aos limites e Page Up e Page Down avançam em passos maiores. No modo range, cada alça recebe um nome com “início” ou “fim” e não pode ultrapassar a outra.

O componente expõe valor, mínimo, máximo e orientação por ARIA. Não use somente cor, posição ou tooltip para explicar o valor; quando a escala não for evidente, mostre referências textuais.

Eventos nativos

Elemento HTML de referência

A referência é <input type="range">. br-slider usa thumbs com role="slider"; no modo range combina dois valores.

Como ouvir os eventos

const slider = document.querySelector('br-slider');
slider.addEventListener('input', () => console.log(slider.value));
slider.addEventListener('change', () => console.log('commit', slider.value));

Eventos nativos suportados

Evento	Quando ocorre	Bubbles	Composed	Cancelable	Host	Observações
change	interação é confirmada	Sim	Sim	Não	Sim	No teclado acompanha cada passo confirmado.
input	valor muda durante interação	Sim	Sim	Não	Sim	Contínuo no ponteiro; uma vez por passo no teclado.
teclado e foco	thumb recebe comando/foco	conforme o tipo	Sim	conforme o tipo	Sim	Setas, Home, End e Page Up/Down.

Eventos não suportados ou ainda não caracterizados

O modo range não possui equivalente HTML único; use rangeValue. Ponteiro e pointer cancel ainda aguardam matriz completa nos três engines.

Eventos customizados

brDidChangeValue e brDidChangeValueEnd são aliases depreciados.

Valor, frameworks e acessibilidade

Leia value e, no intervalo, rangeValue/valueEnd. FormData e validade pertencem ao host. Wrappers usam input/change. Cada thumb expõe nome, limites, orientação e valor por ARIA.

Evidência de teste

src/shared/contracts/platform-contract.e2e.tsx cobre teclado real, ordem, target e caminho em Chromium headless; _tests/slider.e2e.tsx cobre teclas e modo range.

Atributos nativos

O host FACE aceita name, form, disabled e autofocus. min, max, step, value e, no modo range, value-end/range-value definem os thumbs e o valor submetido.

list, stepUp() e stepDown() não são copiados de <input type="range">: ticks, dois thumbs e mudanças de valor pertencem ao contrato próprio do slider.

Dependências

Depende de

• br-icon
• br-input
• br-message

Gráfico

Migração para <br-slider>

O br-slider não existia na linha 1.x. Na 2.x, ele oferece seleção numérica simples ou por intervalo e participa de formulários.

Uso básico

<br-slider name="volume" label="Volume" min="0" max="100" step="5" value="50"></br-slider>

• use min, max e step para definir os valores permitidos;
• leia value nos eventos input e change;
• ative range e use rangeValue para trabalhar com duas alças;
• use orientation="vertical" em vez do alias legado vertical;
• use show-label, show-input, show-ticks e show-bounds somente quando essas referências ajudarem a tarefa.

No modo de intervalo, atribua { start, end } à propriedade JavaScript rangeValue. O atributo legado value-end continua disponível por compatibilidade, mas não deve ser usado em novos códigos.