DateTime Field

The DateTime field type allows users to select and input dates and times using a date/time picker interface.

User Interface

Editor

The browser’s native date/time picker. Depending on the configuration, it can handle date-only, time-only, or both date and time inputs.

Future Plans

We plan to enhance the UI with a custom date/time picker in the future.

Preview

A string representation of the date and/or time, formatted according to the specified format, date_format, or time_format options, or in ISO 8601 format by default.

Data Type

A string representing the date and/or time in ISO 8601 format by default, or in a custom format if specified. The possible formats are:

Date-only: YYYY-MM-DD (e.g., 2025-08-15)
Time-only:
- With picker_utc: HH:mm:ss.SSSZ (e.g., 14:30:00.000Z).
- Without picker_utc: HH:mm:ss (e.g., 14:30:00).
Date and time:
- With picker_utc: YYYY-MM-DDTHH:mm:ss.SSSZ (e.g., 2025-08-15T14:30:00.000Z).
- Without picker_utc: YYYY-MM-DDTHH:mm:ss (e.g., 2025-08-15T14:30:00).

If the format, date_format or time_format option is specified, the string will follow the custom Day.js format defined.

If the required option is set to false and the field is left empty, the value will be an empty string.

If the output format is TOML, the date-time string will be represented as a native, unquoted TOML date value, time value, or date-time value, depending on the configuration, unless a custom format is specified.

Data Validation

If the required option is set to true, the date/time value must not be an empty string.
The date/time value must be a valid date/time string according to the specified format or ISO 8601.
If the pattern option is provided, the date/time value must match the specified regular expression pattern.

Options

In addition to the common field options, the DateTime field supports the following options:

Required Options

`widget`

Type: string
Default: string

Must be set to datetime.

Optional Options

Breaking changes from Netlify/Decap CMS

Sveltia CMS does not support the deprecated camelCase dateFormat, timeFormat and pickerUtc options. Use date_format, time_format and picker_utc instead.

Also, Sveltia CMS (and Decap CMS 3.1.1) has replaced the Moment.js library with Day.js for date formatting and parsing. Since Day.js tokens are not 100% compatible with Moment.js tokens, this could be a breaking change in certain cases. Check your format, date_format and time_format options if you’re migrating from Netlify CMS or earlier versions of Decap CMS.

`default`

Type: string
Default: ""

A default date and/or time value for the field in ISO 8601 format or the specified custom format. Use {{now}} to set the default value to the current date and time.

`type`

Type: string
Default: "datetime-local"

The type HTML attribute value for the date/time input. Accepted values:

"datetime-local" (default): Accepts both date and time values.
"date": Accepts date values only; the time part is disabled.
"time": Accepts time values only; the date part is disabled.

`min`

Type: string
Default: undefined

The min HTML attribute value for the date/time input. The expected format depends on the type option:

"datetime-local": YYYY-MM-DDTHH:mm
"date": YYYY-MM-DD
"time": HH:mm

`max`

Type: string
Default: undefined

The max HTML attribute value for the date/time input. The expected format depends on the type option:

"datetime-local": YYYY-MM-DDTHH:mm
"date": YYYY-MM-DD
"time": HH:mm

`step`

Type: number or "any"
Default: 60 for datetime-local and time; 1 for date

The step HTML attribute value for the date/time input. Accepts a positive integer or "any".

For "datetime-local" and "time" inputs, the integer represents the step in seconds (e.g. 300 for 5-minute steps).
For "date" inputs, the integer represents the step in days (e.g. 7 for weekly steps).

`picker_utc`

Type: boolean
Default: false

Determines whether the date/time picker uses UTC time or the user’s local time zone. This is particularly useful when using date-only input (time_format: false); without UTC, the stored date may shift depending on the user’s time zone.

If set to false (default), the picker will use the local time zone of the user. If the format is date/time or time-only, the stored value will not include the Z suffix or any time zone information.

If set to true, the date/time picker will use UTC time instead of the local time zone. If the format is date/time or time-only, the stored value will include the Z suffix to indicate UTC time.

`format`

Type: string
Default: undefined

A custom format for displaying and storing the date and/or time using Day.js format tokens. If not specified, the field will use ISO 8601 format.

Format Recommendation

For data portability, we recommend saving date/time values in ISO 8601 format by omitting the format option. Formatting is better handled in your application code. Using custom formats is generally discouraged unless you have a specific need for it, e.g., integrating with a framework that doesn’t support date formatting or requires a specific format.

`date_format`

Type: string or boolean
Default: true

A date storage format written in Day.js format tokens if the value is a string and the format option is not defined. If true, ISO 8601 format is used unless the format option is defined. If false, date input/output is disabled.

Use other options instead

This option is available for backward compatibility with Netlify/Decap CMS. Use the format or type option instead. date_format: false is equivalent to type: time.

`time_format`

Type: string or boolean
Default: true

A time storage format written in Day.js format tokens if the value is a string and the format option is not defined. If true, ISO 8601 format is used unless the format option is defined. If false, time input/output is disabled.

Use other options instead

This option is available for backward compatibility with Netlify/Decap CMS. Use the format or type option instead. time_format: false is equivalent to type: date.

Examples

Date and Time

By default, the DateTime field includes both date/time pickers. The output is in ISO 8601 format:

YAMLTOMLJSONJavaScript

yaml

- name: eventDateTime
  label: Event Date and Time
  widget: datetime

toml

[[fields]]
name = "eventDateTime"
label = "Event Date and Time"
widget = "datetime"

json

{
  "name": "eventDateTime",
  "label": "Event Date and Time",
  "widget": "datetime"
}

{
  name: "eventDateTime",
  label: "Event Date and Time",
  widget: "datetime",
}

Output example:

YAMLTOMLJSON

yaml

eventDateTime: 2025-08-15T14:30:00

toml

eventDateTime = 2025-08-15T14:30:00

json

{
  "eventDateTime": "2025-08-15T14:30:00"
}

Date-only

Set type to "date" to make the input date only:

YAMLTOMLJSONJavaScript

yaml

- name: startDate
  label: Start Date
  widget: datetime
  type: date

toml

[[fields]]
name = "startDate"
label = "Start Date"
widget = "datetime"
type = "date"

json

{
  "name": "startDate",
  "label": "Start Date",
  "widget": "datetime",
  "type": "date"
}

{
  name: "startDate",
  label: "Start Date",
  widget: "datetime",
  type: "date",
}

Output example:

YAMLTOMLJSON

yaml

startDate: 2025-08-15

toml

startDate = 2025-08-15

json

{
  "startDate": "2025-08-15"
}

Time-only

Set type to "time" to make the input time only:

YAMLTOMLJSONJavaScript

yaml

- name: startTime
  label: Start Time
  widget: datetime
  type: time

toml

[[fields]]
name = "startTime"
label = "Start Time"
widget = "datetime"
type = "time"

json

{
  "name": "startTime",
  "label": "Start Time",
  "widget": "datetime",
  "type": "time"
}

{
  name: "startTime",
  label: "Start Time",
  widget: "datetime",
  type: "time",
}

Output example:

YAMLTOMLJSON

yaml

startTime: 14:30:00

toml

startTime = 14:30:00

json

{
  "startTime": "14:30:00"
}

UTC Picker and Default Now

Set picker_utc to true to use UTC time in the date/time picker. The default option is set to {{now}} to use the current date and time as the default value:

YAMLTOMLJSONJavaScript

yaml

- name: eventDateTimeUtc
  label: Event Date and Time (UTC)
  widget: datetime
  picker_utc: true
  default: '{{now}}'

toml

[[fields]]
name = "eventDateTimeUtc"
label = "Event Date and Time (UTC)"
widget = "datetime"
picker_utc = true
default = "{{now}}"

json

{
  "name": "eventDateTimeUtc",
  "label": "Event Date and Time (UTC)",
  "widget": "datetime",
  "picker_utc": true,
  "default": "{{now}}"
}

{
  name: "eventDateTimeUtc",
  label: "Event Date and Time (UTC)",
  widget: "datetime",
  picker_utc: true,
  default: '{{now}}',
}

Output example:

YAMLTOMLJSON

yaml

eventDateTimeUtc: 2025-08-15T14:30:00.000Z

toml

eventDateTimeUtc = 2025-08-15T14:30:00.000Z

json

{
  "eventDateTimeUtc": "2025-08-15T14:30:00.000Z"
}

Custom Format

The format option allows specifying a custom format for both displaying and storing the date and/or time using Day.js format tokens. For example, to use the format MM/DD/YYYY HH:mm:

YAMLTOMLJSONJavaScript

yaml

- name: eventDateTime
  label: Event Date and Time
  widget: datetime
  format: MM/DD/YYYY HH:mm

toml

[[fields]]
name = "eventDateTime"
label = "Event Date and Time"
widget = "datetime"
format = "MM/DD/YYYY HH:mm"

json

{
  "name": "eventDateTime",
  "label": "Event Date and Time",
  "widget": "datetime",
  "format": "MM/DD/YYYY HH:mm"
}

{
  name: "eventDateTime",
  label: "Event Date and Time",
  widget: "datetime",
  format: "MM/DD/YYYY HH:mm",
}

Output example:

YAMLTOMLJSON

yaml

eventDateTime: 08/15/2025 14:30

toml

eventDateTime = "08/15/2025 14:30"

json

{
  "eventDateTime": "08/15/2025 14:30"
}

Date with Constraints

Use min, max, and step to restrict the allowed date range and increment. For example, to limit a booking date to the first quarter of 2026 with weekly steps:

YAMLTOMLJSONJavaScript

yaml

- name: bookingDate
  label: Booking Date
  widget: datetime
  type: date
  min: 2026-01-01
  max: 2026-03-31
  step: 7

toml

[[fields]]
name = "bookingDate"
label = "Booking Date"
widget = "datetime"
type = "date"
min = "2026-01-01"
max = "2026-03-31"
step = 7

json

{
  "name": "bookingDate",
  "label": "Booking Date",
  "widget": "datetime",
  "type": "date",
  "min": "2026-01-01",
  "max": "2026-03-31",
  "step": 7
}

{
  name: "bookingDate",
  label: "Booking Date",
  widget: "datetime",
  type: "date",
  min: "2026-01-01",
  max: "2026-03-31",
  step: 7,
}

Output example:

YAMLTOMLJSON

yaml

bookingDate: 2026-01-08

toml

bookingDate = 2026-01-08

json

{
  "bookingDate": "2026-01-08"
}

Time with Step

Use step to control the time increment in seconds. For example, to allow 15-minute steps for a time-only input:

YAMLTOMLJSONJavaScript

yaml

- name: appointmentTime
  label: Appointment Time
  widget: datetime
  type: time
  min: 09:00
  max: 17:00
  step: 900

toml

[[fields]]
name = "appointmentTime"
label = "Appointment Time"
widget = "datetime"
type = "time"
min = "09:00"
max = "17:00"
step = 900

json

{
  "name": "appointmentTime",
  "label": "Appointment Time",
  "widget": "datetime",
  "type": "time",
  "min": "09:00",
  "max": "17:00",
  "step": 900
}

{
  name: "appointmentTime",
  label: "Appointment Time",
  widget: "datetime",
  type: "time",
  min: "09:00",
  max: "17:00",
  step: 900,
}

Output example:

YAMLTOMLJSON

yaml

appointmentTime: 10:15:00

toml

appointmentTime = 10:15:00

json

{
  "appointmentTime": "10:15:00"
}

Framework Guides

Migration Guides

Configuration Basics

Backends

Media Storage

Collections

Fields

JavaScript API

User Interface

Workflows

Integrations

DateTime Field

User Interface

Editor

Preview

Data Type

Data Validation

Options

Required Options

`widget`

Optional Options

`default`

`type`

`min`

`max`

`step`

`picker_utc`

`format`

`date_format`

`time_format`

Examples

Date and Time

Date-only

Time-only

UTC Picker and Default Now

Custom Format

Date with Constraints

Time with Step

DateTime Field ​

User Interface ​

Editor ​

Preview ​

Data Type ​

Data Validation ​

Options ​

Required Options ​

widget ​

Optional Options ​

default ​

type ​

min ​

max ​

step ​

picker_utc ​

format ​

date_format ​

time_format ​

Examples ​

Date and Time ​

Date-only ​

Time-only ​

UTC Picker and Default Now ​

Custom Format ​

Date with Constraints ​

Time with Step ​

DateTime Field

User Interface

Editor

Preview

Data Type

Data Validation

Options

Required Options

`widget`

Optional Options

`default`

`type`

`min`

`max`

`step`

`picker_utc`

`format`

`date_format`

`time_format`

Examples

Date and Time

Date-only

Time-only

UTC Picker and Default Now

Custom Format

Date with Constraints

Time with Step