Datepicker

• Basic example
• Modes
  • Dual entry
  • Picker only
• Date format
  • Styled formats
  • Token formats
• Panel sequence
  • Selecting time
• Values
  • Date styles
  • Token formats
  • Setting values (hydrating)
  • Value locale
• Timezones
  • A case study
  • Indeterminate timezone
  • Specifying a timezone
• Disabling dates
  • Min date
  • Max date
  • Disabled days
  • Scan for availability
• Props & Attributes
• Sections
  • Overlay
  • Years panel
  • Months panel
  • Day panel
  • Time panel
  • Section keys

Basic example

The datepicker input allows users to select a date from a customizable calendar, and type the date directly into the input with full internationalization support.

Modes

FormKit uses a unique masking solution to allow users to type dates into the datepicker input (while limiting the available options to only valid values) or select their date via a calendar input.

Dual entry

• Text entry - By default, users can click or tab into any of the "parts" of the displayed date (month, date, year, etc.) in the text input and type their desired value. Matching values will be displayed with automatic completion. In addition to typing, users can hit the up/down arrow keys to cycle through available options for each segment.
• Picker entry - By clicking the "calendar" icon to the right of the input, users can also display a calendar popup to select their date visually:

Picker only

You can disable the text-entry mechanism and ensure someone uses the datepicker dialog to enter their date by adding the picker-only prop. In picker-only mode, clicking on the input will open the dialog immediately. Additionally, using an overlay is not required for placeholder support:

Date format

The datepicker supports Intl.DateTimeFormat "styled dates", as well as token-based date formats. To change the format displayed to the user, modify the format prop.

Styled formats

If your audience is international, you should consider sticking with "styled dates" since they are the most natural date formats in each locale. The default format for a datepicker is long.

The format prop can accept a simple string like long or medium, in which case it uses the corresponding Intl.DateTimeFormat dateStyle. Alternatively, you can provide an object with date and time properties and their respective Intl.DateTimeFormat styles ({ date: 'long', time: 'short' }).

Date styles

Enable any of the following date styles with the format prop:

Time styles

Token formats

You can use the format prop to explicitly set a tokenized date format. A token format is represented by a string with any arbitrary characters and one or more of the strings in the table below.

FormKit interfaces with the Intl.DateTimeFormat to automatically internationalize tokens based on the current locale. For example, the token MMMM for 2000-01-01 would produce January for the en locale but would produce 一月 for the zh locale.

Escaping tokens

To include letters in the your format that are themselves tokens (like a), you can escape those tokens with a backslash \ before the character:

Panel sequence

The datepicker’s calendar popup has four "panels":

• day — Shows a traditional calendar view of a month with each day selectable.
• month — Shows the 12 months of the year.
• year — Shows a decade of years at a time.
• time — Shows the time of day.

When a user opens the datepicker’s popup, they will be shown one or more of these panels. You can modify which panels are displayed to the user and the sequence those panels should be displayed in by providing a sequence prop. The default sequence value is ['day'] (which allows you to navigate to the month and year panels).

For example, when selecting a birthday, it is natural to first select the birth year, then the month, then the day. The sequence prop allows this behavior:

Selecting time

The time panel can be used to allow a user to select a specific time of day. If you choose a format that includes time (like YYYY-MM-DD HH:mm), you’ll likely want to include time panel to your sequence:

Values

Like all inputs, the value of the datepicker is both what is produced by the datepicker, and what is read back into the datepicker for hydration. By default, the format of the value is a UTC-normalized ISO8601 string (example: 2014-11-27T03:59:00.000Z). However, this format can be changed to any of the supported date style or a token formats listed above by using the value-format prop.

A valid question is why not always use ISO8601? Although it’s the most popular way to work with dates — it’s machine and human readable — it’s not very human readable. For example, if your form sends a contact request email to a catering business, then ISO8601 would likely not be the best choice.

Date styles

To use a date style as the value, simply pass the style you’d like to use to the value-format prop:

Token formats

Values can also be represented in any arbitrary format by using formatting tokens:

Setting values (hydrating)

Values passed to a datepicker must:

1. Match the value-format in the current value-locale OR,
2. Be a native JavaScript Date object.

Although native Date objects are always accepted as valid inputs for a datepicker, they will be immediately transformed into the value-format specified.

Matching the value-format

Using a native Date

Value locale

Since the format of the value needs to be parsed using the same locale it was created with, it is recommended to always specify the value-locale when defining a custom value-format. This ensures that no matter what the locale of the user entering the date is, the value will stay consistent:

Timezones

Time is a notoriously hard thing to work with in any software environment, but especially browser-based JavaScript. The datepicker provides some options to help work around these challenges.

Indeterminate timezone

By default, the datepicker uses the client’s local timezone when a selection is made. The value of the output is determined by the value-format (see above) — by default this is a UTC normalized ISO8601 string. However, by specifying a custom format, you can achieve an "indeterminate" time (also called "wall time"). This is a date and/or time with no specific correlation to a given timezone.

For example, when you set an alarm on your phone for 8:00 AM — that time is "indeterminate" — it has no correlation to timezone. If you live in Rome, and travel to Tokyo, your alarm will ring at 8:00 AM in Tokyo the same as it would ring at 8:00 AM in Rome. It’s impossible to represent a this as UTC.

You can achieve indeterminate time with the datepicker by providing no timezone or offset information in your value-format — it is up to the interpreter of the date to add that information. The tokens in a value-format always output local client values — so by leaving any timezone or offset (Z) data out of the value, it is inherently "indeterminate":

Specifying a timezone

For some applications, it is necessary to select the time in a given location — this can be quite challenging. To help ease this pain, the datepicker supports the ability to explicitly specify the timezone of the input.

The timezone prop lets you specify the "location" of the datepicker based on browser supported IANA timezones. This is important when you’d like to allow users to select a date and time in a given geographic location, no matter what the client’s location is. Some example use cases are:

• Restaurant reservations
• Car rental pickup time
• Hotel check in time

There are plenty of times where the timezone should not be used (default’s to client time):

• Scheduling a Zoom meeting
• Setting a reminder notification
• Creating a calendar event

In the example below, a user needs to pickup a rental car in Kolkata, India after an international flight. The user looks at their ticket — the flight arrives in Kolkata at 1:45 PM. They’d like to pick the car up 45 minutes later at 2:30 PM. These facts are true no matter where in the world the user is booking the trip from. In this case, we should set the timezone to Asia/Kolkata. The offset in Kolkata is +5:30 — so selecting 2:30 PM in Kolkata is equivalent to 09:00 AM UTC:

Disabling dates

It is often necessary to disable specific dates in the datepicker. There are three ways to disable dates in the datepicker:

• min-date - a prop to control what the first available date is.
• max-date - a prop to control what the last available date is.
• disabled-dates - a prop to control whether or not any arbitrary date should be disabled.

Any date that is disabled cannot be selected in the datepicker’s pop up, however an unavailable date can still be set as the initial value or by typing it into the input (when it isn’t in picker-only mode). To handle these edge cases the datepicker has a built-in validation rule (that cannot be disabled) that ensures only valid dates can be submitted. The validation rule’s key is invalidDate.

Min date

Often it is necessary to disable dates that are prior to a particular date. For example, booking a hotel room should only happen for dates in the future. To do this, use the min-date prop with either an ISO8601 compatible string or a native Date object:

Max date

To disable all dates after a given date, use the max-date prop. For example, a birthday selector should only allow past dates. To do this, use the max-date prop with either an ISO8601 compatible string or a native Date object:

Disabled days

Often our applications require substantially more granularity when disabling dates than min-date and max-date allows. The datepicker allows fine-grained control by leveraging the disabled-days prop.

The disabled-days prop expects a function that is passed 2 arguments: the core node and a Date object. The responsibility of the function is to return a boolean indicating if the date is disabled (true is disabled).

The disabled-days prop supersedes min-date and max-date — you can choose to re-implement the base functionality by accessing node.props.minDate or node.props.maxDate.

Example: disabled weekends

Example: fetch from API

Scan for availability

When navigating the calendar pop up via keyboard, the datepicker will not allow you to select a disabled date. However this can be annoying as it can create areas of inaccessibility if some available dates are "sandwiched" between unavailable dates.

To make the user experience better, the datepicker will automatically scan forward or backward (depending on the direction desired) for the next available date to select. The maximum number of days to scan for an available day is controlled by the maxScan prop (7 days by default):

Example: max-scan

Props & Attributes

Sections

You can target a specific section of an input using that section's "key", allowing you to modify that section's classes, HTML (via :sections-schema), or content (via slots). Read more about sections here.

Overlay

This section is located inside the inner section when the overlay prop is added.

Years panel

The panel appears below the input element inside the inner section when the datepicker popup is open.

Months panel

The panel appears below the input element inside the inner section when the datepicker popup is open.

Day panel

The panel appears below the input element inside the inner section when the datepicker popup is open.

Time panel

The panel appears below the input element inside the inner section when the datepicker popup is open.

Section keys