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.
A field with the auto_now option shows its value as text instead, as it can’t be edited. The field is hidden while a new entry is being created.
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:ssZ(e.g.14:30:00Z). - Without
picker_utc:HH:mm:ss(e.g.14:30:00).
- With
- Date and time:
- With
picker_utc:YYYY-MM-DDTHH:mm:ssZ(e.g.2025-08-15T14:30:00Z). - Without
picker_utc:YYYY-MM-DDTHH:mm:ss(e.g.2025-08-15T14:30:00).
- With
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.
TOML Output
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. This also applies to TOML front matter.
- A value set or changed in the editor carries millisecond precision, so the examples above are written as
2025-08-15T14:30:00.000and14:30:00.000. - A value read from an existing file that isn’t edited is written back as it appears there, e.g.
2025-08-15T14:30:00Z, with any finer precision kept. - TOML has no offset-time type, so a UTC time-only value loses its
Zsuffix and is written as a local time (e.g.14:30:00.000). - A value that isn’t a valid date or time, such as
TBDin an existing file, is kept as a quoted string.
Data Validation
- If the
requiredoption is set totrue, 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
patternoption is provided, the date/time value must match the specified regular expression pattern.
A field with the auto_now option is not validated, as its value is set automatically.
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.
auto_now
- Type:
booleanorstring[] - Default:
false
Whether to set the field to the current date and time automatically when an entry is saved. This is useful for keeping track of when an entry was created and last modified, such as the date and lastmod front matter fields in Hugo. Accepted values:
true: The value is set whenever the entry is saved. Same as[create, update].false(default): The value is not set automatically.- An array of the stages at which the value is set:
create: When the entry is first saved. It also covers a value that hasn’t been set yet, such as one in a List item added to an existing entry, or one in an entry saved before the option was enabled.update: Whenever an existing entry is saved.
Use [create] for a creation date and true for a last modified date.
Unlike default: '{{now}}', which fills in the current date and time when a new entry draft is created, this option sets the value at the time of saving. The value is stored in the same format as other values, with options such as format, input_timezone and output_utc applied, but it includes seconds. All the fields and locales saved together get the same value.
The field is read-only: its value is shown as text rather than an input, and it’s not validated. The field is hidden while a new entry is being created, because it has no value until the entry is saved. All locales get the same date and time; with the localize_format option, it’s written in each locale’s language.
Limitations
The option is ignored in a field within a rich text editor component, where the field can be edited as usual. Setting the value when an entry is published with the Editorial Workflow is not supported yet.
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:
9999-12-31T23:59fordatetime-local,9999-12-31fordateandundefinedfortime
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:
numberor"any" - Default:
60fordatetime-localandtime;1fordate
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.300for 5-minute steps). - For
"date"inputs, the integer represents the step in days (e.g.7for 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 aZsuffix to indicate UTC (e.g.2025-08-15T14:30:00Z).- Custom timezone: Preserves the timezone offset (e.g.
2025-08-15T14:30:00-04:00forAmerica/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.
Limited Timezone Support for Time-only Fields
For time-only fields (type: time or date_format: false), the only timezone setting that affects the stored value is input_timezone: utc, which appends a Z suffix (e.g. 14:30:00Z).
A custom input_timezone and output_utc are ignored, and the time is stored as entered (e.g. 14:30:00). This is because converting a wall-clock time to another timezone requires a reference date. Use a date/time field if you need the value converted.
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.
localize_format
- Type:
booleanorstring - Default:
false
Whether to write the locale-dependent parts of a custom format, such as month names (MMMM, MMM) and the AM/PM marker (A, a), in a language other than English. Accepted values:
false(default): English is used, as with Netlify/Decap CMS.true: The locale of the content is used. With i18n support enabled, each locale gets the value in its own language, e.g.1 March 2026in English and1 März 2026in German.- A locale code, e.g.
deorpt-BR: That locale is used for every value. This also works without i18n support, e.g. on a German-only site.
Values are read in the same locale, so an existing value is shown in the date/time picker as usual.
With true, a value copied to another locale is written again in that locale. A value is copied in these cases:
- with the
duplicatei18n strategy - when a locale is enabled for an entry
- with bulk editing
The locale also applies to the date string transformation, entry summaries, sorting and filtering.
The option has no effect without a custom format, because an ISO 8601 value doesn’t depend on the locale. A locale code Day.js doesn’t support falls back to English. Both cases are reported as a warning in the browser console, as is true in a collection without i18n support.
The locale data is loaded from the UNPKG CDN when the CMS starts, or bundled with the npm package. If it can’t be loaded, values are written in English.
Limitations
- Day.js can’t read weekday names (
dddd,dddanddd) in any language, including English. A value written in a format with them can’t be read back, so the date/time picker is left empty. - A value with a UTC offset (
ZorZZ) copied to another locale is written in UTC. It refers to the same moment, written differently.
date_format
- Type:
stringorboolean - 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:
stringorboolean - 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:
- name: eventDateTime
label: Event Date and Time
widget: datetime[[fields]]
name = "eventDateTime"
label = "Event Date and Time"
widget = "datetime"{
"name": "eventDateTime",
"label": "Event Date and Time",
"widget": "datetime"
}{
name: "eventDateTime",
label: "Event Date and Time",
widget: "datetime",
}Output example:
eventDateTime: 2025-08-15T14:30:00eventDateTime = 2025-08-15T14:30:00.000{
"eventDateTime": "2025-08-15T14:30:00"
}Date-only
Set type to "date" to make the input date only:
- name: startDate
label: Start Date
widget: datetime
type: date[[fields]]
name = "startDate"
label = "Start Date"
widget = "datetime"
type = "date"{
"name": "startDate",
"label": "Start Date",
"widget": "datetime",
"type": "date"
}{
name: "startDate",
label: "Start Date",
widget: "datetime",
type: "date",
}Output example:
startDate: 2025-08-15startDate = 2025-08-15{
"startDate": "2025-08-15"
}Time-only
Set type to "time" to make the input time only:
- name: startTime
label: Start Time
widget: datetime
type: time[[fields]]
name = "startTime"
label = "Start Time"
widget = "datetime"
type = "time"{
"name": "startTime",
"label": "Start Time",
"widget": "datetime",
"type": "time"
}{
name: "startTime",
label: "Start Time",
widget: "datetime",
type: "time",
}Output example:
startTime: 14:30:00startTime = 14:30:00.000{
"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:
- name: eventDateTimeUtc
label: Event Date and Time (UTC)
widget: datetime
picker_utc: true
default: '{{now}}'[[fields]]
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}}"
}{
name: "eventDateTimeUtc",
label: "Event Date and Time (UTC)",
widget: "datetime",
picker_utc: true,
default: '{{now}}',
}Output example:
eventDateTimeUtc: 2025-08-15T14:30:00ZeventDateTimeUtc = 2025-08-15T14:30:00.000Z{
"eventDateTimeUtc": "2025-08-15T14:30:00Z"
}Creation and Modification Dates
Use the auto_now option to record when an entry was created and last modified. The date field is set when the entry is first saved, and the lastmod field whenever it’s saved:
fields:
- name: date
label: Created
widget: datetime
auto_now: [create]
- name: lastmod
label: Last Modified
widget: datetime
auto_now: true[[fields]]
name = "date"
label = "Created"
widget = "datetime"
auto_now = ["create"]
[[fields]]
name = "lastmod"
label = "Last Modified"
widget = "datetime"
auto_now = true{
"fields": [
{
"name": "date",
"label": "Created",
"widget": "datetime",
"auto_now": ["create"]
},
{
"name": "lastmod",
"label": "Last Modified",
"widget": "datetime",
"auto_now": true
}
]
}fields: [
{
name: 'date',
label: 'Created',
widget: 'datetime',
auto_now: ['create'],
},
{
name: 'lastmod',
label: 'Last Modified',
widget: 'datetime',
auto_now: true,
},
],Output example, after the entry is updated:
date: 2025-08-15T14:30:12
lastmod: 2025-09-02T09:05:47date = 2025-08-15T14:30:12.000
lastmod = 2025-09-02T09:05:47.000{
"date": "2025-08-15T14:30:12",
"lastmod": "2025-09-02T09:05:47"
}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:
- name: eventDateTime
label: Event Date and Time
widget: datetime
format: MM/DD/YYYY HH:mm[[fields]]
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"
}{
name: "eventDateTime",
label: "Event Date and Time",
widget: "datetime",
format: "MM/DD/YYYY HH:mm",
}Output example:
eventDateTime: 08/15/2025 14:30eventDateTime = "08/15/2025 14:30"{
"eventDateTime": "08/15/2025 14:30"
}Localized Format
Use the localize_format option to write month names in the language of each locale. For example, with English and German enabled in the i18n options, the duplicate strategy copies a date picked in English to the German content, written in German:
- name: eventDate
label: Event Date
widget: datetime
type: date
format: D MMMM YYYY
localize_format: true
i18n: duplicate[[fields]]
name = "eventDate"
label = "Event Date"
widget = "datetime"
type = "date"
format = "D MMMM YYYY"
localize_format = true
i18n = "duplicate"{
"name": "eventDate",
"label": "Event Date",
"widget": "datetime",
"type": "date",
"format": "D MMMM YYYY",
"localize_format": true,
"i18n": "duplicate"
}{
name: "eventDate",
label: "Event Date",
widget: "datetime",
type: "date",
format: "D MMMM YYYY",
localize_format: true,
i18n: "duplicate",
}Output example in English and German:
eventDate: 1 March 2026eventDate: 1 März 2026To write the value in a single language on a site without i18n support, set the option to a locale code instead, e.g. localize_format: de.
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:
- name: bookingDate
label: Booking Date
widget: datetime
type: date
min: 2026-01-01
max: 2026-03-31
step: 7[[fields]]
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
}{
name: "bookingDate",
label: "Booking Date",
widget: "datetime",
type: "date",
min: "2026-01-01",
max: "2026-03-31",
step: 7,
}Output example:
bookingDate: 2026-01-08bookingDate = 2026-01-08{
"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:
- name: appointmentTime
label: Appointment Time
widget: datetime
type: time
min: 09:00
max: 17:00
step: 900[[fields]]
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
}{
name: "appointmentTime",
label: "Appointment Time",
widget: "datetime",
type: "time",
min: "09:00",
max: "17:00",
step: 900,
}Output example:
appointmentTime: 10:15:00appointmentTime = 10:15:00.000{
"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:
- name: eventTime
label: Event Time (New York)
widget: datetime
input_timezone: America/New_York[[fields]]
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"
}{
name: "eventTime",
label: "Event Time (New York)",
widget: "datetime",
input_timezone: "America/New_York",
}Output example (with timezone offset preserved):
eventTime: 2025-08-15T14:30:00-04:00eventTime = 2025-08-15T14:30:00.000-04:00{
"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:
- name: eventTime
label: Event Time
widget: datetime
input_timezone: America/New_York
output_utc: true[[fields]]
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
}{
name: "eventTime",
label: "Event Time",
widget: "datetime",
input_timezone: "America/New_York",
output_utc: true,
}Output example (converted to UTC with Z suffix):
eventTime: 2025-08-15T18:30:00ZeventTime = 2025-08-15T18:30:00Z{
"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:
- name: publishTime
label: Publish Time
widget: datetime
input_timezone: local
output_utc: true
format: YYYY-MM-DD HH:mm[[fields]]
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"
}{
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):
publishTime: 2025-08-15 18:30publishTime = "2025-08-15 18:30"{
"publishTime": "2025-08-15 18:30"
}