Date Picker

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 Modular

O br-date-picker é o subcomponente de calendário com grade visual de dias, meses e anos. É orquestrado automaticamente pelo componente principal <br-datetime-picker>, mas também pode ser utilizado de forma avulsa quando apenas um calendário estático for necessário.

Visão Geral

Calendário usado pelo br-datetime-picker. Também pode ser usado sozinho, quando a tela precisa de um calendário sempre visível.

Usado sozinho, ele não tem campo de texto nem participa de formulário: a aplicação lê a seleção e cuida da validação.

<br-date-picker id="agenda"></br-date-picker>

const calendario = document.querySelector('#agenda');
calendario.addEventListener('change', () => console.log(calendario.value));

• value: data selecionada (Date).
• referenceDate: mês exibido.
• disabledDates: datas que não podem ser escolhidas.
• selectionMode="range": seleção de intervalo, lida em rangeValue.

Para mudar o idioma, veja "Idiomas" na documentação do br-datetime-picker.

Propriedades

disabled

Atributo	disabled
Descrição	Desabilita a interação do calendário quando true.
Tipo	boolean
Valor padrão	false

disabledDates

Atributo	---
Descrição	Lista de datas indisponíveis para seleção no calendário.
Tipo	Date[]
Valor padrão	[]

fixedRowCount

Atributo	fixed-row-count
Descrição	Se true, o calendário sempre exibe 6 semanas (42 dias); caso contrário, adapta-se ao mês.
Tipo	boolean
Valor padrão	false

locale

Atributo	locale
Descrição	Locale usado para gerar nomes de meses e dias da semana.
Tipo	string
Valor padrão	'pt-BR'

rangeEnd

Atributo	---
Descrição	Data final selecionada quando o calendário opera no modo de intervalo.
Tipo	Date
Valor padrão	null

rangeStart

Atributo	---
Descrição	Data inicial selecionada quando o calendário opera no modo de intervalo.
Tipo	Date
Valor padrão	null

rangeValue

Atributo	---
Descrição	Intervalo controlado no modo range. Quando definido, mantém rangeStart e rangeEnd sincronizados.
Tipo	{ start: Date; end: Date; }
Valor padrão	---

referenceDate

Atributo	---
Descrição	Data usada como base visual para o mês atualmente exibido.
Tipo	Date
Valor padrão	new Date()

selectionMode

Atributo	selection-mode
Descrição	Define se a seleção ocorre por data única ou por intervalo.
Tipo	"range" | "single"
Valor padrão	'single'

value

Atributo	---
Descrição	Data atualmente selecionada pelo usuário, ou null quando não há seleção.
Tipo	Date
Valor padrão	null

weekStartsOn

Atributo	week-starts-on
Descrição	Índice do dia em que a semana começa na interface do calendário.
Tipo	0 | 1 | 2 | 3 | 4 | 5 | 6
Valor padrão	0

Eventos

Evento	Descrição	Depreciação	Propagação
dateStateChange	Emite o estado consolidado do componente quando há mudança de referência/seleção. Payload (DatetimePickerDateState):	---	true

CSS Shadow Parts

Nome	Descrição
"calendar"	Grade geral do calendário.
"container"	Parte para o container base do calendário.
"day"	Célula individual do dia no calendário.
"grid"	Grade de dias do mês.
"header"	Cabeçalho do calendário (contendo navegação e seleção de mês/ano).
"month-select"	Elemento de seleção do mês.
"weekday"	Rótulo individual do dia da semana.
"weekdays"	Container para os rótulos dos dias da semana.
"year-input"	Elemento de entrada do ano.

Idiomas

O componente vem com pt-BR. Para outro idioma:

1. Importe o idioma do date-fns.
2. Registre-o uma vez, no início da aplicação, com registerDatePickerLocale.
3. Use o mesmo código em locale.

import { enUS } from 'date-fns/locale/en-US';
import { registerDatePickerLocale } from '@govbr-ds/webcomponents';

registerDatePickerLocale('en-US', enUS);

<br-datetime-picker mode="date" locale="en-US"></br-datetime-picker>

O registro vale para todos os calendários da página. Um locale não registrado usa pt-BR.

Dependências

Componente pai

• br-datetime-picker

Usado por

• br-datetime-picker

Depende de

• br-button
• br-icon

Gráfico

Migração

O br-datetime-picker não existia na 1.x. Se a aplicação usava um campo de texto com máscara própria para datas:

1. Troque o campo por <br-datetime-picker mode="date"> (ou time, datetime).
2. Remova a máscara e a conversão de texto para data: o componente já faz isso.
3. Mantenha name para o valor seguir no formulário.
4. Ouça change para saber quando o valor mudou.

<br-datetime-picker mode="date" name="agendamento" required></br-datetime-picker>