Skip to content

Kirby 4.1.2

Date

A date picker field

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

Example

fields:
  published:
    label: Published on
    type: date

Field properties

Name Type Default Description
after Optional text that will be shown after the input
autofocus bool Sets the focus on this field when the form loads. Only the first field with this label gets
before Optional text that will be shown before the input
calendar bool true Activate/deactivate the dropdown calendar
default string Default date when a new page/file/user gets created
disabled bool If true, the field is no longer editable and will not be saved
display YYYY-MM-DD Custom format (dayjs tokens: DD, MM, YYYY) that is used to display the field in the Panel
format string Defines a custom format that is used when the field is saved
help Optional help text below the field
icon string calendar Changes the calendar icon to something custom
label The field label can be set as string or associative array with translations
max string Latest date, which can be selected/saved (Y-m-d)
min string Earliest date, which can be selected/saved (Y-m-d)
required bool If true, the field has to be filled in correctly to be saved.
step Round to the nearest: sub-options for unit (day) and size (1)
time false Pass true or an array of time field options to show the time selector.
translate bool true If false, the field will be disabled in non-default languages and cannot be translated. This is only relevant in multi-language setups.
when Conditions when the field will be shown (since 3.1.0)
width string 1/1 The width of the field in the field grid. Available widths: 1/1, 1/2, 1/3, 1/4, 2/3, 3/4

Display format

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

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.

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

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

Keep in mind that the full date is still stored in the content file, 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').

Time settings

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

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

You can also pass all time field options to the time input:

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:

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.

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:

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

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

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 object, use the toDate() method.

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

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

Use a date format to render the date in your desired output format:

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

If you have set the date handler to strftime in your config, use the corresponding format syntax:

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