DateTimePicker

Description #

<vaadin-date-time-picker> is a Web Component providing a date time selection field.

<vaadin-date-time-picker value="2019-09-16T15:00"></vaadin-date-time-picker>

dateTimePicker.value = '2019-09-16T15:00';

When the selected value is changed, a value-changed event is triggered.

Styling #

The following shadow DOM parts are available for styling:

Part name	Description
label	The slotted label element wrapper
input-fields	The date and time pickers wrapper
helper-text	The slotted helper text element wrapper
error-message	The slotted error message element wrapper
required-indicator	The required state indicator element

The following state attributes are available for styling:

Attribute	Description
disabled	Set when the element is disabled
focused	Set when the element is focused
focus-ring	Set when the element is keyboard focused
readonly	Set when the element is readonly
invalid	Set when the element is invalid
has-label	Set when the element has a label
has-value	Set when the element has a value
has-helper	Set when the element has helper text
has-error-message	Set when the element has an error message
has-tooltip	Set when the element has a slotted tooltip

The following custom CSS properties are available for styling:

Custom CSS property
--vaadin-date-time-picker-gap
--vaadin-input-field-error-color
--vaadin-input-field-error-font-size
--vaadin-input-field-error-font-weight
--vaadin-input-field-error-line-height
--vaadin-input-field-label-color
--vaadin-input-field-label-font-size
--vaadin-input-field-label-font-weight
--vaadin-input-field-label-line-height
--vaadin-input-field-helper-color
--vaadin-input-field-helper-font-size
--vaadin-input-field-helper-font-weight
--vaadin-input-field-helper-line-height
--vaadin-input-field-required-indicator-color
--vaadin-input-field-required-indicator

Internal components #

The following components are created by <vaadin-date-time-picker> and placed in light DOM:

• <vaadin-date-picker>.
• <vaadin-time-picker>.

See Styling Components documentation.

Change events #

Depending on the nature of the value change that the user attempts to commit e.g. by pressing Enter, the component can fire either a change event or an unparsable-change event:

Value change	Event
empty => parsable	change
empty => unparsable	unparsable-change
parsable => empty	change
parsable => parsable	change
parsable => unparsable	change
unparsable => empty	unparsable-change
unparsable => parsable	change
unparsable => unparsable	unparsable-change
incomplete => empty	unparsable-change
incomplete => parsable	change
incomplete => unparsable	unparsable-change
empty => incomplete	unparsable-change
parsable => incomplete	change
unparsable => incomplete	unparsable-change

Properties #

accessibleDescriptionRef #

Type: string | null | undefined

A space-separated list of IDs referencing the elements that describe the component for screen reader users. The referenced elements are announced in addition to the helper text and the error message.

accessibleName #

Type: string | null | undefined

String used to label the component for screen reader users.

accessibleNameRef #

Type: string | null | undefined

A space-separated list of IDs referencing the elements that label the component for screen reader users.

autofocus #

Type: boolean

Specify that this control should have input focus when the page loads.

autoOpenDisabled #

Type: boolean | null | undefined

Set to true to prevent the overlays from opening automatically.

dateMetadataProvider #

Type: DatePickerDateMetadataProvider | null | undefined

A function that provides metadata for the dates the calendar is about to render: whether they are disabled, and CSS part names for styling from outside using the ::part() selector. The provider is called for a range of dates at a time, and again as the calendar renders further dates.

It receives a DatePickerDateRange and returns an array of DatePickerDateMetadata objects for the dates in that range that have metadata. It can return a Promise to load the metadata asynchronously, and null or undefined when no date in the range has metadata.

The returned array has the following structure:

[
  // The date is an ISO 8601 string.
  { date: '2026-01-01', disabled: true },

  // Adds a custom part name to the date.
  { date: '2026-01-02', part: 'busy' },
]

A date is disabled if its metadata marks it disabled, or it is outside min and max. Disabled dates are not selectable, and a value on a disabled date makes the field invalid. The provider does not affect which date is focused when opening the overlay. Use initialPosition property to provide a selectable date.

While a returned Promise is pending, the dates it covers are not disabled yet and render with the loading part. If the function throws or rejects, corresponding dates are requested again the next time the user navigates.

The provider is used for validation also when the overlay is closed. Date is considered valid while the provider is pending. Unlike <vaadin-date-picker>, the value is not re-validated when the metadata is loaded, but checked against it at the next validation instead.

Keep a stable reference to the function: assigning a new one clears the cache and re-fetches visible range. Call clearCache() to re-fetch when the data behind the same function changed.

See also: DatePickerDateMetadataProvider

datePlaceholder #

Type: string | null | undefined

A placeholder string for the date field.

defaultTime #

Type: string | null | undefined

The time part to set automatically when the user commits a date while the time picker is empty.

Supports same time formats as the value property, without the date part. Precision exceeding the one defined by step is discarded, e.g. 09:30:45 is applied as 09:30 with the default step.

The time part is set when a date is committed while the time picker is empty — never for programmatic or initial values. A value outside min / max is applied as-is and makes the field invalid.

When not set, selecting a date leaves the time part empty. A string that is not a valid ISO 8601 time is ignored and logs a warning.

disabled #

Type: boolean

If true, the user cannot interact with this element.

errorMessage #

Type: string | null | undefined

Error to show when the field is invalid.

helperText #

Type: string | null | undefined

String used for the helper text.

i18n #

Type: DateTimePickerI18n

The object used to localize this component. To change the default localization, replace this with an object that provides all properties, or just the individual properties you want to change.

The object has the following structure and default values:

{
  // Accessible label to the date picker.
  // The property works in conjunction with label and accessibleName defined on the field.
  // If both properties are defined, then accessibleName takes precedence.
  // Then, the dateLabel value is concatenated with it.
  dateLabel: undefined;

  // Accessible label to the time picker.
  // The property works in conjunction with label and accessibleName defined on the field.
  // If both properties are defined, then accessibleName takes precedence.
  // Then, the dateLabel value is concatenated with it.
  timeLabel: undefined;
}

Additionally, all i18n properties from <vaadin-date-picker> and <vaadin-time-picker> are supported.

See also: DateTimePickerI18n

initialPosition #

Type: string | null | undefined

Date which should be visible in the date picker overlay when there is no value selected.

The same date formats as for the value property are supported but without the time part.

invalid #

Type: boolean

Set to true when the field is invalid.

label #

Type: string | null | undefined

The label text for the input node. When no light dom defined via [slot=label], this value will be used.

manualValidation #

Type: boolean

Set to true to enable manual validation mode. This mode disables automatic constraint validation, allowing you to control the validation process yourself. You can still trigger constraint validation manually with the validate() method or use checkValidity() to assess the component's validity without affecting the invalid state. In manual validation mode, you can also manipulate the invalid property directly through your application logic without conflicts with the component's internal validation.

max #

Type: string | undefined

The latest value (date and time) that can be selected. All later values will be disabled.

Supported date time format is based on ISO 8601 (without a time zone designator):

• Minute precision "YYYY-MM-DDThh:mm"
• Second precision "YYYY-MM-DDThh:mm:ss"
• Millisecond precision "YYYY-MM-DDThh:mm:ss.fff"

min #

Type: string | undefined

The earliest allowed value (date and time) that can be selected. All earlier values will be disabled.

Supported date time format is based on ISO 8601 (without a time zone designator):

• Minute precision "YYYY-MM-DDThh:mm"
• Second precision "YYYY-MM-DDThh:mm:ss"
• Millisecond precision "YYYY-MM-DDThh:mm:ss.fff"

name #

Type: string | null | undefined

The name of the control, which is submitted with the form data.

readonly #

Type: boolean

Set to true to make this element read-only.

required #

Type: boolean

Specifies that the user must fill in a value.

showWeekNumbers #

Type: boolean | null | undefined

Set true to display ISO-8601 week numbers in the calendar. Notice that displaying week numbers is only supported when i18n.firstDayOfWeek is 1 (Monday).

step #

Type: number | null | undefined

Defines the time interval (in seconds) between the items displayed in the time selection box. The default is 1 hour (i.e. 3600).

It also configures the precision of the time part of the value string. By default the component formats time values as hh:mm but setting a step value lower than one minute or one second, format resolution changes to hh:mm:ss and hh:mm:ss.fff respectively.

Unit must be set in seconds, and for correctly configuring intervals in the dropdown, it need to evenly divide a day.

Note: it is possible to define step that is dividing an hour in inexact fragments (i.e. 5760 seconds which equals 1 hour 36 minutes), but it is not recommended to use it for better UX.

timePlaceholder #

Type: string | null | undefined

A placeholder string for the time field.

value #

Type: string

The value for this element.

Supported date time format is based on ISO 8601 (without a time zone designator):

• Minute precision "YYYY-MM-DDThh:mm" (default)
• Second precision "YYYY-MM-DDThh:mm:ss"
• Millisecond precision "YYYY-MM-DDThh:mm:ss.fff"

Methods #

checkValidity #

Type: () => boolean

Returns true if the current input value satisfies all constraints (if any)

You can override the checkValidity method for custom validations.

clearCache #

Type: () => void

Clears the dateMetadataProvider cache and reloads the date metadata.

validate #

Type: () => boolean

Validates the field and sets the invalid property based on the result.

The method fires a validated event with the result of the validation.

Events #

change #

Type: DateTimePickerChangeEvent

Fired when the user commits a value change.

invalid-changed #

Type: DateTimePickerInvalidChangedEvent

Fired when the invalid property changes.

unparsable-change #

Type: DateTimePickerUnparsableChangeEvent

Fired when the user commits an unparsable or incomplete value change and there is no change event.

validated #

Type: DateTimePickerValidatedEvent

Fired whenever the field is validated.

value-changed #

Type: DateTimePickerValueChangedEvent

Fired when the value property changes.

Types #

DatePickerDate #

export interface DatePickerDate {
  day: number;
  month: number;
  year: number;
}

DatePickerDateMetadata #

/**
 * Metadata for a single date, returned by `dateMetadataProvider`.
 */
export interface DatePickerDateMetadata {
  /**
   * The date the metadata applies to in ISO 8601 format.
   */
  date: string;
  /**
   * Whether the date cannot be selected.
   */
  disabled?: boolean;
  /**
   * Part names to add to the date, so a theme can style it with `::part()`. A single name, or
   * several separated by spaces. Do not use built-in names like `disabled` and `selected`.
   */
  part?: string;
}

DatePickerDateMetadataProvider #

/**
 * A function called with the range of dates the calendar is about to render, returning
 * the metadata for the dates in that range. It can return a `Promise` to load the metadata
 * asynchronously, and `null` or `undefined` when no date in the range has metadata.
 */
export type DatePickerDateMetadataProvider = (
  range: DatePickerDateRange,
) => DatePickerDateMetadata[] | Promise<DatePickerDateMetadata[] | null | undefined> | null | undefined;

DatePickerDateRange #

/**
 * A range of dates that `dateMetadataProvider` is asked about.
 * It can span several months and always covers whole months.
 */
export interface DatePickerDateRange {
  /**
   * The first date of the range (inclusive), as an ISO 8601 date.
   */
  start: string;
  /**
   * The last date of the range (inclusive), as an ISO 8601 date.
   */
  end: string;
}

DatePickerI18n #

export interface DatePickerI18n {
  /**
   * An array with the full names of months starting
   * with January.
   */
  monthNames?: string[];
  /**
   * An array of weekday names starting with Sunday. Used
   * in screen reader announcements.
   */
  weekdays?: string[];
  /**
   * An array of short weekday names starting with Sunday.
   * Displayed in the calendar.
   */
  weekdaysShort?: string[];
  /**
   * An integer indicating the first day of the week
   * (0 = Sunday, 1 = Monday, etc.).
   */
  firstDayOfWeek?: number;
  /**
   * Translation of the Today shortcut button text.
   */
  today?: string;
  /**
   * Translation of the Cancel button text.
   */
  cancel?: string;
  /**
   * Accessible name of the overlay content, announced by screen readers when
   * the overlay opens.
   */
  dialogAccessibleName?: string;
  /**
   * Used for adjusting the year value when parsing dates with short years.
   * The year values between 0 and 99 are evaluated and adjusted.
   * Example: for a referenceDate of 1970-10-30;
   *   dateToBeParsed: 40-10-30, result: 1940-10-30
   *   dateToBeParsed: 80-10-30, result: 1980-10-30
   *   dateToBeParsed: 10-10-30, result: 2010-10-30
   * Supported date format: ISO 8601 `"YYYY-MM-DD"` (default)
   * The default value is the current date.
   */
  referenceDate?: string;

  /**
   * A function to parse the given text to an `Object` in the format `{ day: ..., month: ..., year: ... }`.
   * Must properly parse (at least) text formatted by `formatDate`.
   * Setting the property to null will disable keyboard input feature.
   * Note: The argument month is 0-based. This means that January = 0 and December = 11.
   * @param date
   */
  parseDate?(date: string): DatePickerDate | undefined;

  /**
   * A function to format given `Object` as
   * date string. Object is in the format `{ day: ..., month: ..., year: ... }`
   * Note: The argument month is 0-based. This means that January = 0 and December = 11.
   * @param date
   */
  formatDate?(date: DatePickerDate): string;

  /**
   * A function to format given `monthName` and
   * `fullYear` integer as calendar title string.
   * @param monthName
   * @param fullYear
   */
  formatTitle?(monthName: string, fullYear: number): string;
}

DateTimePickerChangeEvent #

/**
 * Fired when the user commits a value change.
 */
export type DateTimePickerChangeEvent = Event & {
  target: DateTimePicker;
};

DateTimePickerI18n #

export interface DateTimePickerI18n extends DatePickerI18n, TimePickerI18n {
  /**
   * Accessible label to the date picker.
   * The property works in conjunction with label and accessibleName defined on the field.
   * If both properties are defined, then accessibleName takes precedence.
   * Then, the dateLabel value is concatenated with it.
   */
  dateLabel?: string;

  /**
   * Accessible label to the time picker.
   * The property works in conjunction with label and accessibleName defined on the field.
   * If both properties are defined, then accessibleName takes precedence.
   * Then, the dateLabel value is concatenated with it.
   */
  timeLabel?: string;
}

DateTimePickerInvalidChangedEvent #

/**
 * Fired when the `invalid` property changes.
 */
export type DateTimePickerInvalidChangedEvent = CustomEvent<{ value: boolean }>;

DateTimePickerUnparsableChangeEvent #

/**
 * Fired when the user commits an unparsable value change and there is no change event.
 */
export type DateTimePickerUnparsableChangeEvent = CustomEvent;

DateTimePickerValidatedEvent #

/**
 * Fired whenever the field is validated.
 */
export type DateTimePickerValidatedEvent = CustomEvent<{ valid: boolean }>;

DateTimePickerValueChangedEvent #

/**
 * Fired when the `value` property changes.
 */
export type DateTimePickerValueChangedEvent = CustomEvent<{ value: string }>;

TimePickerI18n #

export interface TimePickerI18n {
  parseTime?(time: string): TimePickerTime | undefined;

  formatTime?(time: TimePickerTime | undefined): string;
}

TimePickerTime #

/**
 * @license
 * Copyright (c) 2018 - 2026 Vaadin Ltd.
 * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
 */

export interface TimePickerTime {
  hours: number | string;
  minutes: number | string;
  seconds?: number | string;
  milliseconds?: number | string;
}