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

Use other options instead

This option is available for backward compatibility with Netlify/Decap CMS. The newer input_timezone and output_utc options provide more flexibility and supersede this option. picker_utc: true is equivalent to input_timezone: utc.

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

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

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

`input_timezone`

Type: 'local' | 'utc' | string
Default: 'local'

Timezone used by the date/time input. This option supersedes picker_utc. Accepted values:

local (default): The browser’s local timezone is used.
utc: UTC is used.
Custom timezone name: A timezone from the IANA timezone database can be provided, e.g., America/New_York, Asia/Tokyo.

`output_utc`

Type: boolean
Default: false

Whether to convert stored values to UTC. This option supersedes picker_utc.

If false (default), output values preserve the timezone semantics of input_timezone:

local: Omits timezone information (e.g., 2025-08-15T14:30:00).
utc: Appends a Z suffix to indicate UTC (e.g., 2025-08-15T14:30:00Z).
Custom timezone: Preserves the timezone offset (e.g., 2025-08-15T14:30:00-04:00 for America/New_York, Eastern Daylight Time).

If true, the input value is converted to UTC for storage. When no custom format is specified, a Z suffix is appended to the ISO 8601 output. When a custom format is used, the value is stored in UTC but formatted according to that pattern — which won’t include an explicit timezone indicator unless the format itself contains Z.

UTC Already Implied

Note that input_timezone: utc already implies UTC semantics, so output_utc has no additional effect in that case.

`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"
}

Custom Timezone with `input_timezone`

Use input_timezone to make the date/time picker use a specific timezone. For example, to allow users to schedule events in New York time:

YAMLTOMLJSONJavaScript

yaml

- name: eventTime
  label: Event Time (New York)
  widget: datetime
  input_timezone: America/New_York

toml

[[fields]]
name = "eventTime"
label = "Event Time (New York)"
widget = "datetime"
input_timezone = "America/New_York"

json

{
  "name": "eventTime",
  "label": "Event Time (New York)",
  "widget": "datetime",
  "input_timezone": "America/New_York"
}

{
  name: "eventTime",
  label: "Event Time (New York)",
  widget: "datetime",
  input_timezone: "America/New_York",
}

Output example (with timezone offset preserved):

YAMLTOMLJSON

yaml

eventTime: 2025-08-15T14:30:00-04:00

toml

eventTime = 2025-08-15T14:30:00-04:00

json

{
  "eventTime": "2025-08-15T14:30:00-04:00"
}

UTC Conversion with `output_utc`

Use output_utc: true to store all date/time values in UTC, regardless of the user’s input timezone. This is useful for ensuring consistent data storage:

YAMLTOMLJSONJavaScript

yaml

- name: eventTime
  label: Event Time
  widget: datetime
  input_timezone: America/New_York
  output_utc: true

toml

[[fields]]
name = "eventTime"
label = "Event Time"
widget = "datetime"
input_timezone = "America/New_York"
output_utc = true

json

{
  "name": "eventTime",
  "label": "Event Time",
  "widget": "datetime",
  "input_timezone": "America/New_York",
  "output_utc": true
}

{
  name: "eventTime",
  label: "Event Time",
  widget: "datetime",
  input_timezone: "America/New_York",
  output_utc: true,
}

Output example (converted to UTC with Z suffix):

YAMLTOMLJSON

yaml

eventTime: 2025-08-15T18:30:00Z

toml

eventTime = 2025-08-15T18:30:00Z

json

{
  "eventTime": "2025-08-15T18:30:00Z"
}

Local Timezone with Custom Format

Combine input_timezone, output_utc, and format to store values in a custom format while maintaining timezone awareness:

YAMLTOMLJSONJavaScript

yaml

- name: publishTime
  label: Publish Time
  widget: datetime
  input_timezone: local
  output_utc: true
  format: YYYY-MM-DD HH:mm

toml

[[fields]]
name = "publishTime"
label = "Publish Time"
widget = "datetime"
input_timezone = "local"
output_utc = true
format = "YYYY-MM-DD HH:mm"

json

{
  "name": "publishTime",
  "label": "Publish Time",
  "widget": "datetime",
  "input_timezone": "local",
  "output_utc": true,
  "format": "YYYY-MM-DD HH:mm"
}

{
  name: "publishTime",
  label: "Publish Time",
  widget: "datetime",
  input_timezone: "local",
  output_utc: true,
  format: "YYYY-MM-DD HH:mm",
}

Output example (UTC time in custom format):

YAMLTOMLJSON

yaml

publishTime: 2025-08-15 18:30

toml

publishTime = "2025-08-15 18:30"

json

{
  "publishTime": "2025-08-15 18:30"
}

DateTime Field ​

User Interface ​

Editor ​

Preview ​

Data Type ​

Data Validation ​

Options ​

Required Options ​

widget ​

Optional Options ​

default ​

type ​

min ​

max ​

step ​

picker_utc ​

input_timezone ​

output_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 ​

Custom Timezone with input_timezone ​

UTC Conversion with output_utc ​

Local Timezone with Custom Format ​

DateTime Field

User Interface

Editor

Preview

Data Type

Data Validation

Options

Required Options

`widget`

Optional Options

`default`

`type`

`min`

`max`

`step`

`picker_utc`

`input_timezone`

`output_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

Custom Timezone with `input_timezone`

UTC Conversion with `output_utc`

Local Timezone with Custom Format