mad-daterange-field — Componentes (Admin)

Componentes de data e hora com datepicker proprio (Alpine.js, sem dependencia de jQuery), formato brasileiro (dd/mm/aaaa) e conversao automatica para formato de banco (yyyy-mm-dd).

`<mad-date-field>` — Campo de data

Props

Prop	Tipo	Default	Descricao
name	string	''	Nome do campo (obrigatorio)
label	string	''	Label do campo
value	string	''	Valor inicial (o registro do MadRenderContext tem precedencia sobre esta prop)
min	string	''	Data minima: `2024-01-01`
max	string	''	Data maxima: `2026-12-31`
display_mask	string	'dd/mm/yyyy'	Formato de exibicao
database_mask	string	'yyyy-mm-dd'	Formato de armazenamento
opens	string	'left'	Lado que o popup do calendario abre: left, right
width / max-width	string	''	Largura / largura maxima do campo (CSS: px, %, calc())
hint	string	''	Texto de ajuda
error	string	''	Mensagem de erro
required	bool	false	Campo obrigatorio
disabled	bool	false	Campo desabilitado
readonly	bool	false	Somente leitura
attrs	string	''	Atributos HTML extras

Uso basico

<mad-date-field name="dt_nascimento" label="Data de nascimento" />

Com limites

<mad-date-field name="dt_inicio" label="Data inicio"
    min="2024-01-01" max="2026-12-31" required />

`<mad-time-field>` — Campo de hora

Props

Prop	Tipo	Default	Descricao
name	string	''	Nome do campo (obrigatorio)
label	string	''	Label do campo
hint	string	''	Texto de ajuda
error	string	''	Mensagem de erro
required	bool	false	Campo obrigatorio
disabled	bool	false	Campo desabilitado
readonly	bool	false	Somente leitura
attrs	string	''	Atributos HTML extras

Uso basico

<mad-time-field name="horario" label="Horario" />

Usa input nativo type="time" do HTML5 (sem dependencia de jQuery).

`<mad-datetime-field>` — Campo de data e hora

Props

Prop	Tipo	Default	Descricao
name	string	''	Nome do campo (obrigatorio)
label	string	''	Label do campo
value	string	''	Valor inicial (o registro do MadRenderContext tem precedencia sobre esta prop)
min	string	''	DateTime minimo: `2024-01-01 08:00`
max	string	''	DateTime maximo: `2026-12-31 18:00`
display_mask	string	'dd/mm/yyyy hh:ii'	Formato de exibicao
database_mask	string	'yyyy-mm-dd hh:ii'	Formato de armazenamento
opens	string	'left'	Lado que o popup do calendario abre: left, right
width / max-width	string	''	Largura / largura maxima do campo (CSS: px, %, calc())
hint	string	''	Texto de ajuda
error	string	''	Mensagem de erro
required	bool	false	Campo obrigatorio
disabled	bool	false	Campo desabilitado
readonly	bool	false	Somente leitura
attrs	string	''	Atributos HTML extras

Uso basico

<mad-datetime-field name="dt_evento" label="Data e hora do evento" />

Com limites

<mad-datetime-field name="agendamento" label="Agendamento"
    min="2024-01-01 08:00" max="2026-12-31 18:00" required />

Par inicio/fim

<mad-form-grid :cols="2">
    <mad-datetime-field name="horario_inicial" label="Inicio" required />
    <mad-datetime-field name="horario_final" label="Fim" required />
</mad-form-grid>

`<mad-daterange-field>` — Periodo (data inicio e fim)

Date range picker moderno com dois calendarios side-by-side, presets sidebar e auto-apply. Pure Alpine.js, sem jQuery datepicker.

Props

Prop	Tipo	Default	Descricao
name_start	string	''	Nome do campo inicio (obrigatorio)
name_end	string	''	Nome do campo fim (obrigatorio)
label	string	''	Label do campo
min	string	''	Data minima: `2024-01-01`
max	string	''	Data maxima: `2026-12-31`
max_span	int	0	Maximo de dias no range (0 = sem limite)
presets	bool	false	Habilita sidebar de presets padrao ERP
custom_presets	array	[]	Presets customizados: `[['Label', 'start', 'end']]`
placeholder	string	'Selecione o período'	Texto quando vazio
clearable	bool	true	Botao X para limpar
opens	string	'left'	Lado que o popup abre: left, right, center
display_mask	string	'dd/mm/yyyy'	Formato de exibicao
database_mask	string	'yyyy-mm-dd'	Formato de armazenamento
width / max-width	string	''	Largura / largura maxima do campo (CSS: px, %, calc())
hint	string	''	Texto de ajuda
error	string	''	Mensagem de erro
required	bool	false	Campo inicio obrigatorio
disabled	bool	false	Campo desabilitado
attrs_start	string	''	Atributos do input inicio
attrs_end	string	''	Atributos do input fim
default_start	string	''	Valor padrao do inicio quando o model nao trouxe valor (fallback, nao sobrescreve valor existente)
default_end	string	''	Valor padrao do fim quando o model nao trouxe valor (idem)

Presets padrao (quando `presets` habilitado)

Preset	Range
Hoje	hoje → hoje
Ontem	ontem → ontem
Ultimos 7 dias	hoje-6 → hoje
Ultimos 30 dias	hoje-29 → hoje
Este mes	1o do mes → ultimo do mes
Mes passado	1o do mes anterior → ultimo do mes anterior
Este trimestre	Q1/Q2/Q3/Q4 conforme data atual
Este ano	01/jan → 31/dez

Uso basico

<mad-daterange-field name_start="dt_ini" name_end="dt_fim" label="Periodo" />

Com presets ERP

<mad-daterange-field name_start="dt_ini" name_end="dt_fim"
    label="Periodo" presets />

Com presets customizados

<mad-daterange-field name_start="dt_ini" name_end="dt_fim"
    label="Periodo" presets
    :custom_presets="[
        ['Safra', '2026-01-01', '2026-06-30'],
        ['Black Friday', '2026-11-20', '2026-11-30'],
    ]" />

Com limites e max span

<mad-daterange-field name_start="dt_ini" name_end="dt_fim"
    label="Periodo do relatorio"
    min="2024-01-01" max="2026-12-31"
    max_span="365" required />

Com callback PHP

<mad-daterange-field name_start="dt_ini" name_end="dt_fim"
    label="Periodo" presets
    mad:change="onPeriodoChange" />

{{-- Abre para a esquerda (padrao) --}}
<mad-daterange-field ... opens="left" />

{{-- Abre para a direita --}}
<mad-daterange-field ... opens="right" />

{{-- Abre centralizado --}}
<mad-daterange-field ... opens="center" />

Comportamento

Auto-apply: seleciona 2a data → aplica e fecha automaticamente
Presets: clique no preset → aplica e fecha com 1 clique
Clear: botao X limpa ambos os campos
Mobile: popup vira bottom-sheet com presets em chips horizontais
Retrocompativel: dois <input type="hidden"> com mad:model, PHP recebe $data->dt_ini e $data->dt_fim separados

Formato e conversao

Componente	Exibicao (usuario)	Armazenamento (banco)
`mad-date-field`	dd/mm/aaaa	yyyy-mm-dd
`mad-time-field`	HH:MM	HH:MM
`mad-datetime-field`	dd/mm/aaaa hh:mm	yyyy-mm-dd HH:MM:SS
`mad-daterange-field`	dd/mm/aaaa → dd/mm/aaaa	yyyy-mm-dd (dois campos)

A conversao ISO → formato brasileiro e automatica ao carregar valores do banco.

Dentro de formulario

<mad-form submit="onSave">
    <mad-form-grid :cols="3">
        <mad-date-field name="dt_pedido" label="Data do pedido" required />
        <mad-time-field name="hora_entrega" label="Hora de entrega" />
        <mad-datetime-field name="dt_aprovacao" label="Aprovacao" />
    </mad-form-grid>
    <mad-daterange-field name_start="dt_ini" name_end="dt_fim"
        label="Periodo de vigencia" />
    <mad-btn type="submit" variant="primary" icon="save">Salvar</mad-btn>
</mad-form>

Quando usar cada componente

Preciso...	Usar
Somente data	`<mad-date-field>`
Somente hora	`<mad-time-field>`
Data e hora juntos	`<mad-datetime-field>`
Periodo (inicio/fim) somente data	`<mad-daterange-field>`
Periodo (inicio/fim) com hora	Dois `<mad-datetime-field>` lado a lado

NUNCA fazer

{{-- ERRADO: usar mad-input-field com type="date" --}}
<mad-input-field name="dt" label="Data" type="date" />

{{-- CERTO --}}
<mad-date-field name="dt" label="Data" />

{{-- ERRADO: usar mad-input-field com type="datetime-local" --}}
<mad-input-field name="dt" label="Data/Hora" type="datetime-local" />

{{-- CERTO --}}
<mad-datetime-field name="dt" label="Data/Hora" />

{{-- ERRADO: usar mad-input-field com type="time" --}}
<mad-input-field name="hr" label="Hora" type="time" />

{{-- CERTO --}}
<mad-time-field name="hr" label="Hora" />

{{-- ERRADO: input nativo --}}
<input type="date" name="dt">
<input type="datetime-local" name="dt">

{{-- CERTO --}}
<mad-date-field name="dt" label="Data" />
<mad-datetime-field name="dt" label="Data/Hora" />

{{-- ERRADO: montar input de data na mao com JS custom / lib de terceiros --}}
<input type="text" name="dt" class="flatpickr">
<script>flatpickr('.flatpickr');</script>

{{-- CERTO --}}
<mad-date-field name="dt" label="Data" />
<mad-datetime-field name="dt" label="Data/Hora" />

{{-- ERRADO: dois date-field para periodo --}}
<mad-date-field name="dt_ini" label="Inicio" />
<mad-date-field name="dt_fim" label="Fim" />

{{-- CERTO: daterange tem os dois inputs vinculados --}}
<mad-daterange-field name_start="dt_ini" name_end="dt_fim" label="Periodo" />

<mad-date-field> — Campo de data#

Props#

Uso basico#

Com limites#

<mad-time-field> — Campo de hora#

Props#

Uso basico#

<mad-datetime-field> — Campo de data e hora#

Props#

Uso basico#

Com limites#

Par inicio/fim#

<mad-daterange-field> — Periodo (data inicio e fim)#

Props#

Presets padrao (quando presets habilitado)#

Uso basico#

Com presets ERP#

Com presets customizados#

Com limites e max span#

Com callback PHP#

Posicao do popup#

Comportamento#

Formato e conversao#

Dentro de formulario#

Quando usar cada componente#

NUNCA fazer#

`<mad-date-field>` — Campo de data

Props

Uso basico

Com limites

`<mad-time-field>` — Campo de hora

Props

Uso basico

`<mad-datetime-field>` — Campo de data e hora

Props

Uso basico

Com limites

Par inicio/fim

`<mad-daterange-field>` — Periodo (data inicio e fim)

Props

Presets padrao (quando `presets` habilitado)

Uso basico

Com presets ERP

Com presets customizados

Com limites e max span

Com callback PHP

Posicao do popup

Comportamento

Formato e conversao

Dentro de formulario

Quando usar cada componente

NUNCA fazer