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 componente br-datetime-picker é o orquestrador completo do GovBR-DS para seleção e digitação de datas, horários ou intervalos combinados. Ele integra-se nativamente a formulários HTML via formAssociated e oferece suporte WAI-ARIA para diálogos e calendários.

Para que serve

• Seleção completa de data e horário: Reúne em um único controle o campo de entrada com máscara formatada (br-datetime-input), o calendário de seleção de datas (br-date-picker) e o seletor de horários (br-time-picker).
• Múltiplos modos operacionais: Suporta data simples, intervalo de datas (range), apenas hora (time), data e hora combinadas (datetime) e datas múltiplas.
• Validação e formulários nativos: Valida datas mínimas (min), máximas (max), formatos permitidos e comunica valores estruturados diretamente ao formulário pai.

Quando utilizar

• Utilize quando:
  • O formulário exigir preenchimento de datas ou horários onde tanto a digitação manual rápida quanto a exploração visual no calendário agreguem valor à experiência.
  • For necessário selecionar um período com data de início e fim.
• Evite e prefira outro componente quando:
  • A data for estritamente de nascimento ou emissão de documento onde a pessoa usuária sabe os dígitos de cor e prefere digitar apenas números (prefira br-input com máscara numérica).

Composição e Subcomponentes

Subcomponente	Papel	Regra de uso
br-date-picker	Calendário de datas. Painel visual com grade de dias, meses e anos.	Coordenado pelo pai; use avulso se precisar de calendário estático embutido.
br-datetime-input	Campo com máscara. Exibe o valor formatado e permite digitação manual.	Coordenado automaticamente pelo pai; use avulso apenas em composições customizadas.
br-datetime-picker	Orquestrador principal. Gerencia valor consolidado, validação, abertura do popup e sincronização entre input e calendário.	Deve ser o único controle declarado no template da aplicação na quase totalidade dos casos.
br-time-picker	Seletor de horário. Controle de escolha de horas e minutos.	Coordenado pelo pai; use avulso se precisar apenas de seletor de hora sem data.

Como os subcomponentes se relacionam

O br-datetime-picker funciona como o modelo pronto: ele instancia e sincroniza internamente o campo textual (br-datetime-input) e os seletores visuais suspensos (br-date-picker e/ou br-time-picker). A aplicação consome os eventos unificados emitidos diretamente pelo orquestrador pai (change, input).

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ã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. Quando true, impede abrir o picker, alterar valores e navegar entre datas/horários.
Tipo	boolean
Valor padrão	false

disabledDates

Atributo	disabled-dates
Descrição	Define um conjunto de datas indisponíveis para seleção. Aceita uma lista de Date e/ou strings analisáveis, ou uma string com datas separadas por espaço em branco. Datas inválidas são ignoradas com warning. A comparação considera apenas o dia (ano/mês/dia), ignorando hora.
Exemplo de uso	<br-datetime-picker mode="date" disabled-dates="2026-09-07 2026-09-08"></br-datetime-picker> const picker = document.querySelector('br-datetime-picker'); picker.disabledDates = [new Date(2026, 8, 7), '2026-09-08'];
Tipo	DatetimePickerDisabledDate[] | string
Valor padrão	null

fixedRowCount

Atributo	fixed-row-count
Descrição	Define se o calendário deve manter um número fixo de linhas (6 semanas = 42 dias) ou variar conforme o mês. Quando true, o calendário sempre exibe 6 semanas completas. Quando false, o calendário adapta-se ao mês, exibindo apenas as semanas necessárias.
Tipo	boolean
Valor padrão	false

initialMoment

Atributo	initial-moment
Descrição	Define a seleção inicial do componente. Aceita: - 'now': seleciona o momento atual. - Date ou string: seleciona uma data arbitrária. - null: inicia sem seleção. Reativo em runtime: mudanças na prop atualizam estado e subcomponentes.
Exemplo de uso	<br-datetime-picker initial-moment="now"></br-datetime-picker>
Tipo	Date | string
Valor padrão	null

locale

Atributo	locale
Descrição	Define o locale usado pelos subcomponentes para formatar datas e rótulos.
Tipo	string
Valor padrão	'pt-BR'

max

Atributo	max
Descrição	Maior data/horário aceito, interpretado conforme mode. Valores inválidos são ignorados. Aceita texto no atributo HTML ou uma instância de Date por property binding.
Exemplo de uso	<br-datetime-picker mode="date" max="2026-12-31"></br-datetime-picker>
Tipo	Date | string
Valor padrão	null

min

Atributo	min
Descrição	Menor data/horário aceito, interpretado conforme mode. Valores inválidos são ignorados. Aceita texto no atributo HTML ou uma instância de Date por property binding.
Exemplo de uso	<br-datetime-picker mode="date" min="2026-01-01"></br-datetime-picker>
Tipo	Date | string
Valor padrão	null

mode

Atributo	mode
Descrição	Define o modo de seleção exibido pelo componente: data, horário ou ambos. Valores aceitos: date, time ou datetime. Valores inválidos são corrigidos automaticamente para o valor padrão, mantendo o atributo refletido sempre consistente com o modo exibido.
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	Define o placeholder exibido no campo de entrada do datetime picker.
Tipo	string
Valor padrão	''

rangeValue

Atributo	---
Descrição	Intervalo controlado quando selectionMode="range". Deve conter datas válidas ou null em start e end; valores inválidos mantêm o último intervalo efetivo. Passe o objeto por property binding; atributos HTML não representam objetos com Date.
Exemplo de uso	const picker = document.querySelector('br-datetime-picker'); picker.selectionMode = 'range'; picker.rangeValue = { start: new Date(2026, 8, 7), end: new Date(2026, 8, 12), };
Tipo	{ start: Date; end: Date; }
Valor padrão	---

required

Atributo	required
Descrição	Indica se o campo deve ter valor antes do envio do formulário.
Tipo	boolean
Valor padrão	false

selectionMode

Atributo	selection-mode
Descrição	Define o tipo de seleção de datas para o calendário: única ou intervalo. range só funciona em conjunto com mode="date". Se selectionMode="range" for informado, o componente ajusta automaticamente mode para date. Se mode mudar para time ou datetime, o componente normaliza selectionMode para single quando necessário. Valores inválidos usam single.
Tipo	"range" | "single"
Valor padrão	'single'

serializedValue

Atributo	serialized-value
Descrição	Representação serializada compatível com os formatos de controles HTML (YYYY-MM-DD, HH:mm ou ISO local, conforme mode). Em intervalos, usa início/fim. Na inicialização, tem precedência sobre valueAsDate, value e initialMoment. Uma string vazia inicia sem seleção, mesmo quando outra prop fornece uma data.
Exemplo de uso	<br-datetime-picker mode="datetime" serialized-value="2026-09-07T14:30"></br-datetime-picker>
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 à data ou intervalo selecionado. Retorne uma mensagem para invalidar ou null para aceitar o valor.
Exemplo de uso	const picker = document.querySelector('br-datetime-picker'); picker.validator = (value) => value === null ? 'Escolha uma data' : null;
Tipo	(value: Date | DatetimePickerDateRange) => string | Promise<string>
Valor padrão	---

value

Atributo	---
Descrição	Instância de Date selecionada pelo usuário no modo simples. Pode ser controlada por property binding e é atualizada pelo evento valueChange. Para formulários e atributos textuais, use serializedValue.
Exemplo de uso	const picker = document.querySelector('br-datetime-picker'); picker.value = new Date(2026, 8, 7, 14, 30);
Tipo	Date
Valor padrão	null

valueAsDate

Atributo	---
Descrição	Espelho tipado da seleção atual, equivalente ao padrão valueAsDate dos controles HTML. Diferentemente de serializedValue, recebe e retorna uma instância de Date. Na inicialização, tem precedência sobre value e initialMoment quando serializedValue não é informado. null inicia sem seleção; undefined permite usar as outras props.
Exemplo de uso	const picker = document.querySelector('br-datetime-picker'); picker.valueAsDate = new Date(2026, 8, 7);
Tipo	Date
Valor padrão	---

weekStartsOn

Atributo	week-starts-on
Descrição	Define o dia inicial da semana exibida no calendário. Valores suportados: 0 (domingo) a 6 (sábado).
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
brDatetimePickerValidationChange Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.	Emitido ao iniciar e concluir a validação customizada.	---	true
dateStateChange	Evento público emitido quando a data de referência ou a seleção mudam.	---	true
valueChange Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.	Evento emitido quando o valor selecionado muda.	Use input/change e leia event.target.value.	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.
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:

setDisabledDates

Descrição	Define programaticamente as datas desabilitadas por meio de array. Útil quando o componente é usado via HTML e o consumidor precisa enviar uma lista tipada em runtime.
Assinatura	setDisabledDates(dates: DatetimePickerDisabledDate[] | null) => Promise<void>
Parâmetros	dates: - Lista de datas (Date|string) a bloquear.

setRange

Descrição	Define intervalo de datas de forma imperativa, forçando modo date e selectionMode range.
Assinatura	setRange(start: Date | string | null, end: Date | string | null) => Promise<void>
Parâmetros	start: end:

setValue

Descrição	Define o valor atual de forma imperativa aceitando Date, string serializada ou null.
Assinatura	setValue(value: Date | string | null) => Promise<void>
Parâmetros	value:

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 do picker e retorna se a seleção atual é válida.
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.

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.