Time Input

Time Input widgets are Input Fields that provide a structured, segmented text-input approach to manual time entry (hh:mm), offering a keyboard-friendly alternative to time pickers. Whether the widget renders in 12-hour or 24-hour mode follows the user’s locale, and in 12-hour mode an AM/PM segment is rendered at the locale’s position.

The widget emits an ISO time string (HH:mm:ss) on change, pair it with the { format: 'time' } validator. Values hydrate from HH:mm, HH:mm:ss, or from the time part of a local ISO date-time string. To capture a date and a time together, use the Date Time Input instead.

import { gui } from '@golemui/gui-shared';

export default [
  gui.inputs.timeInput('meetingTime', {
    label: 'Meeting Time',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "timeInput",
      "path": "meetingTime",
      "label": "Meeting Time"
    }
  ]
}

Typed values clamp at their limits (30 hours becomes 23 or 12 in 12-hour mode, and 95 minutes becomes 59). ArrowUp/ArrowDown increment the focused segment: hours stop at their limits while minutes wrap around (59 → 00). The AM/PM segment is a toggle button: clicking it (or pressing Enter, Space, ArrowUp or ArrowDown) swaps AM and PM.

Props

Use these props to customize your Time Input widget.

prop	type	description
`dayPeriodAriaLabel`	string	ARIA label for the AM/PM segment input. Defaults to `AM/PM`
`hint`	string	A description to display below the segmented inputs
`hourAriaLabel`	string	ARIA label for the hour segment input. Defaults to `Hour`
`hourFormat`	`'12' \| '24'`	Forces 12-hour or 24-hour mode; when omitted the locale decides
`icon`	string	A css class to display an icon inside the input
`incompleteMessage`	string \| Localizable	Error message shown when focus leaves the widget with a partially filled time behind; the value goes to `null` so validators report it
`maxTime`	string	Last allowed time (ISO time, inclusive)
`maxTimeMessage`	string \| Localizable	Error message shown when the entered time is after `maxTime`
`minTime`	string	First allowed time (ISO time, inclusive)
`minTimeMessage`	string \| Localizable	Error message shown when the entered time is before `minTime`
`minuteAriaLabel`	string	ARIA label for the minute segment input. Defaults to `Minute`
`minuteStep`	number	The ArrowUp/ArrowDown increment of the minute segment (default: 1)

Hint

Use the property hint to add a description or validation instructions.

import { gui } from '@golemui/gui-shared';

export default [
  gui.inputs.timeInput('meetingTime', {
    hint: 'Please enter the meeting start time',
    label: 'Meeting Time',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "timeInput",
      "path": "meetingTime",
      "label": "Meeting Time",
      "props": {
        "hint": "Please enter the meeting start time"
      }
    }
  ]
}

Icon

Use the property icon to add an icon to the widget. The value of icon represents a set of CSS classes separated by spaces. The icon is displayed inside the input border.

import { gui } from '@golemui/gui-shared';

export default [
  gui.inputs.timeInput('meetingTime', {
    icon: 'schedule',
    label: 'Meeting Time',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "timeInput",
      "path": "meetingTime",
      "label": "Meeting Time",
      "props": {
        "icon": "schedule"
      }
    }
  ]
}

Hour Format

By default the 12-hour/24-hour layout comes from the locale’s hour cycle. Use the property hourFormat ('12' or '24') to force one of them.

import { gui } from '@golemui/gui-shared';

export default [
  gui.inputs.timeInput('meetingTime12', {
    hourFormat: '12',
    label: 'Meeting Time (12h)',
  }),
  gui.inputs.timeInput('meetingTime24', {
    hourFormat: '24',
    label: 'Meeting Time (24h)',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "timeInput",
      "path": "meetingTime12",
      "label": "Meeting Time (12h)",
      "props": {
        "hourFormat": "12"
      }
    },
    {
      "kind": "input",
      "type": "timeInput",
      "path": "meetingTime24",
      "label": "Meeting Time (24h)",
      "props": {
        "hourFormat": "24"
      }
    }
  ]
}

Minute Step

Use the property minuteStep to control the ArrowUp/ArrowDown increment of the minute segment, useful for appointment-style forms where times snap to a grid (e.g. every 15 minutes). Typing a value is not restricted by the step. The default is 1.

import { gui } from '@golemui/gui-shared';

export default [
  gui.inputs.timeInput('meetingTime', {
    minuteStep: 15,
    label: 'Meeting Time',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "timeInput",
      "path": "meetingTime",
      "label": "Meeting Time",
      "props": {
        "minuteStep": 15
      }
    }
  ]
}

Min and Max Times

Use the properties minTime and maxTime (ISO times, both inclusive) to specify the boundaries for accepted times. A completed time outside the boundaries raises an input error instead of a value; customize (and localize) the messages with minTimeMessage and maxTimeMessage.

import { gui } from '@golemui/gui-shared';

export default [
  gui.inputs.timeInput('meetingTime', {
    hint: 'Office hours are 9:00 to 18:00',
    minTime: '09:00:00',
    maxTime: '18:00:00',
    minTimeMessage: 'Office not open until 9:00',
    maxTimeMessage: 'Office closed from 18:00',
    label: 'Meeting Time',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "timeInput",
      "path": "meetingTime",
      "label": "Meeting Time",
      "props": {
        "hint": "Office hours are 9:00 to 18:00",
        "minTime": "09:00:00",
        "maxTime": "18:00:00",
        "minTimeMessage": "Office not open until 9:00",
        "maxTimeMessage": "Office closed from 18:00"
      }
    }
  ]
}

Styling

Time Inputs can be styled as explained in the Styling Guide.

CSS Variables

Following you will find a list with the CSS Variables and a quick description of what you will style.

CSS Variable	Description
`--gui-text-default`	Text color and active piece (hour/minute) visual underline color
`--gui-intent-error`	Border color when invalid
`--gui-border-focus`	Border color when a segment is focused
`--gui-shadow-focus`	Focus shadow
`--gui-shadow-focus-error`	Focus shadow when invalid

Anatomy

This is the anatomy of the Time Input Widget in case you want to use your CSS styles.

<gui-time class="gui-field">
  <label class="gui-label" for="fieldUid" id="fieldUid_label">
    Label
    <div class="gui-widget-hint" id="fieldUid_hint">Hint</div>
  </label>

  <div class="gui-widget">
    <div class="gui-widget-input gui-time-input gui-calendar--icon" role="group">
      <div class="gui-time-input__touch-target">
        <input type="text" inputmode="numeric" class="gui-time-input__part" data-type="hour" maxlength="2" placeholder="hh" tabindex="0" value="09">
        <div class="gui-time-input__visual-underline"></div>
      </div>
      <span class="gui-time-input__separator">:</span>

      <div class="gui-time-input__touch-target">
        <input type="text" inputmode="numeric" class="gui-time-input__part" data-type="minute" maxlength="2" placeholder="mm" tabindex="-1" value="30">
        <div class="gui-time-input__visual-underline"></div>
      </div>

      <!-- Only rendered in 12-hour mode, at the locale's position -->
      <div class="gui-time-input__touch-target">
        <button type="button" class="gui-time-input__part gui-time-input__dayperiod" data-type="dayPeriod" tabindex="-1" aria-label="AM/PM">AM</button>
        <div class="gui-time-input__visual-underline"></div>
      </div>
    </div>

    <span class="gui-widget-icon schedule" data-icon="schedule"></span>
  </div>
</gui-time>