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 é o controle completo do GovBR-DS para digitação e seleção visual de datas e horários. Orquestra o campo textual e os seletores internos, consolidando valor, validação e integração com formulários HTML.

Para que serve

• Oferece os modos date, time e datetime, com seleção única (single) ou de intervalo (range).
• Combina edição textual com máscara, calendário e ajuste de horas e minutos conforme o modo escolhido.
• Centraliza restrições de seleção, validação e submissão do valor por meio de formAssociated.

Quando utilizar

• Utilize quando o formulário precisar de um controle completo de data ou horário com digitação e seleção visual.
• Utilize para períodos com início e fim, inclusive com horários nos modos time e datetime.
• Evite quando precisar apenas apresentar uma data: prefira texto formatado.
• Para um calendário permanentemente visível sem o campo textual, considere br-date-picker; a aplicação assume a integração com o restante do formulário.
• A seleção não oferece uma coleção de datas independentes: use single para um valor ou range para um intervalo.

Composição e Subcomponentes

Componente	Papel	Regra de uso
br-date-picker	Calendário para navegação e seleção de data única ou intervalo.	Criado pelo pai nos modos date e datetime; pode ser usado isoladamente como calendário embutido.
br-datetime-input	Campo textual com máscara, interpretação da entrada e ação de abertura do painel.	Instanciado internamente pelo pai; não deve ser fornecido em slot.
br-datetime-picker	Orquestrador do valor consolidado, validação, formulário e abertura do painel.	Declare este controle no template para obter a composição completa.
br-time-picker	Controles de hora e minuto.	Criado pelo pai nos modos time e datetime, com uma instância por limite quando a seleção é range.

O slot feedback recebe conteúdo declarativo de validação, normalmente um br-message; não substitui os seletores internos.

Como os subcomponentes se relacionam

O pai fornece valores e configurações aos filhos por propriedades e consolida suas alterações por eventos DOM. O campo textual solicita a abertura do painel; o calendário e os controles de horário atualizam a seleção compartilhada, sem coordenar diretamente uns aos outros.

referenceDate representa a referência de navegação visual, distinta da seleção efetiva. O orquestrador mantém o campo textual, os seletores e o valor de formulário sincronizados. A aplicação consome o valor e os eventos do pai, incluindo brDatetimePickerChange para a seleção completa e tipada.

O uso isolado dos filhos exige que a aplicação assuma a coordenação de estado, validação e formulário; eles não herdam a associação nativa ao formulário do br-datetime-picker.

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

PadrãoIntervalo de datasSomente horário

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 público canônico 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

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-datetime-picker.

Use required, min e max para datas/horários escalares. Em intervalos, range-value deve conter início e fim completos, válidos e ordenados. input acompanha edição e change representa o commit.

Em mode="datetime", início e término representam datas e horários completos. Se o término for anterior ao início, o controle fica inválido com a mensagem “A data e hora de término devem ser iguais ou posteriores às de início.”. Datas iguais com horários iguais são aceitas.

setRange(), a prop rangeValue e os seletores preservam os limites informados, sem inverter as pontas ou avançar automaticamente a data final. Ao editar um horário, a data daquele limite permanece inalterada, inclusive ao passar de 23:00 para 00:00. Corrija explicitamente a data ou o horário para validar o intervalo. Na entrada textual, o texto inválido é preservado e a última seleção confirmada não é substituída.

Em mode="time", intervalos noturnos como 22:00 - 06:00 continuam válidos. Em mode="date", a entrada textual mantém a reordenação das pontas.

Use setCustomValidity() para regras de agenda da aplicação e getValidationState() para integrar Constraint Validation com seu framework.

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.

Para regras de domínio síncronas ou assíncronas, use validator. Ele recebe Date | null no modo simples ou { start, end } no modo de intervalo. A validação também pode ser acionada por await picker.validate() e emite brDatetimePickerValidationChange.

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.

Tab percorre o campo e os controles disponíveis. No calendário, as setas mudam a data em foco, Enter ou Espaço confirma a escolha e Escape fecha o painel e devolve o foco ao campo. Instruções e erros precisam ser textuais e associados ao controle, sem depender apenas de cor ou ícone.

Eventos nativos

Elemento HTML de referência

br-datetime-picker referencia inputs de data/hora, mas combina campo textual, calendário e seletor de horário. O host é o controle público.

Como ouvir os eventos

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

Eventos nativos suportados

Evento	Quando ocorre	Bubbles	Composed	Cancelable	Host	Observações
change	alteração válida é confirmada	Sim	Sim	Não	Sim	Imediatamente depois de input.
input	edição/seleção válida altera o valor	Sim	Sim	Não	Sim	Após sincronizar value.
teclado, click e foco	interação com campo/pickers	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

O componente não promete todos os eventos específicos de <input type="date">, pois a interface é composta. Digitação, calendário, hora e intervalo ainda precisam de uma matriz única de ordem/duplicação nos três engines.

Eventos customizados

valueChange é alias depreciado. Eventos dateStateChange dos subcomponentes são protocolo interno e não substituem input/change no host.

Valor, frameworks e acessibilidade

Leia value, serializedValue, valueAsDate e, no modo intervalo, rangeValue. FormData e validade pertencem ao host. Wrappers usam eventos padrão. Foco e teclado dependem do modo e dos controles internos documentados.

Evidência de teste

src/shared/contracts/platform-contract.e2e.tsx cobre API comum, FormData e constraints em Chromium; _tests/datetime-picker.e2e.tsx cobre silêncio programático e emissão após interação. A matriz completa permanece pendente.

Atributos nativos

O host FACE aceita name, form, required, disabled e autofocus. mode, min, max, locale, selection-mode e os valores serializados configuram o calendário e o horário compostos.

APIs IDL de picker e step de <input> não são duplicadas: abertura e seleção pertencem aos componentes de data e hora. form e autofocus permanecem atributos da plataforma.

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 para <br-datetime-picker>

O br-datetime-picker não existia na linha 1.x. Na 2.x, use este componente como ponto de entrada para campos de data, hora ou data e hora. Ele reúne o campo textual, o calendário e o seletor de horário em um único controle associado a formulário.

Configuração básica

• escolha mode="date", mode="time" ou mode="datetime";
• use value como propriedade JavaScript quando precisar trabalhar com Date;
• use serialized-value para os formatos textuais aceitos pelo componente;
• informe name para incluir o valor no FormData;
• use input durante a edição e change quando a alteração for confirmada.

<br-datetime-picker
  mode="date"
  name="agendamento"
  placeholder="Selecione a data"
  required
></br-datetime-picker>

Para selecionar um intervalo, combine mode="date" com selection-mode="range" e leia rangeValue. Aplicações que usavam um campo de texto comum na 1.x devem remover máscaras e parsing duplicados antes de adotar o componente.