Date Time Picker
- Common Input Field Features
- Step
- Auto Open
- Validation
- Week Numbers
- Initial Position
- Internationalization (i18n)
- Usage Patterns
- Best Practices
- Related Components
Date Time Picker is an input field for selecting both a date and a time.
The date and time can be entered directly using the keyboard in the format of the current locale or through the Date Time Picker’s two overlays. The overlays open when their respective fields are clicked or any input is entered when the fields are focused.
Common Input Field Features
Date Time Picker includes all Text Field and shared input field features.
Step
Date Time Picker’s step parameter defines the time interval (in seconds) between the items displayed in the time picker overlay. It also specifies the amount by which the time increases/decreases using the up/down arrow keys (when the overlays are disabled).
The default step is one hour (that is, 3600).
Unlike with Number Field, Date Time Picker accepts values that don’t align with the specified step.
new tab
<vaadin-date-time-picker
label="Meeting date and time"
value="2020-06-12T12:30"
.step="${60 * 30}"
></vaadin-date-time-picker>|
Note
|
Use even steps
The step must divide an hour or day evenly.
For example, "15 minutes", "30 minutes" and "2 hours" are valid steps, while "42 minutes" isn’t.
|
The displayed time format changes based on the step.
new tab
<vaadin-date-time-picker
label="Message received"
value="2020-06-12T15:45:08"
step="1"
></vaadin-date-time-picker>| Step | Format |
|---|---|
Less than 60 seconds | HH:MM:SS |
Less than 1 second | HH:MM:SS:FFF |
|
Note
|
Limit the number of steps
The overlay doesn’t appear for steps less than 900 seconds (15 minutes) to avoid showing an impractical number of choices.
|
Auto Open
The overlay opens automatically when the field is focused using a pointer (mouse or touch), or when the user types in the field. You can disable this, so that the overlay opens only when the toggle button or up/down arrow keys are pressed.
new tab
<vaadin-date-time-picker
label="Meeting date and time"
auto-open-disabled
></vaadin-date-time-picker>Validation
Min and Max Values
You can define a min and max value for Date Time Picker if you need to restrict the input to a specific range:
new tab
<vaadin-date-time-picker
label="Appointment date and time"
helper-text="Must be within 60 days from today"
.value="${format(this.initialValue, dateTimeFormat)}"
.min="${format(this.minDate, dateTimeFormat)}"
.max="${format(this.maxDate, dateTimeFormat)}"
.errorMessage="${this.errorMessage}"
@change="${({ target }: DateTimePickerChangeEvent) => {
const date = parseISO(target.value ?? '');
if (isBefore(date, this.minDate)) {
this.errorMessage = 'Too early, choose another date and time';
} else if (isAfter(date, this.maxDate)) {
this.errorMessage = 'Too late, choose another date and time';
} else {
this.errorMessage = '';
}
}}"
></vaadin-date-time-picker>Custom Validation
If the min and max values aren’t enough, you can also apply custom validation.
new tab
private binder = new Binder(this, AppointmentModel);
private errorMessage = 'The selected day of week or time is not available';
protected override firstUpdated() {
this.binder.for(this.binder.model.startDateTime).addValidator({
message: this.errorMessage,
validate: (startDateTime: string) => {
const date = new Date(startDateTime);
const validWeekDay = date.getDay() >= 1 && date.getDay() <= 5;
return validWeekDay;
},
});
this.binder.for(this.binder.model.startDateTime).addValidator({
message: this.errorMessage,
validate: (startDateTime: string) => {
const time = startDateTime.split('T')[1];
const validTime =
(time >= '08:00' && time <= '12:00') || (time >= '13:00' && time <= '16:00');
return validTime;
},
});
}
protected override render() {
return html`
<vaadin-date-time-picker
label="Appointment date and time"
helper-text="Open Mondays-Fridays, 8:00-12:00, 13:00-16:00"
.step="${60 * 30}"
${field(this.binder.model.startDateTime)}
></vaadin-date-time-picker>
`;
}Week Numbers
You can configure Date Time Picker to show week numbers in the date picker overlay.
new tab
@query('vaadin-date-time-picker')
private dateTimePicker!: DateTimePicker;
protected override firstUpdated() {
this.dateTimePicker.i18n = {
...this.dateTimePicker.i18n,
firstDayOfWeek: 1,
};
}
protected override render() {
return html`
<vaadin-date-time-picker
label="Meeting date and time"
show-week-numbers
></vaadin-date-time-picker>
`;
}The week numbers are displayed according to ISO-8601. They can only be displayed when the first day of the week is Monday.
Initial Position
Date Time Picker’s initial position parameter defines which date is focused in the calendar overlay when the overlay is opened. Use this feature to minimize the need for any additional navigation and/or scrolling when the user’s input is expected to be between certain dates.
new tab
<vaadin-date-time-picker
label="Meeting date and time"
.initialPosition="${startOfNextMonthISOString}"
></vaadin-date-time-picker>Internationalization (i18n)
Date Time Picker allows localizing texts and labels, such as month names and button labels.
new tab
@query('vaadin-date-time-picker')
private dateTimePicker!: DateTimePicker;
protected override firstUpdated() {
this.dateTimePicker.i18n = {
...this.dateTimePicker.i18n,
monthNames: [
'Januar',
'Februar',
'März',
'April',
'Mai',
'Juni',
'Juli',
'August',
'September',
'Oktober',
'November',
'Dezember',
],
weekdays: ['Sonntag', 'Montag', 'Dienstag', 'Mittwoch', 'Donnerstag', 'Freitag', 'Samstag'],
weekdaysShort: ['So', 'Mo', 'Di', 'Mi', 'Do', 'Fr', 'Sa'],
week: 'Woche',
today: 'Heute',
cancel: 'Abbrechen',
};
}
protected override render() {
return html`<vaadin-date-time-picker label="Sitzungsdatum"></vaadin-date-time-picker>`;
}See also how to configure a custom date format.
Usage Patterns
Date Time Range
You can accomplish a date time range picker using two Date Time Pickers.
new tab
<div>
<vaadin-date-time-picker
label="Start date and time"
.value="${this.startDateTime}"
@value-changed="${(event: DateTimePickerValueChangedEvent) => {
this.startDateTime = event.detail.value;
}}"
></vaadin-date-time-picker>
<vaadin-date-time-picker
label="End date and time"
.min="${this.startDateTime}"
.value="${this.endDateTime}"
@value-changed="${(event: DateTimePickerValueChangedEvent) => {
this.endDateTime = event.detail.value;
}}"
></vaadin-date-time-picker>
</div>To disable the days before the start date in the end date picker, you need to handle the selection in the start date picker and change the range in the end date picker.
Best Practices
Use Date Time Picker when the user needs to choose both a date and time of day. If you only need a date or time of day, use Date Picker or Time Picker respectively.
Picking vs Typing
The calendar overlay is useful when the user needs to choose a day that’s close to the current date or when information such as day of the week, week number, valid dates, and so on, can aid in choosing the best option.
For days well into the past or future, and for known dates such as birthdays, typing the date can be a faster and easier approach. It’s important to verify that the user can enter dates according to their locale.
Providing Input Guidance
Use a helper text to show the expected date and time formats, and placeholders to help users identify the two sub-fields correctly.
new tab
<vaadin-date-time-picker
label="Select date and time"
helper-text="Format: DD/MM/YYYY and HH:MM"
date-placeholder="Date"
time-placeholder="Time"
></vaadin-date-time-picker>