Docs

You are viewing documentation for an older Vaadin version. View latest documentation

Docs

Time Picker

Time Picker is an input field for entering or selecting a specific time.

Open in a
new tab
TimePicker timePicker = new TimePicker();
timePicker.setLabel("Alarm");
timePicker.setValue(LocalTime.of(7, 0));
add(timePicker);

The time can be entered directly using a keyboard or by choosing a value from a set of predefined options presented in an overlay. The overlay opens when the field is clicked or any input is entered when the field is focused.

Common Input Field Features

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

Step

Time Picker’s step parameter defines the interval (in seconds) between the items displayed in the overlay. It also specifies the amount by which the time increases/decreases using the Up/Down arrow keys (when the overlay is disabled).

The default step is one hour (that is 3600). Note that, unlike with Number Field, Time Picker accepts values that do not align with the specified step.

Open in a
new tab
TimePicker timePicker = new TimePicker();
timePicker.setLabel("Meeting time");
timePicker.setStep(Duration.ofMinutes(30));
timePicker.setValue(LocalTime.of(12,30));
add(timePicker);
Note
Use common 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.

Open in a
new tab
TimePicker timePicker = new TimePicker();
timePicker.setLabel("Message received");
timePicker.setStep(Duration.ofSeconds(1));
timePicker.setValue(LocalTime.of(15, 45, 8));
add(timePicker);
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.

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.

Open in a
new tab
TimePicker timePicker = new TimePicker();
timePicker.setLabel("Alarm");
timePicker.setStep(Duration.ofMinutes(30));
timePicker.setValue(LocalTime.of(5, 30));
timePicker.setAutoOpen(false);
add(timePicker);

Validation

Minimum & Maximum Value

You can define a minimum and maximum value for Time Picker if you need to restrict the input to a specific range:

Open in a
new tab
TimePicker timePicker = new TimePicker();
timePicker.setLabel("Appointment time");
timePicker.setHelperText("Open 8:00-16:00");
timePicker.setStep(Duration.ofMinutes(30));
timePicker.setValue(LocalTime.of(8, 30));
timePicker.setMinTime(LocalTime.of(8, 0));
timePicker.setMaxTime(LocalTime.of(16, 0));
add(timePicker);

Custom Validation

If the minimum and maximum values are not sufficient, you can also apply custom validation.

Open in a
new tab
TimePicker timePicker = new TimePicker();
timePicker.setLabel("Appointment time");
timePicker.setHelperText("Open 8:00-12:00, 13:00-16:00");
timePicker.setStep(Duration.ofMinutes(30));
timePicker.setMinTime(LocalTime.of(8, 0));
timePicker.setMaxTime(LocalTime.of(16, 0));
add(timePicker);

Binder<Appointment> binder = new Binder<>(Appointment.class);
binder.forField(timePicker).withValidator(startTime -> {
    return !(LocalTime.of(8, 0).isAfter(startTime)
            || (LocalTime.of(12, 0).isBefore(startTime) && LocalTime.of(13, 0).isAfter(startTime))
            || LocalTime.of(16, 0).isBefore(startTime));
}, "The selected time is not available").bind(Appointment::getStartTime, Appointment::setStartTime);

Best Practises

Use Time Picker when the user needs to choose a time of day. Do not use it for durations, such as for a stopwatch or timer.

Component Usage recommendations

Date Picker

Input field for entering or selecting a specific date.

Date Time Picker

Input field for entering or selecting a specific date.

68E1BB9D-2798-4662-A35F-E9CF5D5575A6