Time Picker

A time input component with an integrated dropdown for selecting time values, with support for various formats, masking, and validation.

Time

Overview

Time pickers allow users to select specific time values through an interactive interface. They provide a structured way to input time data while reducing errors and ensuring consistent formatting across different time systems and locales.

Usage

forge-time-picker wraps a child text field and adds a dropdown of selectable time options, through use24HourTime, min/max/step, restrictedTimes, masked, and allowInput. Use it when a person is entering a specific time; for a time range, place two time pickers side by side. Reach for a select instead when the choice is really a vague description (“now”, “in 30 minutes”) rather than a specific time, or a plain text field instead when the value isn’t a time at all.

Rules

Support both 12-hour and 24-hour formats depending on locale and context.

Pair a 12-hour format with a visible AM/PM indicator.

Place two time pickers side by side to capture a time range.

Show a timezone alongside the value when the time is specific to a place or event.

Don't

Don't use a time picker for vague time descriptions like "now" or "in an hour" — use a select instead.

Don't use a time picker for free-text entry that isn't actually a time — use a text field instead.

Don't restrict input to the dropdown alone unless typing a time would be error-prone for your data.

Basic usage

A time picker’s text field accepts typed input and its trailing icon button opens a dropdown of selectable times.

A time picker combining a text field with a dropdown of time options.

<forge-time-picker use-24-hour-time="false">
  <forge-text-field>
    <input id="time-picker" type="text" autocomplete="off" autocorrect="off" autocapitalize="off" role="combobox" aria-live="assertive" aria-atomic aria-haspopup aria-controls="forge-aria-controls-placeholder">
    <label for="time-picker" slot="label">
      Time
    </label>
    <forge-icon-button slot="trailing" density="medium" aria-label="Toggle time dropdown">
      <forge-icon name="clock_outline">
      </forge-icon>
    </forge-icon-button>
  </forge-text-field>
</forge-time-picker>

<script type="module">
import { IconRegistry } from "@tylertech/forge/icon";
import { tylIconClockOutline } from "@tylertech/tyler-icons";
IconRegistry.define([tylIconClockOutline]);
</script>

Format

Set use24HourTime to switch between the default 12-hour format and 24-hour time.

12-hour (default) and 24-hour formats.

<forge-time-picker>
  <forge-text-field>
    <label for="time-picker-12h">
      12-hour
    </label>
    <input type="text" id="time-picker-12h" />
  </forge-text-field>
</forge-time-picker>
<forge-time-picker use24-hour-time>
  <forge-text-field>
    <label for="time-picker-24h">
      24-hour
    </label>
    <input type="text" id="time-picker-24h" />
  </forge-text-field>
</forge-time-picker>

Working with values

Always use 24-hour format in code

Regardless of the display format shown to the user, every programmatic read or write of value — and the change event — uses 24-hour time (e.g. "15:30"). This keeps the format locale-independent. Set values through forge-time-picker itself, never the wrapped <input> (the input only takes cosmetic attributes like placeholder). If the field needs to be required or invalid, set that on the embedded forge-text-field, not on forge-time-picker.

const picker = document.querySelector("forge-time-picker");
picker.value = "15:30"; // always 24-hour, even if use24HourTime is false
picker.addEventListener("change", () => console.log(picker.value)); // also 24-hour

Now and hour shortcuts

Set showNow and showHourOptions to add shortcuts for the current time and whole-hour options to the dropdown.

Shortcuts for the current time and whole-hour options.

<forge-time-picker show-now show-hour-options>
  <forge-text-field>
    <label for="time-picker-shortcuts">
      Choose time
    </label>
    <input type="text" id="time-picker-shortcuts" />
  </forge-text-field>
</forge-time-picker>

Constraints

Set min, max, and step to bound selectable times and control the interval between dropdown options.

A time picker bounded to a range, in 30-minute steps.

<forge-time-picker min="09:00" max="17:00" step="30">
  <forge-text-field>
    <label for="time-picker-constrained">
      Appointment time
    </label>
    <input type="text" id="time-picker-constrained" />
  </forge-text-field>
</forge-time-picker>

Masking and input

Set masked to apply an input mask, shown as a placeholder, so typed times are corrected to a consistent format as the user types.

A masked time picker showing its format as a placeholder.

<forge-time-picker masked show-mask-format>
  <forge-text-field>
    <label for="time-picker-masked">
      Choose time
    </label>
    <input type="text" id="time-picker-masked" />
  </forge-text-field>
</forge-time-picker>

Disabled

Set disabled to prevent typing or opening the dropdown.

A disabled time picker.

<forge-time-picker disabled>
  <forge-text-field disabled>
    <label for="time-picker-disabled">
      Choose time
    </label>
    <input type="text" id="time-picker-disabled" />
  </forge-text-field>
</forge-time-picker>

A time input component with integrated dropdown for selecting time values with support for various formats, masking, and validation options.

import "@tylertech/forge/time-picker";

Properties

Property	Attribute	Type	Default	Description
`value`	`value`	`string \| null \| undefined`	`undefined`	The current value of the time picker.
`open`	`open`	`boolean`	`false`	Whether or not the time picker is open.
`allowSeconds`	`allow-seconds`	`boolean`	`false`	Whether or not to allow seconds in the time picker.
`masked`	`masked`	`boolean`	`false`	Whether or not the time picker input should be masked.
`showMaskFormat`	`show-mask-format`	`boolean`	`false`	Whether or not to show the mask format in the input.
`use24HourTime`	—	`boolean`	`false`	Whether or not to use 24-hour time.
`allowInvalidTime`	`allow-invalid-time`	`boolean`	`false`	Whether or not to allow invalid times.
`min`	`min`	`string \| null \| undefined`	`undefined`	The minimum time that can be selected.
`max`	`max`	`string \| null \| undefined`	`undefined`	The maximum time that can be selected.
`restrictedTimes`	`restricted-times`	`string[]`	`[]`	An array of times that cannot be selected.
`startTime`	`start-time`	`string \| null \| undefined`	`undefined`	The time to start the time picker at.
`step`	`step`	`number`	`undefined`	The step interval for the time picker.
`allowInput`	`allow-input`	`boolean`	`false`	Whether or not to allow manual input of the time.
`showNow`	`show-now`	`boolean`	`false`	Whether or not to show a "Now" button.
`showHourOptions`	`show-hour-options`	`boolean`	`false`	Whether or not to display hour options in dropdown.
`customOptions`	`custom-options`	`ITimePickerOption[]`	`[]`	An array of custom time picker options.
`validationCallback`	`validation-callback`	`TimePickerValidationCallback`	`undefined`	A callback function to validate the time.
`parseCallback`	`parse-callback`	`TimePickerParseCallback`	`undefined`	A callback function to parse the time.
`formatCallback`	`format-callback`	`TimePickerFormatCallback`	`undefined`	A callback function to format the time.
`coercionCallback`	`coercion-callback`	`TimePickerCoercionCallback`	`undefined`	A callback function to coerce the time.
`prepareMaskCallback`	`prepare-mask-callback`	`TimePickerPrepareMaskCallback`	`undefined`	A callback function to prepare the mask.
`disabled`	`disabled`	`boolean`	`false`	Whether or not the time picker is disabled.
`popupClasses`	`popup-classes`	`string \| string[]`	`undefined`	The classes to apply to the time picker popup.
`allowDropdown`	`allow-dropdown`	`boolean`	`false`	Whether or not to allow the time picker to be a dropdown.
`popupTarget`	`popup-target`	`string`	`undefined`	The target element to attach the popup to.
—	`use-24-hour-time`	`boolean`	`false`	Whether or not to use 24-hour time.

Labeling

Add an aria-label to the <input> if you’re not pairing it with a <label for> — the time picker doesn’t infer one on its own.

Automatic ARIA attributes

The component applies role="combobox", aria-live, aria-atomic, aria-haspopup, aria-expanded, aria-controls, aria-activedescendant, and aria-disabled to the input for you, so you don’t need to set those yourself.

Keyboard interaction

As you arrow through the dropdown, the highlighted option is announced via aria-activedescendant.