---
url: /en/docs/fields/datetime.md
description: Select dates and times in Sveltia CMS with an interactive date/time picker.
---

# 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.

::: info Future Plans

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

:::

A field with the [`auto_now`](#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`).
* 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`).

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. TOML output always carries millisecond precision, so the examples above are written as `2025-08-15T14:30:00.000` and `14:30:00.000`. Note also that TOML has no offset-time type, so a UTC time-only value loses its `Z` suffix and is written as a local time (e.g., `14:30:00.000`).

## 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.

A field with the [`auto_now`](#auto-now) option is not validated, as its value is set automatically.

## Options

In addition to the [common field options](/en/docs/fields#common-options), the DateTime field supports the following options:

### Required Options

#### `widget`

* **Type**: `string`
* **Default**: `string`

Must be set to `datetime`.

### Optional Options

::: warning 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](https://day.js.org/docs/en/display/format) are not 100% compatible with [Moment.js tokens](https://momentjs.com/docs/#/displaying/format/), 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**: `boolean` or `string[]`
* **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 the other 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, as it has no value until the entry is saved. The value is not localized, so the same value is used for all locales.

::: info Limitations

The option is ignored in a field within a [rich text editor component](/en/docs/fields/richtext#editor-components), where the field can be edited as usual. Setting the value when an entry is published with the [Editorial Workflow](/en/docs/workflows/editorial) is not supported yet.

:::

#### `type`

* **Type**: `string`
* **Default**: `"datetime-local"`

The [`type`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#input_types) 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`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/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:59` for `datetime-local`, `9999-12-31` for `date`, and `undefined` for `time`

The [`max`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/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`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/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`

::: warning 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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) 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`.

::: info UTC Already Implied

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

:::

::: warning 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`), 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](https://day.js.org/docs/en/display/format). If not specified, the field will use ISO 8601 format.

::: tip 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](https://day.js.org/docs/en/display/format) 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.

::: warning 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](https://day.js.org/docs/en/display/format) 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.

::: warning 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:

::: code-group

```yaml [YAML]
- name: eventDateTime
  label: Event Date and Time
  widget: datetime
```

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

```json [JSON]
{
  "name": "eventDateTime",
  "label": "Event Date and Time",
  "widget": "datetime"
}
```

```js [JavaScript]
{
  name: "eventDateTime",
  label: "Event Date and Time",
  widget: "datetime",
}
```

:::

Output example:

::: code-group

```yaml [YAML]
eventDateTime: 2025-08-15T14:30:00
```

```toml [TOML]
eventDateTime = 2025-08-15T14:30:00.000
```

```json [JSON]
{
  "eventDateTime": "2025-08-15T14:30:00"
}
```

:::

### Date-only

Set `type` to `"date"` to make the input [date only](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/date):

::: code-group

```yaml [YAML]
- name: startDate
  label: Start Date
  widget: datetime
  type: date
```

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

```json [JSON]
{
  "name": "startDate",
  "label": "Start Date",
  "widget": "datetime",
  "type": "date"
}
```

```js [JavaScript]
{
  name: "startDate",
  label: "Start Date",
  widget: "datetime",
  type: "date",
}
```

:::

Output example:

::: code-group

```yaml [YAML]
startDate: 2025-08-15
```

```toml [TOML]
startDate = 2025-08-15
```

```json [JSON]
{
  "startDate": "2025-08-15"
}
```

:::

### Time-only

Set `type` to `"time"` to make the input [time only](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/time):

::: code-group

```yaml [YAML]
- name: startTime
  label: Start Time
  widget: datetime
  type: time
```

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

```json [JSON]
{
  "name": "startTime",
  "label": "Start Time",
  "widget": "datetime",
  "type": "time"
}
```

```js [JavaScript]
{
  name: "startTime",
  label: "Start Time",
  widget: "datetime",
  type: "time",
}
```

:::

Output example:

::: code-group

```yaml [YAML]
startTime: 14:30:00
```

```toml [TOML]
startTime = 14:30:00.000
```

```json [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:

::: code-group

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

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

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

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

:::

Output example:

::: code-group

```yaml [YAML]
eventDateTimeUtc: 2025-08-15T14:30:00Z
```

```toml [TOML]
eventDateTimeUtc = 2025-08-15T14:30:00.000Z
```

```json [JSON]
{
  "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:

::: code-group

```yaml [YAML]
fields:
  - name: date
    label: Created
    widget: datetime
    auto_now: [create]
  - name: lastmod
    label: Last Modified
    widget: datetime
    auto_now: true
```

```toml [TOML]
[[fields]]
name = "date"
label = "Created"
widget = "datetime"
auto_now = ["create"]

[[fields]]
name = "lastmod"
label = "Last Modified"
widget = "datetime"
auto_now = true
```

```json [JSON]
{
  "fields": [
    {
      "name": "date",
      "label": "Created",
      "widget": "datetime",
      "auto_now": ["create"]
    },
    {
      "name": "lastmod",
      "label": "Last Modified",
      "widget": "datetime",
      "auto_now": true
    }
  ]
}
```

```js [JavaScript]
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:

::: code-group

```yaml [YAML]
date: 2025-08-15T14:30:12
lastmod: 2025-09-02T09:05:47
```

```toml [TOML]
date = 2025-08-15T14:30:12.000
lastmod = 2025-09-02T09:05:47.000
```

```json [JSON]
{
  "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](https://day.js.org/docs/en/display/format). For example, to use the format `MM/DD/YYYY HH:mm`:

::: code-group

```yaml [YAML]
- name: eventDateTime
  label: Event Date and Time
  widget: datetime
  format: MM/DD/YYYY HH:mm
```

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

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

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

:::

Output example:

::: code-group

```yaml [YAML]
eventDateTime: 08/15/2025 14:30
```

```toml [TOML]
eventDateTime = "08/15/2025 14:30"
```

```json [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:

::: code-group

```yaml [YAML]
- name: bookingDate
  label: Booking Date
  widget: datetime
  type: date
  min: 2026-01-01
  max: 2026-03-31
  step: 7
```

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

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

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

:::

Output example:

::: code-group

```yaml [YAML]
bookingDate: 2026-01-08
```

```toml [TOML]
bookingDate = 2026-01-08
```

```json [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:

::: code-group

```yaml [YAML]
- name: appointmentTime
  label: Appointment Time
  widget: datetime
  type: time
  min: 09:00
  max: 17:00
  step: 900
```

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

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

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

:::

Output example:

::: code-group

```yaml [YAML]
appointmentTime: 10:15:00
```

```toml [TOML]
appointmentTime = 10:15:00.000
```

```json [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:

::: code-group

```yaml [YAML]
- name: eventTime
  label: Event Time (New York)
  widget: datetime
  input_timezone: America/New_York
```

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

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

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

:::

Output example (with timezone offset preserved):

::: code-group

```yaml [YAML]
eventTime: 2025-08-15T14:30:00-04:00
```

```toml [TOML]
eventTime = 2025-08-15T14:30:00.000-04:00
```

```json [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:

::: code-group

```yaml [YAML]
- name: eventTime
  label: Event Time
  widget: datetime
  input_timezone: America/New_York
  output_utc: true
```

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

```json [JSON]
{
  "name": "eventTime",
  "label": "Event Time",
  "widget": "datetime",
  "input_timezone": "America/New_York",
  "output_utc": true
}
```

```js [JavaScript]
{
  name: "eventTime",
  label: "Event Time",
  widget: "datetime",
  input_timezone: "America/New_York",
  output_utc: true,
}
```

:::

Output example (converted to UTC with `Z` suffix):

::: code-group

```yaml [YAML]
eventTime: 2025-08-15T18:30:00Z
```

```toml [TOML]
eventTime = 2025-08-15T18:30:00Z
```

```json [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:

::: code-group

```yaml [YAML]
- name: publishTime
  label: Publish Time
  widget: datetime
  input_timezone: local
  output_utc: true
  format: YYYY-MM-DD HH:mm
```

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

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

```js [JavaScript]
{
  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):

::: code-group

```yaml [YAML]
publishTime: 2025-08-15 18:30
```

```toml [TOML]
publishTime = "2025-08-15 18:30"
```

```json [JSON]
{
  "publishTime": "2025-08-15 18:30"
}
```

:::