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

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

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.
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.
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.
Tipo	Date | string
Valor padrão	null

min

Atributo	min
Descrição	Menor data/horário aceito, interpretado conforme mode.
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".
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.
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. Quando informada, tem precedência sobre o valor legado value durante a inicialização.
Tipo	string
Valor padrão	---

validator

Atributo	---
Descrição	Regra síncrona ou assíncrona aplicada à data ou intervalo selecionado.
Tipo	(value: Date | DatetimePickerDateRange) => string | Promise<string>
Valor padrão	---

value

Atributo	---
Descrição	Valor selecionado pelo usuário. Pode ser controlado externamente e é atualizado pelo evento valueChange.
Tipo	Date
Valor padrão	null

valueAsDate

Atributo	---
Descrição	Espelho tipado da seleção atual, equivalente ao padrão valueAsDate dos controles HTML.
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

Eventos

Evento	Descrição	Depreciação	Propagação
brDatetimePickerValidationChange	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

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.

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

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

Forneça label visível ou aria-label descritivo e associe ajuda/erro por aria-describedby. O campo, o botão de abrir o calendário e os dias precisam ter nomes e estados determináveis.

O calendário deve ser operável por teclado: Tab para entrar, setas para navegar, Enter/Espaço para escolher e Escape para fechar, com retorno do foco ao acionador.

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