--- title: DatePicker description: DatePicker element: vaadin-date-picker --- ## Description `` is an input field that allows to enter a date by typing or by selecting from a calendar overlay. ```html ``` ```js datePicker.value = '2016-03-02'; ``` When the selected `value` is changed, a `value-changed` event is triggered. ### Styling The following custom properties are available for styling: Custom property | Description | Default -------------------------------|----------------------------|--------- `--vaadin-field-default-width` | Default width of the field | `12em` The following shadow DOM parts are available for styling: Part name | Description ---------------------|---------------- `label` | The label element `input-field` | The element that wraps prefix, value and buttons `field-button` | Set on both clear and toggle buttons `clear-button` | The clear button `error-message` | The error message element `helper-text` | The helper text element wrapper `required-indicator` | The `required` state indicator element `toggle-button` | The toggle button `backdrop` | Backdrop of the overlay `overlay` | The overlay container `content` | The overlay content The following state attributes are available for styling: Attribute | Description ---------------------|--------------------------------- `disabled` | Set when the element is disabled `has-value` | Set when the element has a value `has-label` | Set when the element has a label `has-helper` | Set when the element has helper text or slot `has-error-message` | Set when the element has an error message `has-tooltip` | Set when the element has a slotted tooltip `invalid` | Set when the element is invalid `focused` | Set when the element is focused `focus-ring` | Set when the element is keyboard focused `readonly` | Set when the element is readonly `opened` | Set when the overlay is opened `week-numbers` | Set when week numbers are shown in the calendar ### Internal components In addition to `` itself, the following internal components are themable: - `` - `` - `` - `` - `` In order to style the overlay content, use `` shadow DOM parts: Part name | Description ----------------------|-------------------- `years-toggle-button` | Fullscreen mode years scroller toggle `toolbar` | Toolbar with slotted buttons The following state attributes are available on the `` element: Attribute | Description ----------------|------------------------------------------------- `desktop` | Set when the overlay content is in desktop mode `fullscreen` | Set when the overlay content is in fullscreen mode `years-visible` | Set when the year scroller is visible in fullscreen mode In order to style the month calendar, use `` shadow DOM parts: Part name | Description ----------------------|-------------------- `month-header` | Month title `weekdays` | Weekday container `weekday` | Weekday element `week-numbers` | Week numbers container `week-number` | Week number element `date` | Date element `disabled` | Disabled date element `focused` | Focused date element `selected` | Selected date element `today` | Date element corresponding to the current day `past` | Date element corresponding to the date in the past `future` | Date element corresponding to the date in the future In order to style year scroller elements, use `` shadow DOM parts: Part name | Description ----------------------|-------------------- `year-number` | Year number `year-separator` | Year separator 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 ## 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. ### allowedCharPattern **Type:** `string` A pattern matched against individual characters the user inputs. When set, the field will prevent: - `keydown` events if the entered key doesn't match `/^allowedCharPattern$/` - `paste` events if the pasted text doesn't match `/^allowedCharPattern*$/` - `drop` events if the dropped text doesn't match `/^allowedCharPattern*$/` For example, to allow entering only numbers and minus signs, use: `allowedCharPattern = "[\\d-]"` ### autofocus **Type:** `boolean` Specify that this control should have input focus when the page loads. ### autoOpenDisabled **Type:** `boolean | null | undefined` Set true to prevent the overlay from opening automatically. ### autoselect **Type:** `boolean` If true, the input text gets fully selected when the field is focused using click or touch / tap. ### clearButtonVisible **Type:** `boolean` Set to true to display the clear icon which clears the input. It is up to the component to choose where to place the clear icon: in the Shadow DOM or in the light DOM. In any way, a reference to the clear icon element should be provided via the `clearElement` getter. ### 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:** `DatePickerI18n` 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 JSON structure and default values: ```js { // An array with the full names of months starting // with January. monthNames: [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December' ], // An array of weekday names starting with Sunday. Used // in screen reader announcements. weekdays: [ 'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday' ], // An array of short weekday names starting with Sunday. // Displayed in the calendar. weekdaysShort: [ 'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat' ], // An integer indicating the first day of the week // (0 = Sunday, 1 = Monday, etc.). firstDayOfWeek: 0, // Translation of the Today shortcut button text. today: 'Today', // Translation of the Cancel button text. cancel: 'Cancel', // 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: '', // 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. formatDate: d => { // returns a string representation of the given // object in 'MM/DD/YYYY' -format }, // 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. parseDate: text => { // Parses a string in 'MM/DD/YY', 'MM/DD' or 'DD' -format to // an `Object` in the format `{ day: ..., month: ..., year: ... }`. } // A function to format given `monthName` and // `fullYear` integer as calendar title string. formatTitle: (monthName, fullYear) => { return monthName + ' ' + fullYear; } } ``` See also: [DatePickerI18n](#datepickeri18n) ### initialPosition **Type:** `string | null | undefined` Date which should be visible when there is no value selected. The same date formats as for the `value` property are supported. ### invalid **Type:** `boolean` Set to true when the field is invalid. ### isDateDisabled **Type:** `(date: DatePickerDate) => boolean` A function to be used to determine whether the user can select a given date. Receives a `DatePickerDate` object of the date to be selected and should return a boolean. See also: [DatePickerDate](#datepickerdate) ### 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 date that can be selected. All later dates will be disabled. Supported date formats: - ISO 8601 `"YYYY-MM-DD"` (default) - 6-digit extended ISO 8601 `"+YYYYYY-MM-DD"`, `"-YYYYYY-MM-DD"` ### min **Type:** `string | undefined` The earliest date that can be selected. All earlier dates will be disabled. Supported date formats: - ISO 8601 `"YYYY-MM-DD"` (default) - 6-digit extended ISO 8601 `"+YYYYYY-MM-DD"`, `"-YYYYYY-MM-DD"` ### name **Type:** `string` The name of this field. ### opened **Type:** `boolean | null | undefined` Set true to open the date selector overlay. ### placeholder **Type:** `string` A hint to the user of what can be entered in the field. ### readonly **Type:** `boolean` When present, it specifies that the field is 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). ### title **Type:** `string` The text usually displayed in a tooltip popup when the mouse is over the field. ### value **Type:** `string` Selected date. Supported date formats: - ISO 8601 `"YYYY-MM-DD"` (default) - 6-digit extended ISO 8601 `"+YYYYYY-MM-DD"`, `"-YYYYYY-MM-DD"` ## Methods ### checkValidity **Type:** `(() => boolean) & (() => boolean)` Returns true if the current input value satisfies all constraints (if any) Override the `checkValidity` method for custom validations. ### clear **Type:** `() => void` Clear the value of the field. ### close **Type:** `() => void` Closes the dropdown. ### open **Type:** `() => void` Opens the dropdown. ### 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:** [DatePickerChangeEvent](#datepickerchangeevent) Fired when the user commits a value change. ### input **Type:** `CustomEvent` Fired when the value is changed by the user: on every typing keystroke, and the value is cleared using the clear button. ### invalid-changed **Type:** [DatePickerInvalidChangedEvent](#datepickerinvalidchangedevent) Fired when the `invalid` property changes. ### opened-changed **Type:** [DatePickerOpenedChangedEvent](#datepickeropenedchangedevent) Fired when `opened` property value changes. ### validated **Type:** [DatePickerValidatedEvent](#datepickervalidatedevent) Fired whenever the field is validated. ### value-changed **Type:** [DatePickerValueChangedEvent](#datepickervaluechangedevent) Fired when `value` property value changes. ## Types ### DatePickerChangeEvent ```ts /** * Fired when the user commits a value change. */ export type DatePickerChangeEvent = Event & { target: DatePicker; }; ``` ### 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; } ``` ### DatePickerInvalidChangedEvent ```ts /** * Fired when the `invalid` property changes. */ export type DatePickerInvalidChangedEvent = CustomEvent<{ value: boolean }>; ``` ### DatePickerOpenedChangedEvent ```ts /** * Fired when the `opened` property changes. */ export type DatePickerOpenedChangedEvent = CustomEvent<{ value: boolean }>; ``` ### DatePickerValidatedEvent ```ts /** * Fired whenever the field is validated. */ export type DatePickerValidatedEvent = CustomEvent<{ valid: boolean }>; ``` ### DatePickerValueChangedEvent ```ts /** * Fired when the `value` property changes. */ export type DatePickerValueChangedEvent = CustomEvent<{ value: string }>; ```