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

# Time Picker

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

**TypeScript** — `time-picker-basic.ts`

```html
<vaadin-time-picker label="Alarm" value="07:00"></vaadin-time-picker>
```

**Java** — `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/v23/components/text-field.md)

- [See shared input field features](https://vaadin.com/docs/v23/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`). Unlike [Number Field](https://vaadin.com/docs/v23/components/number-field.md), Time Picker accepts values that don’t align with the specified step.

**TypeScript** — `time-picker-minutes-step.ts`

```html
<vaadin-time-picker
  label="Meeting time"
  value="12:30"
  .step="${60 * 30}"
></vaadin-time-picker>
```

**Java** — `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, whereas *"42 minutes"* isn’t.

The displayed time format changes based on the step.

**TypeScript** — `time-picker-seconds-step.ts`

```html
<vaadin-time-picker label="Message received" value="15:45:08" step="1"></vaadin-time-picker>
```

**Java** — `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);
```

<!-- vale Vaadin.Abbr = NO -->

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

<!-- vale Vaadin.Abbr = YES -->

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

## <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 this, to open the overlay only when the toggle button or `Up`/`Down` arrow keys are pressed.

**TypeScript** — `time-picker-auto-open.ts`

```html
<vaadin-time-picker
  label="Alarm"
  value="05:30"
  .step="${60 * 30}"
  auto-open-disabled
></vaadin-time-picker>
```

**Java** — `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-and-maximum-value"></a>Minimum and Maximum Value

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

**TypeScript** — `time-picker-min-max.ts`

```html
<vaadin-time-picker
  label="Appointment time"
  helper-text="Open 8:00-16:00"
  value="08:30"
  min="08:00"
  max="16:00"
  .step="${60 * 30}"
  error-message="${this.errorMessage}"
  @change="${(event: TimePickerChangeEvent) => {
    const { min, max, value } = event.target;
    if (value < min) {
      this.errorMessage = 'Too early, choose another time';
    } else if (value > max) {
      this.errorMessage = 'Too late, choose another time';
    } else {
      this.errorMessage = '';
    }
  }}"
></vaadin-time-picker>
```

**Java** — `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.setMin(LocalTime.of(8, 0));
timePicker.setMax(LocalTime.of(16, 0));
timePicker.addValueChangeListener(event -> {
    LocalTime value = event.getValue();
    String errorMessage = null;
    if (value != null) {
        if (value.compareTo(timePicker.getMin()) < 0) {
            errorMessage = "Too early, choose another time";
        } else if (value.compareTo(timePicker.getMax()) > 0) {
            errorMessage = "Too late, choose another time";
        }
    }
    timePicker.setErrorMessage(errorMessage);
});
add(timePicker);
```

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

If the minimum and maximum values aren’t sufficient for validation, you can also apply custom validation.

**TypeScript** — `time-picker-custom-validation.ts`

```html
private binder = new Binder(this, AppointmentModel);

protected override firstUpdated() {
  this.binder.for(this.binder.model.startTime).addValidator({
    message: 'The selected time is not available',
    validate: (startTime: string) =>
      (startTime >= '08:00' && startTime <= '12:00') ||
      (startTime >= '13:00' && startTime <= '16:00'),
  });
}

protected override render() {
  return html`
    <vaadin-time-picker
      label="Appointment time"
      helper-text="Open 8:00-12:00, 13:00-16:00"
      min="08:00"
      max="16:00"
      .step="${60 * 30}"
      ${field(this.binder.model.startTime)}
    ></vaadin-time-picker>
  `;
}
```

**Java** — `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-practices"></a>Best Practices

Use Time Picker when the user needs to choose a time of day. Don’t 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/v23/components/date-picker.md)           | Input field for entering or selecting a specific date.          |
| [Date Time Picker](https://vaadin.com/docs/v23/components/date-time-picker.md) | Input field for entering or selecting a specific date and time. |

`299E8D5A-A465-4F72-A029-BB24A4902CD3`
