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

Design System

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

Exemplo(s)

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Compartilhar URL

Mudar fundo

Abrir no StackBlitz

Tela cheia

HTML

Controles

JS

CSS

Console

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Formatar código

Resetar código para o estado inicial

Copiar para a área de transferência

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 da alça de controle. small = 16px (desktop compacto), medium = 20px (desktop padrão), large = 24px (mobile).
Tipo	"large" | "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

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.
Tipo	number
Valor padrão	100

min

Atributo	min
Descrição	Valor mínimo aceito pelo slider.
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.
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.
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 campo de entrada numérico sincronizado com a alça. 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.
Tipo	number
Valor padrão	1

validator

Atributo	---
Descrição	Regra síncrona ou assíncrona aplicada ao número ou intervalo selecionado.
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).
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.
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.

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	Emitido ao iniciar e concluir a validação customizada.	---	true

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

Dependências

Depende de

• br-message

Gráfico

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 compreensíveis. O slider segue o padrão APG: setas alteram o valor, Home/End vão aos limites e Page Up/Page Down avançam por páginas quando suportado.

O valor atual deve permanecer determinável por tecnologia assistiva. Não use somente uma cor ou tooltip para comunicar o valor.

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/platform-contract.e2e.tsx cobre teclado real, ordem, target e caminho em Chromium headless; _tests/slider.e2e.tsx cobre teclas e modo range.