MaskedTimeField

The MaskedTimeField is a text input control designed for precise, structured time entry. It lets users enter times as numbers and automatically formats the input based on a defined mask when the field loses focus. The mask is a string that specifies the expected time format, guiding both input and display.

This component supports flexible parsing, validation, localization, and value restoration. It's especially useful in time-sensitive forms like schedules, timesheets, and reservations.

Looking for date input?

The MaskedTimeField is built for time-only input. If you’re looking for a component to handle dates with similar mask-based formatting, take a look at the MaskedDateField.

Basics

The MaskedTimeField can be instantiated with or without parameters. You can define an initial value, a label, a placeholder, and an event listener for value changes.

Show Code

Java

Mask rules

The MaskedTimeField uses format indicators to define how time is parsed and displayed. Each format indicator begins with a % followed by a letter that represents a time component.

Time format indicators

Format	Description
`%H`	Hour (24-hour)
`%h`	Hour (12-hour)
`%m`	Minute
`%s`	Second
`%p`	AM/PM

Modifiers

Modifiers refine the display of time components:

Modifier	Description
`z`	Zero-fill
`s`	Short text representation
`l`	Long text representation
`p`	Packed number
`d`	Decimal (default format)

These allow for flexible and locale-friendly time formatting.

Time format localization

The MaskedTimeField supports localization by setting the appropriate locale. This ensures that time input and output match regional conventions.

field.setLocale(Locale.GERMANY);

This affects how AM/PM indicators are displayed, how separators are handled, and how values are parsed.

Parsing logic

The MaskedTimeField parses user input based on the defined time mask. It accepts both complete and abbreviated numeric inputs with or without delimiters, allowing flexible entry while ensuring valid times. Parsing behavior depends on the format order defined by the mask (e.g., %Hz:%mz for hour/minute). This format determines how numeric sequences are interpreted.

Example parsing scenarios

Entry	Mask	Interpreted As
`900`	`%Hz:%mz`	`09:00`
`1345`	`%Hz:%mz`	`13:45`
`0230`	`%hz:%mz %p`	`02:30 AM`
`1830`	`%hz:%mz %p`	`06:30 PM`

Setting min/max constraints

You can restrict the allowed time range in a MaskedTimeField using the setMin() and setMax() methods:

field.setMin(LocalTime.of(8, 0));
field.setMax(LocalTime.of(18, 0));

Both methods accept values of type java.time.LocalTime. Inputs outside the defined range are considered invalid.

Restoring the value

The MaskedTimeField includes a restore feature that resets the field’s value to a predefined or original state. This can be useful for undoing changes or returning to a default time.

field.setRestoreValue(LocalTime.of(12, 0));
field.restoreValue();

Ways to restore the value

Programmatically, by calling restoreValue()
Via keyboard, by pressing ESC (this is the default restore key unless overridden by an event listener)

Show Code

Java

Validation patterns

You can apply client-side validation rules using regular expressions with the setPattern() method:

field.setPattern("^\\d{2}:\\d{2}$");

This pattern ensures that only values matching the HH:mm format (two digits, colon, two digits) are considered valid.

Regular Expression Format

The pattern must follow JavaScript RegExp syntax as documented here.

Notes on Input Handling

The field attempts to parse and format numeric time inputs based on the current mask. However, users can still manually enter values that don't match the expected format. If the input is syntactically valid but semantically incorrect or unparseable (e.g. 99:99), it may pass pattern checks but fail logical validation. You should always validate the input value in your app logic, even if a regular expression pattern is set, to ensure the time is both correctly formatted and meaningful.

Time picker

The MaskedTimeField includes a built-in time picker that lets users select a time visually, rather than typing it. This enhances usability for less technical users or when precise input is required.

Show Code

Java

Accessing the picker

You can access the time picker using getPicker():

TimePicker picker = field.getPicker();

Show/hide the picker icon

Use setIconVisible() to show or hide the clock icon next to the field:

picker.setIconVisible(true); // shows the icon

Auto-open behavior

You can configure the picker to open automatically when the user interacts with the field (e.g. clicks, presses Enter or arrow keys):

picker.setAutoOpen(true);

Enforce Selection Through the Picker

To ensure users can only select a time using the picker (and not manually type one), combine the following two settings:

field.getPicker().setAutoOpen(true); // Opens the picker on user interaction
field.setAllowCustomValue(false);    // Disables manual text input

This setup guarantees that all time input comes through the picker UI, which is useful when you want strict format control and eliminate parsing issues from typed input.

Manually open the picker

To open the time picker programmatically:

picker.open();

Or use the alias:

picker.show(); // same as open()

Setting the picker step

You can define the interval between selectable times in the picker using setStep(). This allows you to control how granular the time options are—ideal for scenarios like scheduling in 15-minute blocks.

field.getPicker().setStep(Duration.ofMinutes(15));

Step Constraint

The step must evenly divide an hour or a full day. Otherwise, an exception will be thrown.

This ensures the dropdown list contains predictable, evenly spaced values like 09:00, 09:15, 09:30, etc.