--- title: DateTimePicker description: DateTimePicker element: vaadin-date-time-picker --- ## Description `` is a Web Component providing a date time selection field. ```html ``` ```js 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 `` and placed in light DOM: - [``](/elements/vaadin-date-picker). - [``](/elements/vaadin-time-picker). See [Styling Components](https://vaadin.com/docs/latest/styling/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 ### accessibleName **Type:** `string | null | undefined` String used to label the component to screen reader users. ### accessibleNameRef **Type:** `string | null | undefined` Id of the element used as label of the component to 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. ### datePlaceholder **Type:** `string | null | undefined` A placeholder string for the date field. ### 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: ```js { // 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 [``](/elements/vaadin-date-picker) and [``](/elements/vaadin-time-picker) are supported. See also: [DateTimePickerI18n](#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. ### 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](#datetimepickerchangeevent) Fired when the user commits a value change. ### invalid-changed **Type:** [DateTimePickerInvalidChangedEvent](#datetimepickerinvalidchangedevent) Fired when the `invalid` property changes. ### validated **Type:** [DateTimePickerValidatedEvent](#datetimepickervalidatedevent) Fired whenever the field is validated. ### value-changed **Type:** [DateTimePickerValueChangedEvent](#datetimepickervaluechangedevent) Fired when the `value` property changes. ## Types ### DatePickerDate ```ts export interface DatePickerDate { day: number; month: number; year: number; } ``` ### DatePickerI18n ```ts 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; /** * 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 ```ts /** * Fired when the user commits a value change. */ export type DateTimePickerChangeEvent = Event & { target: DateTimePicker; }; ``` ### DateTimePickerI18n ```ts 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 ```ts /** * Fired when the `invalid` property changes. */ export type DateTimePickerInvalidChangedEvent = CustomEvent<{ value: boolean }>; ``` ### DateTimePickerValidatedEvent ```ts /** * Fired whenever the field is validated. */ export type DateTimePickerValidatedEvent = CustomEvent<{ valid: boolean }>; ``` ### DateTimePickerValueChangedEvent ```ts /** * Fired when the `value` property changes. */ export type DateTimePickerValueChangedEvent = CustomEvent<{ value: string }>; ``` ### TimePickerI18n ```ts export interface TimePickerI18n { parseTime?(time: string): TimePickerTime | undefined; formatTime?(time: TimePickerTime | undefined): string; } ``` ### TimePickerTime ```ts /** * @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; } ```