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.

Future Plans

The date_format and time_format options derived from Netlify/Decap CMS may be confusing. We plan to add the new type option for selecting between date, time, and date-time inputs more intuitively, and introduce new input types: year, month and week.

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.

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 custom format for displaying the date portion using Day.js format tokens. If set to false, the date picker will be hidden, making the field time-only. If not specified, the date picker will be shown with the default format.

time_format

• Type: string or boolean
• Default: true

A custom format for displaying the time portion using Day.js format tokens. If set to false, the time picker will be hidden, making the field date-only. If not specified, the time picker will be shown with the default format.

Examples

Date and Time

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

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

JavaScript

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

Output example:

YAML

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

TOML

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

JSON

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

Date-only

Set time_format to false to hide the time picker and make the input date only:

YAML

- name: startDate
  label: Start Date
  widget: datetime
  time_format: false

TOML

[[fields]]
name = "startDate"
label = "Start Date"
widget = "datetime"
time_format = false

JSON

{
  "name": "startDate",
  "label": "Start Date",
  "widget": "datetime",
  "time_format": false
}

JavaScript

{
  name: "startDate",
  label: "Start Date",
  widget: "datetime",
  time_format: false,
}

Output example:

YAML

startDate: 2025-08-15

TOML

startDate = 2025-08-15

JSON

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

Time-only

Set date_format to false to hide the date picker and make the input time only:

YAML

- name: startTime
  label: Start Time
  widget: datetime
  date_format: false

TOML

[[fields]]
name = "startTime"
label = "Start Time"
widget = "datetime"
date_format = false

JSON

{
  "name": "startTime",
  "label": "Start Time",
  "widget": "datetime",
  "date_format": false
}

JavaScript

{
  name: "startTime",
  label: "Start Time",
  widget: "datetime",
  date_format: false,
}

Output example:

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:

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

JavaScript

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

Output example:

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:

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

JavaScript

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

Output example:

YAML

eventDateTime: 08/15/2025 14:30

TOML

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

JSON

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