Time Picker

Common Input Field Features
Step
Auto Open
Validation
Best Practices
Related Components

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

Source code

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

@customElement('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-time-picker label="Alarm" value="07:00"></vaadin-time-picker>
      <!-- end::snippet[] -->
    `;
  }
}
TimePickerBasic.javapackage com.vaadin.demo.component.timepicker;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.timepicker.TimePicker;
import com.vaadin.flow.router.Route;

import java.time.LocalTime;


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

    public TimePickerBasic() {
        // tag::snippet[]
        TimePicker timePicker = new TimePicker();
        timePicker.setLabel("Alarm");
        timePicker.setValue(LocalTime.of(7, 0));
        add(timePicker);
        // end::snippet[]
    }

}

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). Unlike Number Field, Time Picker accepts values that don’t align with the specified step.

Open in a
new tab

Source code

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

@customElement('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-time-picker
        label="Meeting time"
        value="12:30"
        .step="${60 * 30}"
      ></vaadin-time-picker>
      <!-- end::snippet[] -->
    `;
  }
}
TimePickerMinutesStep.javapackage com.vaadin.demo.component.timepicker;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.timepicker.TimePicker;
import com.vaadin.flow.router.Route;

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


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

    public TimePickerMinutesStep() {
        // tag::snippet[]
        TimePicker timePicker = new TimePicker();
        timePicker.setLabel("Meeting time");
        timePicker.setStep(Duration.ofMinutes(30));
        timePicker.setValue(LocalTime.of(12, 30));
        add(timePicker);
        // end::snippet[]
    }

}

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.

Open in a
new tab

Source code

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

@customElement('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-time-picker label="Message received" value="15:45:08" step="1"></vaadin-time-picker>
      <!-- end::snippet[] -->
    `;
  }
}
TimePickerSecondsStep.javapackage com.vaadin.demo.component.timepicker;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.timepicker.TimePicker;
import com.vaadin.flow.router.Route;

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


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

    public TimePickerSecondsStep() {
        // tag::snippet[]
        TimePicker timePicker = new TimePicker();
        timePicker.setLabel("Message received");
        timePicker.setStep(Duration.ofSeconds(1));
        timePicker.setValue(LocalTime.of(15, 45, 8));
        add(timePicker);
        // 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, to open the overlay only when the toggle button or Up/Down arrow keys are pressed.

Open in a
new tab

Source code

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

@customElement('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-time-picker
        label="Alarm"
        value="05:30"
        .step="${60 * 30}"
        auto-open-disabled
      ></vaadin-time-picker>
      <!-- end::snippet[] -->
    `;
  }
}
TimePickerAutoOpen.javapackage com.vaadin.demo.component.timepicker;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.timepicker.TimePicker;
import com.vaadin.flow.router.Route;

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


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

    public TimePickerAutoOpen() {
        // tag::snippet[]
        TimePicker timePicker = new TimePicker();
        timePicker.setLabel("Alarm");
        timePicker.setStep(Duration.ofMinutes(30));
        timePicker.setValue(LocalTime.of(5, 30));
        timePicker.setAutoOpen(false);
        add(timePicker);
        // end::snippet[]
    }

}

Validation

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:

Open in a
new tab

Source code

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

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

  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-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>
      <!-- end::snippet[] -->
    `;
  }
}
TimePickerMinMax.javapackage com.vaadin.demo.component.timepicker;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.timepicker.TimePicker;
import com.vaadin.flow.router.Route;

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


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

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

}

Custom Validation

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

Open in a
new tab

Source code

time-picker-custom-validation.ts
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@vaadin/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('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);

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

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.timepicker.TimePicker;
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("time-picker-custom-validation")
public class TimePickerCustomValidation extends Div {

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

}

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.

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 and time.

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 and time.

299E8D5A-A465-4F72-A029-BB24A4902CD3

Documentation

Documentation

Time Picker

Common Input Field Features

Step

Auto Open

Validation

Minimum and Maximum Value

Custom Validation

Best Practices

Documentation

Common Input Field Features

Step

Auto Open

Validation

Minimum and Maximum Value

Custom Validation

Best Practices

Related Components