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

Visão Geral

O br-datetime-picker é um campo para informar data, hora ou data e hora. A pessoa pode digitar ou escolher no calendário e nos controles de horário.

Escolha o tipo em mode: date, time ou datetime. Para início e fim, use selection-mode="range".

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

<br-datetime-picker mode="date" selection-mode="range" name="periodo"></br-datetime-picker>

Ler o valor

Onde	Formato
rangeValue	{ start, end } com Date
serialized-value e envio do formulário	2026-05-20 (data), 14:30 (hora), 2026-05-20T14:30:00-03:00 (data e hora), início/fim (intervalo)
value	Date (ou null)

Atribua valores do tipo Date pelo JavaScript (picker.value = new Date()), não por atributo. Para restringir datas, use min, max e disabled-dates.

Quando usar

• Formulários que pedem uma data, um horário ou um período.

Quando evitar

• Para só exibir uma data: use texto formatado.
• Para escolher várias datas soltas: o componente aceita uma data ou um intervalo.

O calendário (br-date-picker), os controles de horário (br-time-picker) e o campo de texto (br-datetime-input) são criados pelo próprio componente; não é preciso declará-los.

Consulte as diretrizes de design do GovBR.

Exemplos

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

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

disabled

Atributo	disabled
Descrição	Desabilita toda a interação do componente.
Tipo	boolean
Valor padrão	false

disabledDates

Atributo	disabled-dates
Descrição	Datas indisponíveis para seleção. Aceita Date[], string ou null. Datas inválidas são ignoradas. A comparação considera apenas o dia.
Tipo	DatetimePickerDisabledDate[] | string
Valor padrão	null

fixedRowCount

Atributo	fixed-row-count
Descrição	Mantém número fixo de linhas no calendário (6 semanas) quando true.
Tipo	boolean
Valor padrão	false

initialMoment

Atributo	initial-moment
Descrição	Valor inicial da seleção: 'now' | Date | string | null.
Tipo	Date | string
Valor padrão	null

locale

Atributo	locale
Descrição	Locale usado para formatação e rótulos.
Tipo	string
Valor padrão	'pt-BR'

max

Atributo	max
Descrição	Maior data/hora aceito (Date | string | null).
Tipo	Date | string
Valor padrão	null

min

Atributo	min
Descrição	Menor data/hora aceito (Date | string | null).
Tipo	Date | string
Valor padrão	null

mode

Atributo	mode
Descrição	Modo exibido pelo componente. Valores: date | time | datetime. Valores inválidos são normalizados para o padrão.
Tipo	"date" | "datetime" | "time"
Valor padrão	'datetime'

name

Atributo	name
Descrição	Nome do campo para submissão em formulários nativos.
Tipo	string
Valor padrão	''

placeholder

Atributo	placeholder
Descrição	Texto placeholder exibido no input.
Tipo	string
Valor padrão	''

rangeValue

Atributo	---
Descrição	Intervalo controlado quando selectionMode="range". Em datetime, preserva as datas e horários informados; término anterior ao início torna o controle inválido, sem reordenar ou avançar datas.
Tipo	{ start: Date; end: Date; }
Valor padrão	---

required

Atributo	required
Descrição	Indica se o campo é requerido para submissão do formulário.
Tipo	boolean
Valor padrão	false

selectionMode

Atributo	selection-mode
Descrição	Tipo de seleção: single ou range.
Tipo	"range" | "single"
Valor padrão	'single'

serializedValue

Atributo	serialized-value
Descrição	Representação serializada compatível com controles HTML. Formatos variam conforme mode. Em intervalos, usa início/fim.
Tipo	string
Valor padrão	---

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

Atributo	---
Descrição	Validador customizado (síncrono ou assíncrono) para a seleção. Recebe Date | DatetimePickerDateRange | null como valor.
Tipo	(value: Date | DatetimePickerDateRange) => string | Promise<string>
Valor padrão	---

value

Atributo	---
Descrição	Valor selecionado pelo usuário (Date | null). Pode ser controlado externamente e é refletido internamente.
Tipo	Date
Valor padrão	null

weekStartsOn

Atributo	week-starts-on
Descrição	Dia inicial da semana exibido no calendário (0 = Dom, 6 = Sáb).
Tipo	0 | 1 | 2 | 3 | 4 | 5 | 6
Valor padrão	0

Slots

Nome	Descrição
"feedback"	Mensagem de validação, normalmente um br-message.

Eventos

Evento	Descrição	Depreciação	Propagação
brDatetimePickerChange	Evento emitido quando a seleção muda. Payload (DatetimePickerChangeDetail): - mode: DatetimePickerMode — modo atual do componente (date | time | datetime). - selectionMode: DatetimePickerSelectionMode — single ou range. - value: Date | null | DatetimePickerDateRange — seleção atual (tipo depende de selectionMode). - serializedValue: string | undefined — representação serializada para integração com formulários.	---	true
brDatetimePickerValidationChange Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.	Emitido ao iniciar e concluir a validação customizada. Payload (FormValidationChangeDetail): - validating: boolean — indica se a validação está em execução. - valid: boolean | null — resultado da validação (null enquanto valida). - message: string | null — mensagem de validação associada.	---	true
dateStateChange	Evento público emitido quando a data de referência ou a seleção mudam. Payload (DatetimePickerDateState): - referenceDate: Date — data usada para navegação visual (mês/semana exibidos). - value: Date | null — valor selecionado atualmente.	---	true
valueChange Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.	Evento emitido quando o valor selecionado muda.	Use brDatetimePickerChange para receber a seleção completa e tipada. Payload (legacy): Date | null — valor selecionado.	true

Métodos

checkValidity

Descrição	Permite que consumidores acionem validação nativa do formulário via host.
Assinatura	checkValidity() => Promise<boolean>
Parâmetros	---

clear

Descrição	Limpa valor e intervalo selecionados. Remove seleção atual e restaura a referência de navegação para a data atual.
Assinatura	clear() => Promise<void>
Parâmetros	---

close

Descrição	Fecha o picker.
Assinatura	close() => Promise<void>
Parâmetros	---

focusInput

Descrição	Move o foco para o input nativo interno.
Assinatura	focusInput() => Promise<void>
Parâmetros	---

getRange

Descrição	Retorna o intervalo de datas selecionado quando em modo selectionMode="range".
Assinatura	getRange() => Promise<{ start: Date | null; end: Date | null; } | null>
Parâmetros	---

getValidationState

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

getValue

Descrição	Retorna uma cópia do valor selecionado atualmente.
Assinatura	getValue() => Promise<Date | null>
Parâmetros	---

isOpen

Descrição	Consulta se o picker está atualmente aberto.
Assinatura	isOpen() => Promise<boolean>
Parâmetros	---

open

Descrição	Abre o picker quando o componente estiver habilitado.
Assinatura	open() => Promise<void>
Parâmetros	---

reportValidity

Descrição	Permite exibir mensagens nativas de validação no host.
Assinatura	reportValidity() => Promise<boolean>
Parâmetros	---

resetToInitial

Descrição	Restaura o estado inicial atualmente registrado para reset.
Assinatura	resetToInitial() => Promise<void>
Parâmetros	---

setCustomValidity

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

setDisabledDates

Descrição	Define programaticamente as datas desabilitadas. Use quando scripts externos precisam fornecer uma lista tipada de datas a bloquear no calendário. Substitui a prop disabledDates para atualizações imperativas.
Assinatura	setDisabledDates(dates: DatetimePickerDisabledDate[] | null) => Promise<void>
Parâmetros	dates: Lista de datas (Date | string) a bloquear, ou null para limpar.

setRange

Descrição	Define um intervalo no modo atual e ativa selectionMode="range". Valida datas contra bloqueios e sincroniza estado visual e de formulário. Em datetime, mantém os limites informados e sinaliza intervalo inválido quando o término precede o início, sem ajustar datas automaticamente.
Assinatura	setRange(start: Date | string | null, end: Date | string | null) => Promise<void>
Parâmetros	start: Date | string | null — data inicial do intervalo. end: Date | string | null — data final do intervalo.

setValue

Descrição	Define o valor do componente de forma imperativa. Aceita Date, string compatível com o mode, ou null para limpar a seleção. Validação de datas desabilitadas é aplicada antes da atribuição.
Assinatura	setValue(value: Date | string | null) => Promise<void>
Parâmetros	value: Date | string | null — valor a aplicar; null limpa a seleção.

toggle

Descrição	Alterna o estado de abertura do picker.
Assinatura	toggle() => Promise<void>
Parâmetros	---

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

Descrição	Executa o validator customizado (se houver) e valida o controle. Emite eventos de início/conclusão da validação e atualiza mensagens internas.
Assinatura	validate() => Promise<boolean>
Parâmetros	---

CSS Shadow Parts

Nome	Descrição
"container"	Parte para o container base do seletor.
"feedback"	Contêiner da mensagem de validação.
"input-container"	Container base do campo de entrada interno.
"input-field"	Campo textual interno.
"input-icon"	Ícone de ação (calendário/relógio).
"panel"	Parte para o painel em forma de card que engloba o seletor.

Validação

Use required, min e max. Consulte a validade com checkValidity() e mostre a mensagem com reportValidity().

<br-datetime-picker mode="date" name="consulta" required min="2026-01-01" max="2026-12-31"></br-datetime-picker>

Intervalos

• O intervalo só é válido com início e fim preenchidos.
• Em mode="datetime", um fim anterior ao início deixa o campo inválido. O componente não inverte nem corrige as datas sozinho.
• Ao mudar só o horário de uma ponta, a data dela não muda, mesmo passando de 23:00 para 00:00.
• Em mode="time", intervalos que atravessam a meia-noite, como 22:00 - 06:00, são válidos.

Mensagem própria

Coloque a mensagem no slot feedback. Sem ele, o componente mostra a mensagem de validação em um br-message.

Regra personalizada

Atribua uma função a validator. Ela recebe a data (Date ou null) ou, em intervalos, { start, end }, e retorna uma mensagem para invalidar ou null para aceitar.

picker.validator = (data) => (data && data.getDay() === 0 ? 'Não atendemos aos domingos.' : null);
const valido = await picker.validate();

Veja também o guia de formulários.

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.

Acessibilidade

O campo interno recebe um nome acessível conforme o modo: data, horário ou data e hora. Apresente também um texto visível próximo ao componente para explicar o dado solicitado; o placeholder deve servir apenas como exemplo de formato ou valor.

Instruções e erros precisam ser textuais e associados ao controle, sem depender apenas de cor ou ícone.

Teclado

Contexto	Tecla	Ação
Campo	Alt+Seta para baixo ou F4	Abre ou fecha o painel.
Campo	Enter	Confirma o valor digitado.
Grade de dias	Enter ou Espaço	Seleciona a data em foco; datas bloqueadas são ignoradas.
Grade de dias	Home / End	Move o foco para o início ou o fim da semana.
Grade de dias	Page Up / Page Down	Move o foco para o mesmo dia do mês anterior ou seguinte.
Grade de dias	Setas	Move o foco um dia ou uma semana.
Grade de dias	Shift+Page Up / Shift+Page Down	Move o foco para o mesmo dia do ano anterior ou seguinte.
Hora e minuto	Enter	Confirma o valor digitado.
Hora e minuto	Seta para cima / para baixo	Incrementa ou decrementa o valor.
Painel	Escape	Fecha o painel e devolve o foco ao campo.
Painel	Tab / Shift+Tab	Percorre campo, navegação de mês e ano, grade e horários.

Datas bloqueadas continuam alcançáveis pelas setas para que o foco não fique preso, mas não podem ser selecionadas. Ao trocar de mês pelos botões, pelo seletor de mês ou pelo ano, o foco vai para a data selecionada, quando ela pertence ao mês exibido, ou para o mesmo dia do mês, limitado ao último dia disponível.

Leitores de tela

A grade usa os papéis grid, row, columnheader e gridcell. Cada dia informa a data por extenso e o estado de seleção ou de intervalo; o dia atual recebe aria-current="date" e os cabeçalhos das colunas têm o nome completo do dia da semana. A troca de mês é anunciada por uma região aria-live="polite".

Eventos nativos

Ouça input e change no br-datetime-picker. Os dois ocorrem quando a pessoa digita um valor válido ou escolhe uma data ou horário.

const picker = document.querySelector('br-datetime-picker');
picker.addEventListener('change', () => console.log(picker.value, picker.serializedValue));

Mudar o valor pelo código não emite input nem change. Para receber o valor já tipado, inclusive em intervalos, use brDatetimePickerChange. valueChange ainda funciona, mas está depreciado.

Atributos nativos

Aceita name, form, required, disabled e autofocus, como um campo de formulário. min e max limitam as datas, como em <input type="date">.

Dependências

Subcomponentes

• br-date-picker
• br-datetime-input
• br-time-picker

Depende de

• br-datetime-input
• br-date-picker
• br-time-picker
• br-divider
• br-card
• br-message

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>