Datetime Input

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-datetime-input é o subcomponente do ecossistema Datetime-picker responsável pelo campo de entrada com máscara formatada. Na quase totalidade das aplicações, utilize diretamente o componente orquestrador <br-datetime-picker>, que gerencia automaticamente a digitação e a sincronização com os seletores visuais.

Visão Geral

Subcomponente especializado do ecossistema de datas do GovBR-DS, responsável pela digitação e formatação de datas e horários via teclado.

Papel na composição

• Aplica máscaras automáticas de digitação conforme o formato configurado (ex.: DD/MM/AAAA, HH:mm, DD/MM/AAAA HH:mm).
• Contém o botão de acionamento para expandir ou recolher o popup do calendário.

Regra de uso e relacionamento

No fluxo usual da aplicação, é instanciado e coordenado automaticamente pelo orquestrador br-datetime-picker. Pode ser utilizado de forma autônoma apenas quando o leiaute exigir somente o campo de digitação textual sem o painel flutuante de calendário.

Para a documentação completa de design, consulte o Design System do GovBR.

Exemplo(s)

Propriedades

disabled

Atributo	disabled
Descrição	Desabilita digitação e abertura do picker quando ativo.
Tipo	boolean
Valor padrão	false

mode

Atributo	mode
Descrição	Define o modo de entrada: date, time ou datetime.
Tipo	"date" | "datetime" | "time"
Valor padrão	'datetime'

placeholder

Atributo	placeholder
Descrição	Define o placeholder do campo de entrada.
Tipo	string
Valor padrão	''

rangeEnd

Atributo	---
Descrição	Data final do intervalo quando em modo range.
Tipo	Date
Valor padrão	null

rangeStart

Atributo	---
Descrição	Data inicial do intervalo quando em modo range.
Tipo	Date
Valor padrão	null

rangeValue

Atributo	---
Descrição	Intervalo controlado no modo range, reunindo rangeStart e rangeEnd em uma atualização. Deve conter datas válidas ou null; valores inválidos são ignorados. Passe o objeto por property binding.
Exemplo de uso	const input = document.querySelector('br-datetime-input'); input.selectionMode = 'range'; input.rangeValue = { start: new Date(2026, 8, 7), end: new Date(2026, 8, 12) };
Tipo	{ start: Date; end: Date; }
Valor padrão	---

referenceDate

Atributo	---
Descrição	Data de referência que orienta a navegação visual do calendário sem alterar a seleção. Recebe uma instância de Date por property binding.
Exemplo de uso	const input = document.querySelector('br-datetime-input'); input.referenceDate = new Date(2026, 8, 1);
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. Aceita single ou range; valores inválidos usam single.
Tipo	"range" | "single"
Valor padrão	'single'

value

Atributo	---
Descrição	Data efetivamente selecionada, ou null quando nada foi escolhido; é diferente de referenceDate, que controla apenas a referência visual. Recebe uma instância de Date por property binding.
Exemplo de uso	const input = document.querySelector('br-datetime-input'); input.value = new Date(2026, 8, 7, 14, 30);
Tipo	Date
Valor padrão	null

Eventos

Evento	Descrição	Depreciação	Propagação
dateStateChange	Emite quando o valor é alterado via input ou parsing.	---	true
togglePicker	Solicita ao componente pai a alternância da abertura do picker.	---	true

CSS Shadow Parts

Nome	Descrição
"container"	Parte para o container base do campo.
"icon"	Parte para o ícone de ação (calendário/relógio).
"input"	Parte para o campo textual interno.

Dependências

Componente pai

• br-datetime-picker

Usado por

• br-datetime-picker

Depende de

• br-input
• br-icon

Gráfico

Migração para <br-datetime-input>

O br-datetime-input não existia na linha 1.x. Na 2.x, ele é o campo de entrada usado internamente por br-datetime-picker.

Aplicações devem preferir o componente pai, que mantém valor, calendário, horário, formulário e validação sincronizados:

<br-datetime-picker mode="datetime" name="inicio" placeholder="Selecione data e hora"></br-datetime-picker>

Use br-datetime-input diretamente somente em uma composição que também controle seu estado. mode define o formato editado, value e rangeValue recebem os valores controlados, togglePicker solicita abertura ou fechamento e dateStateChange comunica uma edição válida.

Não combine os eventos desse subcomponente com os eventos públicos de br-datetime-picker; no componente completo, ouça input e change no host pai.