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.

Source code

date-time-picker-basic.ts
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@vaadin/date-time-picker';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('date-time-picker-basic')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-date-time-picker label="Meeting date and time"></vaadin-date-time-picker>
      <!-- end::snippet[] -->
    `;
  }
}
DateTimePickerBasic.javapackage com.vaadin.demo.component.datetimepicker;

import com.vaadin.flow.component.datetimepicker.DateTimePicker;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.router.Route;


@Route("date-time-picker-basic")
public class DateTimePickerBasic extends Div {

    public DateTimePickerBasic() {
        // tag::snippet[]
        DateTimePicker dateTimePicker = new DateTimePicker();
        dateTimePicker.setLabel("Meeting date and time");
        add(dateTimePicker);
        // end::snippet[]
    }

}

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.

Open in a
new tab

Source code

date-time-picker-minutes-step.ts
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@vaadin/date-time-picker';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('date-time-picker-minutes-step')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-date-time-picker
        label="Meeting date and time"
        value="2020-06-12T12:30"
        .step="${60 * 30}"
      ></vaadin-date-time-picker>
      <!-- end::snippet[] -->
    `;
  }
}
DateTimePickerMinutesStep.javapackage com.vaadin.demo.component.datetimepicker;

import com.vaadin.flow.component.datetimepicker.DateTimePicker;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.router.Route;

import java.time.Duration;
import java.time.LocalDateTime;


@Route("date-time-picker-minutes-step")
public class DateTimePickerMinutesStep extends Div {

    public DateTimePickerMinutesStep() {
        // tag::snippet[]
        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);
        // end::snippet[]
    }

}

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.

Open in a
new tab

Source code

date-time-picker-seconds-step.ts
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@vaadin/date-time-picker';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('date-time-picker-seconds-step')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-date-time-picker
        label="Message received"
        value="2020-06-12T15:45:08"
        step="1"
      ></vaadin-date-time-picker>
      <!-- end::snippet[] -->
    `;
  }
}
DateTimePickerSecondsStep.javapackage com.vaadin.demo.component.datetimepicker;

import com.vaadin.flow.component.datetimepicker.DateTimePicker;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.router.Route;

import java.time.Duration;
import java.time.LocalDateTime;


@Route("date-time-picker-seconds-step")
public class DateTimePickerSecondsStep extends Div {

    public DateTimePickerSecondsStep() {
        // tag::snippet[]
        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);
        // end::snippet[]
    }

}

Step	Format
Less than 60 seconds	HH:MM:SS
Less than 1 second	HH:MM:SS:FFF

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.

Open in a
new tab

Source code

date-time-picker-auto-open.ts
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@vaadin/date-time-picker';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('date-time-picker-auto-open')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-date-time-picker
        label="Meeting date and time"
        auto-open-disabled
      ></vaadin-date-time-picker>
      <!-- end::snippet[] -->
    `;
  }
}
DateTimePickerAutoOpen.javapackage com.vaadin.demo.component.datetimepicker;

import com.vaadin.flow.component.datetimepicker.DateTimePicker;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.router.Route;

@Route("date-time-picker-auto-open")
public class DateTimePickerAutoOpen extends Div {

    public DateTimePickerAutoOpen() {
        DateTimePicker dateTimePicker = new DateTimePicker(
                "Meeting date and time");
        // tag::snippet[]
        dateTimePicker.setAutoOpen(false);
        // end::snippet[]
        add(dateTimePicker);
    }

}

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:

Open in a
new tab

Source code

date-time-picker-min-max.ts
import { html, LitElement } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import '@vaadin/date-time-picker';
import type { DateTimePickerChangeEvent } from '@vaadin/date-time-picker';
import { applyTheme } from 'Frontend/generated/theme';
import { addDays, format, isAfter, isBefore, parseISO } from 'date-fns';

const dateTimeFormat = `yyyy-MM-dd'T'HH:00:00`;

@customElement('date-time-picker-min-max')
export class Example extends LitElement {
  @state()
  private errorMessage = '';

  @state()
  private initialValue = addDays(new Date(), 7);

  @state()
  private minDate = new Date();

  @state()
  private maxDate = addDays(new Date(), 60);

  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <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>
      <!-- end::snippet[] -->
    `;
  }
}
DateTimePickerMinMax.javapackage com.vaadin.demo.component.datetimepicker;

import com.vaadin.flow.component.datetimepicker.DateTimePicker;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.router.Route;

import java.time.LocalDateTime;


@Route("date-time-picker-min-max")
public class DateTimePickerMinMax extends Div {

    public DateTimePickerMinMax() {
        // tag::snippet[]
        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));
        dateTimePicker.addValueChangeListener(event -> {
            LocalDateTime value = event.getValue();
            String errorMessage = null;
            if (value != null) {
                if (value.compareTo(dateTimePicker.getMin()) < 0) {
                    errorMessage = "Too early, choose another date and time";
                } else if (value.compareTo(dateTimePicker.getMax()) > 0) {
                    errorMessage = "Too late, choose another date and time";
                }
            }
            dateTimePicker.setErrorMessage(errorMessage);
        });
        add(dateTimePicker);
        // end::snippet[]
    }

}

Custom Validation

If the min and max values aren’t enough, you can also apply custom validation.

Open in a
new tab

Source code

date-time-picker-custom-validation.ts
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@vaadin/date-time-picker';
import { Binder, field } from '@hilla/form';
import AppointmentModel from 'Frontend/generated/com/vaadin/demo/domain/AppointmentModel';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('date-time-picker-custom-validation')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  // tag::snippet[]
  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>
    `;
  }
  // end::snippet[]
}
DateTimePickerCustomValidation.javapackage com.vaadin.demo.component.datetimepicker;

import com.vaadin.flow.component.datetimepicker.DateTimePicker;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.data.binder.Binder;
import com.vaadin.flow.router.Route;

import java.time.Duration;
import java.time.LocalTime;

import com.vaadin.demo.domain.Appointment;

@Route("date-time-picker-custom-validation")
public class DateTimePickerCustomValidation extends Div {

    public DateTimePickerCustomValidation() {
        // tag::snippet[]
        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);

        String errorMessage = "The selected day of week or time is not available";
        Binder<Appointment> binder = new Binder<>(Appointment.class);
        binder.forField(dateTimePicker).withValidator(startDateTime -> {
            boolean validWeekDay = startDateTime.getDayOfWeek().getValue() >= 1
                    && startDateTime.getDayOfWeek().getValue() <= 5;
            return validWeekDay;
        }, errorMessage).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;
        }, errorMessage).bind(Appointment::getStartDateTime,
                Appointment::setStartDateTime);
        // end::snippet[]
    }

}

Week Numbers

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

Open in a
new tab

Source code

date-time-picker-week-numbers.ts
import { html, LitElement } from 'lit';
import { customElement, query } from 'lit/decorators.js';
import '@vaadin/date-time-picker';
import type { DateTimePicker } from '@vaadin/date-time-picker';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('date-time-picker-week-numbers')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  // tag::snippet[]
  @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>
    `;
  }
  // end::snippet[]
}
DateTimePickerWeekNumbers.javapackage com.vaadin.demo.component.datetimepicker;

import com.vaadin.flow.component.datepicker.DatePicker;
import com.vaadin.flow.component.datetimepicker.DateTimePicker;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.router.Route;

@Route("date-time-picker-week-numbers")
public class DateTimePickerWeekNumbers extends Div {

    public DateTimePickerWeekNumbers() {
        DateTimePicker dateTimePicker = new DateTimePicker();
        dateTimePicker.setLabel("Meeting date and time");
        // tag::snippet[]
        dateTimePicker.setWeekNumbersVisible(true);
        dateTimePicker.setDatePickerI18n(
                new DatePicker.DatePickerI18n().setFirstDayOfWeek(1));
        // end::snippet[]
        add(dateTimePicker);
    }

}

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.

Open in a
new tab

Source code

date-time-picker-initial-position.ts
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@vaadin/date-time-picker';
import { applyTheme } from 'Frontend/generated/theme';
import startOfMonth from 'date-fns/startOfMonth';
import addMonths from 'date-fns/addMonths';
import formatISO from 'date-fns/formatISO';

const startOfNextMonth = startOfMonth(addMonths(new Date(), 1));
const startOfNextMonthISOString = formatISO(startOfNextMonth, { representation: 'date' });

@customElement('date-time-picker-initial-position')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-date-time-picker
        label="Meeting date and time"
        .initialPosition="${startOfNextMonthISOString}"
      ></vaadin-date-time-picker>
      <!-- end::snippet[] -->
    `;
  }
}
DateTimePickerInitialPosition.javapackage com.vaadin.demo.component.datetimepicker;

import com.vaadin.flow.component.datetimepicker.DateTimePicker;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.router.Route;

import java.time.LocalDate;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;
import java.time.temporal.TemporalAdjusters;

@Route("date-time-picker-initial-position")
public class DateTimePickerInitialPosition extends Div {

    public DateTimePickerInitialPosition() {
        DateTimePicker dateTimePicker = new DateTimePicker(
                "Meeting date and time");
        // tag::snippet[]
        // 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);
        // end::snippet[]
        add(dateTimePicker);
    }

}

Internationalization (i18n)

Date Time Picker allows localizing texts and labels, such as month names and button labels.

Open in a
new tab

Source code

date-time-picker-internationalization.ts
import { html, LitElement } from 'lit';
import { customElement, query } from 'lit/decorators.js';
import '@vaadin/date-time-picker';
import type { DateTimePicker } from '@vaadin/date-time-picker';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('date-time-picker-internationalization')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  // tag::snippet[]
  @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>`;
  }
  // end::snippet[]
}
DateTimePickerInternationalization.javapackage com.vaadin.demo.component.datetimepicker;

import java.util.List;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.datepicker.DatePicker;
import com.vaadin.flow.component.datetimepicker.DateTimePicker;
import com.vaadin.flow.router.Route;

@Route("date-time-picker-internationalization")
public class DateTimePickerInternationalization extends Div {

    public DateTimePickerInternationalization() {
        DateTimePicker dateTimePicker = new DateTimePicker("Sitzungsdatum");

        // tag::snippet[]
        DatePicker.DatePickerI18n germanI18n = new DatePicker.DatePickerI18n();
        germanI18n.setMonthNames(List.of("Januar", "Februar", "März", "April",
                "Mai", "Juni", "Juli", "August", "September", "Oktober",
                "November", "Dezember"));
        germanI18n.setWeekdays(List.of("Sonntag", "Montag", "Dienstag",
                "Mittwoch", "Donnerstag", "Freitag", "Samstag"));
        germanI18n.setWeekdaysShort(
                List.of("So", "Mo", "Di", "Mi", "Do", "Fr", "Sa"));
        germanI18n.setWeek("Woche");
        germanI18n.setToday("Heute");
        germanI18n.setCancel("Abbrechen");

        dateTimePicker.setDatePickerI18n(germanI18n);
        // end::snippet[]

        add(dateTimePicker);
    }

}

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.

Open in a
new tab

Source code

date-time-picker-range.ts
import { html, LitElement } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import '@vaadin/date-time-picker';
import type { DateTimePickerValueChangedEvent } from '@vaadin/date-time-picker';
import { applyTheme } from 'Frontend/generated/theme';

const initialStartValue = '2020-08-25T20:00';
const initialEndValue = '2020-09-01T20:00';

@customElement('date-time-picker-range')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  @state()
  private startDateTime = initialStartValue;

  @state()
  private endDateTime = initialEndValue;

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <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>
      <!-- end::snippet[] -->
    `;
  }
}
DateTimePickerRange.javapackage com.vaadin.demo.component.datetimepicker;

import com.vaadin.flow.component.datetimepicker.DateTimePicker;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.router.Route;

import java.time.LocalDateTime;


@Route("date-time-picker-range")
public class DateTimePickerRange extends Div {

    public DateTimePickerRange() {
        // tag::snippet[]
        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);
        // end::snippet[]
    }

}

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.

Open in a
new tab

Source code

date-time-picker-input-format.ts
import { html, LitElement } from 'lit';
import { customElement, query } from 'lit/decorators.js';
import '@vaadin/date-time-picker';
import { applyTheme } from 'Frontend/generated/theme';
import type { DateTimePicker } from '@vaadin/date-time-picker';
import dateFnsFormat from 'date-fns/format';
import dateFnsParse from 'date-fns/parse';
import type { DatePickerDate } from '@vaadin/date-picker';

@customElement('date-time-picker-input-format')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  @query('vaadin-date-time-picker')
  private dateTimePicker!: DateTimePicker;

  protected override firstUpdated() {
    const _formatDate = (dateParts: DatePickerDate): string => {
      const { year, month, day } = dateParts;
      const date = new Date(year, month, day);

      return dateFnsFormat(date, 'dd/MM/yyyy');
    };

    const _parseDate = (inputValue: string): DatePickerDate => {
      const date = dateFnsParse(inputValue, 'dd/MM/yyyy', new Date());

      return { year: date.getFullYear(), month: date.getMonth(), day: date.getDate() };
    };

    this.dateTimePicker.i18n = {
      ...this.dateTimePicker.i18n,
      formatDate: _formatDate,
      parseDate: _parseDate,
    };
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <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>
      <!-- end::snippet[] -->
    `;
  }
}
DateTimePickerInputFormat.javapackage com.vaadin.demo.component.datetimepicker;

import com.vaadin.flow.component.datepicker.DatePicker.DatePickerI18n;
import com.vaadin.flow.component.datetimepicker.DateTimePicker;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.router.Route;


@Route("date-time-picker-input-format")
public class DateTimePickerInputFormat extends Div {

    public DateTimePickerInputFormat() {
        // tag::snippet[]
        DatePickerI18n dateFormat = new DatePickerI18n();
        dateFormat.setDateFormat("dd/MM/yyyy");

        DateTimePicker dateTimePicker = new DateTimePicker();
        dateTimePicker.setLabel("Select date and time");
        dateTimePicker.setDatePickerI18n(dateFormat);
        dateTimePicker.setHelperText("Format: DD/MM/YYYY and HH:MM");
        dateTimePicker.setDatePlaceholder("Date");
        dateTimePicker.setTimePlaceholder("Time");
        add(dateTimePicker);
        // end::snippet[]
    }

}

Component	Usage recommendations
Time Picker	Input field for entering or selecting a specific time.
Date Picker	Input field for entering or selecting a specific date.

Component

Usage recommendations

Time Picker

Input field for entering or selecting a specific time.

Date Picker

Input field for entering or selecting a specific date.

58305ABE-B962-4ED0-A1C7-36BB906C9452

Documentation

Documentation

Date Time Picker

Common Input Field Features

Step

Auto Open

Validation

Min and Max Values

Custom Validation

Week Numbers

Initial Position

Internationalization (i18n)

Usage Patterns

Date Time Range

Best Practices

Picking vs Typing

Providing Input Guidance

Documentation

Common Input Field Features

Step

Auto Open

Validation

Min and Max Values

Custom Validation

Week Numbers

Initial Position

Internationalization (i18n)

Usage Patterns

Date Time Range

Best Practices

Picking vs Typing

Providing Input Guidance

Related Components