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

# Time Picker

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

`TimePickerBasic.java`

```java
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.

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

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

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](https://vaadin.com/docs/v14/ds/components/number-field.md), Time Picker accepts values that do not align with the specified step.

`TimePickerMinutesStep.java`

```java
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.

`TimePickerSecondsStep.java`

```java
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.

## <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.

`TimePickerAutoOpen.java`

```java
TimePicker timePicker = new TimePicker();
timePicker.setLabel("Alarm");
timePicker.setStep(Duration.ofMinutes(30));
timePicker.setValue(LocalTime.of(5, 30));
timePicker.setAutoOpen(false);
add(timePicker);
```

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

### <a id="minimum-maximum-value"></a>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:

`TimePickerMinMax.java`

```java
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);
```

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

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

`TimePickerCustomValidation.java`

```java
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);
```

## <a id="best-practises"></a>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.

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

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

`68E1BB9D-2798-4662-A35F-E9CF5D5575A6`