> Markdown version of [Date Time Picker](https://vaadin.com/docs/v14/ds/components/date-time-picker). Section index: [llms.txt](https://vaadin.com/docs/v14/ds/llms.txt)

# Date Time Picker

Date Time Picker is an input field for selecting both a date and a time.

`DateTimePickerBasic.java`

```java
DateTimePicker dateTimePicker = new DateTimePicker();
dateTimePicker.setLabel("Meeting date and time");
add(dateTimePicker);
```

The date and time can be entered directly using a 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.

## <a id="common-input-field-features"></a>Common Input Field Features

Date Time Picker includes all Text Field and shared input field features.

- [See Text Field features](https://vaadin.com/docs/v14/ds/components/text-field.md)

- [See shared input field features](https://vaadin.com/docs/v14/ds/components/input-fields.md)

## <a id="step"></a>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`). Note that, unlike with [Number Field](https://vaadin.com/docs/v14/ds/components/number-field.md), Date Time Picker accepts values that do not align with the specified step.

`DateTimePickerMinutesStep.java`

```java
DateTimePicker dateTimePicker = new DateTimePicker();
dateTimePicker.setLabel("Meeting date and time");
dateTimePicker.setStep(Duration.ofMinutes(30));
dateTimePicker.setValue(LocalDateTime.of(2020, 6, 12, 12, 30, 0));
add(dateTimePicker);
```

> **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"* is not.

The displayed time format changes based on the step.

`DateTimePickerSecondsStep.java`

```java
DateTimePicker dateTimePicker = new DateTimePicker();
dateTimePicker.setLabel("Message received");
dateTimePicker.setStep(Duration.ofSeconds(1));
dateTimePicker.setValue(LocalDateTime.of(2020, 6, 12, 15, 45, 8));
add(dateTimePicker);
```

| 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 does not appear for steps less than 900 seconds (15 minutes) to avoid showing an impractical number of choices.

## <a id="auto-open"></a>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 that to only open the overlay when the toggle button or Up/Down arrow keys are pressed.

`DateTimePickerAutoOpen.java`

```java
dateTimePicker.setAutoOpen(false);
```

## <a id="validation"></a>Validation

### <a id="min-max-value"></a>Min & Max Value

You can define a min and max value for Date Time Picker if you need to restrict the input to a specific range:

`DateTimePickerMinMax.java`

```java
DateTimePicker dateTimePicker = new DateTimePicker();
dateTimePicker.setLabel("Appointment date and time");
dateTimePicker.setHelperText("Must be within 60 days from today");
dateTimePicker.setAutoOpen(true);
dateTimePicker.setMin(LocalDateTime.now());
dateTimePicker.setMax(LocalDateTime.now().plusDays(60));
dateTimePicker.setValue(LocalDateTime.now().plusDays(7));
add(dateTimePicker);
```

### <a id="custom-validation"></a>Custom Validation

If the min and max values are not enough, you can also apply custom validation.

`DateTimePickerCustomValidation.java`

```java
DateTimePicker dateTimePicker = new DateTimePicker();
dateTimePicker.setLabel("Appointment date and time");
dateTimePicker.setHelperText("Open Mondays-Fridays, 8:00-12:00, 13:00-16:00");
dateTimePicker.setStep(Duration.ofMinutes(30));
add(dateTimePicker);

Binder<Appointment> binder = new Binder<>(Appointment.class);
binder.forField(dateTimePicker).withValidator(startDateTime -> {
    boolean validWeekDay = startDateTime.getDayOfWeek().getValue() >= 1
            && startDateTime.getDayOfWeek().getValue() <= 5;
    return validWeekDay;
}, "The selected day of week is not available").withValidator(startDateTime -> {
    LocalTime startTime = LocalTime.of(startDateTime.getHour(), startDateTime.getMinute());
    boolean validTime = !(LocalTime.of(8, 0).isAfter(startTime)
            || (LocalTime.of(12, 0).isBefore(startTime) && LocalTime.of(13, 0).isAfter(startTime))
            || LocalTime.of(16, 0).isBefore(startTime));
    return validTime;
}, "The selected time is not available").bind(Appointment::getStartDateTime, Appointment::setStartDateTime);
```

## <a id="week-numbers"></a>Week Numbers

You can configure Date Time Picker to show week numbers in the date picker overlay.

`DateTimePickerWeekNumbers.java`

```java
dateTimePicker.setWeekNumbersVisible(true);
dateTimePicker.setDatePickerI18n(new DatePicker.DatePickerI18n().setFirstDayOfWeek(1));
```

The week numbers are displayed according to [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html). Please note that they can only be displayed when the first day of the week is Monday.

## <a id="initial-position"></a>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 minimise the need for any additional navigation and/or scrolling when the user’s input is expected to be within a certain time frame.

`DateTimePickerInitialPosition.java`

```java
// https://github.com/vaadin/vaadin-date-time-picker/issues/57
DateTimeFormatter formatter = DateTimeFormatter.ISO_DATE;
LocalDate startOfNextMonth = LocalDate.now(ZoneId.systemDefault())
        .with(TemporalAdjusters.firstDayOfNextMonth());
String startOfNextMonthIsoString = formatter.format(startOfNextMonth);

dateTimePicker.getElement().executeJs(
        "this.initialPosition = $0",
        startOfNextMonthIsoString
);
```

## <a id="usage-patterns"></a>Usage Patterns

### <a id="date-time-range"></a>Date Time Range

You can accomplish a date time range picker using two Date Time Pickers.

`DateTimePickerRange.java`

```java
DateTimePicker startDateTimePicker = new DateTimePicker("Start date and time");
startDateTimePicker.setValue(LocalDateTime.of(2020, 8, 25, 20, 0, 0));

DateTimePicker endDateTimePicker = new DateTimePicker("End date and time");
endDateTimePicker.setValue(LocalDateTime.of(2020, 9, 1, 20, 0, 0));

startDateTimePicker.addValueChangeListener(e -> endDateTimePicker.setMin(e.getValue()));

add(startDateTimePicker, endDateTimePicker);
```

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.

## <a id="best-practises"></a>Best Practises

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](https://vaadin.com/docs/v14/ds/components/date-picker.md) and [Time Picker](https://vaadin.com/docs/v14/ds/components/time-picker.md) respectively.

### <a id="picking-vs-typing"></a>Picking vs Typing

The calendar overlay is useful when the users need to choose a day that is close to the current date or when information such as day of the week, week number, and valid dates, etc. can aid in choosing the best option.

For days well in the past or future, and for known dates such as birthdays, typing the date can be the faster and easier approach. It is important to verify that the user can enter dates according to their locale.

### <a id="input-format"></a>Input Format

<!-- vale Google.DateFormat = NO --><!-- vale Microsoft.DateOrder = NO -->

Use a placeholder or helper to show how the input should be formatted. This is important for the date picker if the overlay is disabled and/or when supporting multiple locales. For example, 12/6/2020 does not represent the same date for Americans as it does Europeans.

<!-- vale Google.DateFormat = YES --><!-- vale Microsoft.DateOrder = YES -->

`DateTimePickerInputFormat.java`

```java
DateTimePicker dateTimePicker = new DateTimePicker();
dateTimePicker.setLabel("Select date and time");
dateTimePicker.setHelperText("Format: DD/MM/YYYY and HH:MM");
dateTimePicker.setDatePlaceholder("DD/MM/YYYY");
dateTimePicker.setTimePlaceholder("HH:MM");
add(dateTimePicker);
```

Helpers are generally preferable to placeholders, as they are always visible, thereby requiring less short-term memory. Fields with placeholders are also less noticeable than empty fields and susceptible to being skipped.

Use placeholders when space is limited, for example, when Date Time Picker is used as a grid filter.

## <a id="related-components"></a>Related Components

| Component                                                               | Usage recommendations                                  |
| ----------------------------------------------------------------------- | ------------------------------------------------------ |
| [Time Picker](https://vaadin.com/docs/v14/ds/components/time-picker.md) | Input field for entering or selecting a specific time. |
| [Date Picker](https://vaadin.com/docs/v14/ds/components/date-picker.md) | Input field for entering or selecting a specific date. |

`FC3082C2-94F9-4A2A-BA33-5C0A903BC9FA`