# Date

A date picker field

****

- Read more: <https://getkirby.com/docs/guide/blueprints/fields>
- Source: <https://github.com/getkirby/kirby/tree/5.5.3/config/fields/date.php>

****

The date field generates a simple input with a nice date picker. It can be setup to display and store dates.

<figure class="image"><a data-lightbox href="https://assets.getkirby.com/media/pages/docs/reference/panel/fields/date/5da9abadcf-1717846665/date.png?width=1416&amp;height=328&amp;enlarge=0"><img alt="" class="rounded" height="214" loading="lazy" sizes="auto" src="https://assets.getkirby.com/media/pages/docs/reference/panel/fields/date/5da9abadcf-1717846665/date.png?width=924&amp;height=214&amp;enlarge=0" srcset="https://assets.getkirby.com/media/pages/docs/reference/panel/fields/date/5da9abadcf-1717846665/date.png?width=462&amp;height=107&amp;enlarge=0 462w, https://assets.getkirby.com/media/pages/docs/reference/panel/fields/date/5da9abadcf-1717846665/date.png?width=690&amp;height=160&amp;enlarge=0 690w, https://assets.getkirby.com/media/pages/docs/reference/panel/fields/date/5da9abadcf-1717846665/date.png?width=924&amp;height=214&amp;enlarge=0 924w, https://assets.getkirby.com/media/pages/docs/reference/panel/fields/date/5da9abadcf-1717846665/date.png?width=1380&amp;height=320&amp;enlarge=0 1380w, https://assets.getkirby.com/media/pages/docs/reference/panel/fields/date/5da9abadcf-1717846665/date.png?width=1416&amp;height=328&amp;enlarge=0 1848w" width="924"></a></figure>

## Example

```yaml
fields:
  published:
    label: Published on
    type: date
```

## Field properties



<div class="table">
	<table class="parameters">
		<thead>
			<tr>
				<th>Name</th>
				<th>Type</th>
				<th>Default</th>

								<th>Description</th>
							</tr>
		</thead>
		<tbody>
						<tr>
				<td>
					after				</td>
				<td><code class="type type-mixed">mixed</code></td>

				<td data-label="Default:">
															<code>null</code>
									</td>

								<td>Optional text that will be shown after the input</td>
							</tr>
						<tr>
				<td>
					autofocus				</td>
				<td><code class="type type-bool">bool</code></td>

				<td data-label="Default:">
															<code>null</code>
									</td>

								<td>Sets the focus on this field when the form loads. Only the first field with this label gets</td>
							</tr>
						<tr>
				<td>
					before				</td>
				<td><code class="type type-mixed">mixed</code></td>

				<td data-label="Default:">
															<code>null</code>
									</td>

								<td>Optional text that will be shown before the input</td>
							</tr>
						<tr>
				<td>
					calendar				</td>
				<td><code class="type type-bool">bool</code></td>

				<td data-label="Default:">
															<code>true</code>
									</td>

								<td>Activate/deactivate the dropdown calendar</td>
							</tr>
						<tr>
				<td>
					default				</td>
				<td><code class="type type-string">string</code></td>

				<td data-label="Default:">
															<code>null</code>
									</td>

								<td>Default date when a new page/file/user gets created</td>
							</tr>
						<tr>
				<td>
					disabled				</td>
				<td><code class="type type-bool">bool</code></td>

				<td data-label="Default:">
															<code>null</code>
									</td>

								<td>If <code class="type type-bool">true</code>, the field is no longer editable and will not be saved</td>
							</tr>
						<tr>
				<td>
					display				</td>
				<td><code class="type type-mixed">mixed</code></td>

				<td data-label="Default:">
															<code>'YYYY-MM-DD'</code>
									</td>

								<td>Custom format (dayjs tokens: <code class="type">DD</code>, <code class="type">MM</code>, <code class="type">YYYY</code>) that is used to display the field in the Panel</td>
							</tr>
						<tr>
				<td>
					format				</td>
				<td><code class="type type-string">string</code></td>

				<td data-label="Default:">
															<code>null</code>
									</td>

								<td>Defines a custom format that is used when the field is saved</td>
							</tr>
						<tr>
				<td>
					help				</td>
				<td><code class="type type-mixed">mixed</code></td>

				<td data-label="Default:">
															<code>null</code>
									</td>

								<td>Optional help text below the field</td>
							</tr>
						<tr>
				<td>
					icon				</td>
				<td><code class="type type-string">string</code></td>

				<td data-label="Default:">
															<code>'calendar'</code>
									</td>

								<td>Changes the calendar icon to something custom</td>
							</tr>
						<tr>
				<td>
					label				</td>
				<td><code class="type type-mixed">mixed</code></td>

				<td data-label="Default:">
															<code>null</code>
									</td>

								<td>The field label can be set as string or associative array with translations</td>
							</tr>
						<tr>
				<td>
					max				</td>
				<td><code class="type type-string">string</code></td>

				<td data-label="Default:">
															<code>null</code>
									</td>

								<td>Latest date, which can be selected/saved (Y-m-d)</td>
							</tr>
						<tr>
				<td>
					min				</td>
				<td><code class="type type-string">string</code></td>

				<td data-label="Default:">
															<code>null</code>
									</td>

								<td>Earliest date, which can be selected/saved (Y-m-d)</td>
							</tr>
						<tr>
				<td>
					required				</td>
				<td><code class="type type-bool">bool</code></td>

				<td data-label="Default:">
															<code>null</code>
									</td>

								<td>If <code class="type type-bool">true</code>, the field has to be filled in correctly to be saved.</td>
							</tr>
						<tr>
				<td>
					step				</td>
				<td><code class="type type-mixed">mixed</code></td>

				<td data-label="Default:">
															<code>null</code>
									</td>

								<td>Round to the nearest: sub-options for <code class="type">unit</code> (day) and <code class="type">size</code> (1)</td>
							</tr>
						<tr>
				<td>
					time				</td>
				<td><code class="type type-mixed">mixed</code></td>

				<td data-label="Default:">
															<code>false</code>
									</td>

								<td>Pass <code class="type type-bool">true</code> or an array of time field options to show the time selector.</td>
							</tr>
						<tr>
				<td>
					translate				</td>
				<td><code class="type type-bool">bool</code></td>

				<td data-label="Default:">
															<code>true</code>
									</td>

								<td>If <code class="type type-bool">false</code>, the field will be disabled in non-default languages and cannot be translated. This is only relevant in multi-language setups.</td>
							</tr>
						<tr>
				<td>
					when				</td>
				<td><code class="type type-mixed">mixed</code></td>

				<td data-label="Default:">
															<code>null</code>
									</td>

								<td>Conditions when the field will be shown (since 3.1.0)</td>
							</tr>
						<tr>
				<td>
					width				</td>
				<td><code class="type type-string">string</code></td>

				<td data-label="Default:">
															<code>'1/1'</code>
									</td>

								<td>The width of the field in the field grid, e.g. <code class="type">1/1</code>, <code class="type">1/2</code>, <code class="type">1/3</code>, <code class="type">1/4</code>, <code class="type">2/3</code>, <code class="type">3/4</code></td>
							</tr>
					</tbody>
	</table>
</div>

## Display format

You can define the format of the date via the `display` option:

```yaml
display: YYYY-MM-DD
display: DD.MM.YYYY
display: MM/DD/YYYY
```

| Token | Output | Description |
|--|--|--|
| `YY` | 18 | Two-digit year
| `YYYY` | 2018 | Four-digit year
| `M` | 1-12 | Month
| `MM` | 01-12 | Month, 2-digits
| `MMM` | Jan-Dec | Abbreviated month name
| `MMMM` | January-December | Full month name
| `D` | 1-31 | Day of the month
| `DD` | 01-31 | Day of the month, 2-digits

The field will parse any input by matching it to the display format. `display: DD.MM.YYYY` will match an input of `01.05.2015`. It will also match partials or slight variations, e.g. `01.05.`, `1.5.2015`, `01.05.15`. The base for partials will be the current year, month...

## Step

The `step` option allows you to define intervals of valid values. Any input to the field gets rounded to the nearest interval step.

```yaml
step:
  unit: day
  size: 2

# only unit, size will default to `1`
step: month

# only size, unit will default to `day`
step: 2
```

While this is more useful in the [`time` field](/docs/reference/panel/fields/time) (e.g. rounding to 5 minute steps), in the context of the `date` field this can be used, e.g. to let users only select month and year:

```yaml
myMonth:
  type: date
  display: MMM YYYY
  step: month
```

<info>
Keep in mind that the full date is still [stored in the content file](#how-to-use-in-templates-snippets), e.g. `2020-05-01`. You need to adapt your templates as well to only show month and year, e.g. `$page->myMonth()->toDate('F Y')`.
</info>

## Time settings

To enable time input, set the `time` option to `true`:

```yaml
fields:
  published:
    label: Published on
    type: date
    time: true
```

You can also pass all [`time` field](/docs/reference/panel/fields/time) options to the time input:

```yaml
fields:
  published:
    label: Published on
    type: date
    time:
      step: 1 # 1 minute steps
```

If you want to define a `display` option, define it for date and time input separately:

```yaml
fields:
  published:
    label: Published on
    type: date
    display: MM/DD/YYYY
    time:
      display: h.mm a
```

## Default value

The default value can either be set to a specific date (e.g. `2020-05-01`) or as `today`.

```yaml
fields:
  published:
    label: Published on
    type: date
    default: today
```

With the `time` option enabled, you can set a specific date and time (e.g. `2022-07-01 12:05`) or use `now` for the current date and time:

```yaml
fields:
  published:
    label: Published on
    type: date
    time: true
    default: now
```

Or using a combination of the current date but a specific time:

```yaml
fields:
  published:
    label: Published on
    type: date
    time: true
    default: today 20:15
```

You can even do date/or date-time calculations:

```yaml
fields:
  published:
    label: Published on
    type: date
    time: true
    default: now + 1 day
```

This also works for `today`. Other relative settings like `tomorrow` or `yesterday` will also work, btw.

## How to use in templates/snippets

The field stores its value in a standardized format in the content file: `Y-m-d` for only dates, `Y-m-d H:i:s` for date and time combined. To convert the value to a date string or timestamp, use the [`toDate()`](/docs/reference/templates/field-methods/to-date) method.

Without a date format, the `toDate()` field method renders a UNIX timestamp:

```php
<?= $page->published()->toDate() ?>
```

Use a date format to render the date in your desired <a href="https://www.php.net/manual/en/function.date.php">output format</a>:

```php
<?= $page->published()->toDate('Y-m-d') ?>
```

If you have set the <a href="https://getkirby.com/docs/reference/system/options/date">date handler</a> to `strftime` in your config, use the corresponding <a href="https://www.php.net/manual/en/function.strftime.php">format syntax</a>:

```php
<?= $page->published()->toDate('%Y-%m-%d') ?>
```