Range Time Input

Range Time Input widgets are Input Fields that allow the user to enter one or more time-of-day ranges using segmented keyboard inputs (hh:mm), with no dropdown. Each completed range is displayed as a pill that can be removed, or edited in place with allowEdit. 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 array of { start, end } objects, each holding an ISO time string (HH:mm:ss). The end time of every range must be strictly after its start time. To enter a single time, use the Time Input; for whole-day ranges, use the Range Date Input.

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

export default [
  gui.inputs.rangeTimeInput('timeRanges', {
    label: 'Time Ranges',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "rangeTimeInput",
      "path": "timeRanges",
      "label": "Time Ranges"
    }
  ]
}

Props

Use these props to customize your Range Time Input widget.

prop	type	description
`allowEdit`	boolean	Enables selecting and editing pills in place. See Editing Pills. Defaults to `false`
`cancelEditLabel`	string \| Localizable	Tooltip of the pill’s cancel icon while editing. Defaults to `Cancel`
`confirmEditLabel`	string \| Localizable	Tooltip of the pill’s confirm icon while editing. Defaults to `Confirm`
`dayPeriodAriaLabel`	string	Aria label for the AM/PM segment input. Defaults to `AM/PM`
`editAriaLabel`	string \| Localizable	Edit hint joined into a selectable pill’s `aria-description`; `{label}` is replaced with the range’s label. Defaults to `Edit range {label}`
`editCancelledMessage`	string \| Localizable	Screen-reader announcement when an edit is cancelled. Defaults to `Edit cancelled.`
`editCommittedMessage`	string \| Localizable	Screen-reader announcement when an edit commits; `{label}` carries the resulting range. Defaults to `Range updated to {label}.`
`editLabel`	string \| Localizable	Tooltip of the pill’s edit icon. Defaults to `Edit`
`editStartedMessage`	string \| Localizable	Screen-reader announcement when an edit starts; `{label}` carries the range. Defaults to `Editing range {label}.`
`endTimeAriaLabel`	string	Aria label for the end time field group. Defaults to `End time`
`hint`	string	A description to display below the input
`hourAriaLabel`	string	Aria label for the hour segment input. Defaults to `Hour`
`hourFormat`	`'12' \| '24'`	Force 12- or 24-hour entry. Defaults to the user’s locale
`icon`	string	A css class to display an icon inside the input
`incompleteMessage`	string \| Localizable	Error shown when focus leaves the widget with a partially filled time behind; the value goes to `null` so validators report it
`maxTime`	string	Latest allowed time (ISO time, inclusive)
`maxTimeMessage`	string \| Localizable	Error shown when a typed time is after `maxTime`
`minTime`	string	Earliest allowed time (ISO time, inclusive)
`minTimeMessage`	string \| Localizable	Error shown when a typed time is before `minTime`
`minuteAriaLabel`	string	Aria label for the minute segment input. Defaults to `Minute`
`minuteStep`	number	Granularity of the minute segment
`rangeOrderMessage`	string \| Localizable	Error shown when the end time is not strictly after the start time
`removePillAriaLabel`	string	Aria label for the remove pill action. Defaults to `Remove time`
`separator`	string	The separator between start and end time fields. Defaults to `-`
`startTimeAriaLabel`	string	Aria label for the start time field group. Defaults to `Start time`

Hint

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

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

export default [
  gui.inputs.rangeTimeInput('timeRanges', {
    hint: 'Enter one or more time ranges',
    label: 'Time Ranges',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "rangeTimeInput",
      "path": "timeRanges",
      "label": "Time Ranges",
      "props": {
        "hint": "Enter one or more time ranges"
      }
    }
  ]
}

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.rangeTimeInput('timeRanges', {
    icon: 'schedule',
    label: 'Time Ranges',
  }),
];

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

Separator

Use the property separator to customize the text displayed between the start time and end time fields. By default the separator is -.

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

export default [
  gui.inputs.rangeTimeInput('timeRanges', {
    separator: 'to',
    label: 'Time Ranges',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "rangeTimeInput",
      "path": "timeRanges",
      "label": "Time Ranges",
      "props": {
        "separator": "to"
      }
    }
  ]
}

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.rangeTimeInput('timeRanges', {
    hourFormat: '24',
    label: 'Time Ranges',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "rangeTimeInput",
      "path": "timeRanges",
      "label": "Time Ranges",
      "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.rangeTimeInput('timeRanges', {
    minuteStep: 15,
    label: 'Time Ranges',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "rangeTimeInput",
      "path": "timeRanges",
      "label": "Time Ranges",
      "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. The end time of each range must be strictly after its start time, otherwise the rangeOrderMessage error is shown.

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

export default [
  gui.inputs.rangeTimeInput('timeRanges', {
    hint: 'Office hours are 9:00 to 18:00',
    minTime: '09:00:00',
    maxTime: '18:00:00',
    minuteStep: 15,
    minTimeMessage: 'Office not open until 9:00',
    maxTimeMessage: 'Office closed from 18:00',
    rangeOrderMessage: 'End time must be after the start time',
    label: 'Time Ranges',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "rangeTimeInput",
      "path": "timeRanges",
      "label": "Time Ranges",
      "props": {
        "hint": "Office hours are 9:00 to 18:00",
        "minTime": "09:00:00",
        "maxTime": "18:00:00",
        "minuteStep": 15,
        "minTimeMessage": "Office not open until 9:00",
        "maxTimeMessage": "Office closed from 18:00",
        "rangeOrderMessage": "End time must be after the start time"
      }
    }
  ]
}

Aria Labels

Use the properties removePillAriaLabel, startTimeAriaLabel and endTimeAriaLabel to customize the accessibility labels for screen readers. These properties are localizable.

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

export default [
  gui.inputs.rangeTimeInput('timeRanges', {
    removePillAriaLabel: 'Delete range',
    startTimeAriaLabel: 'From time',
    endTimeAriaLabel: 'To time',
    label: 'Time Ranges',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "rangeTimeInput",
      "path": "timeRanges",
      "label": "Time Ranges",
      "props": {
        "removePillAriaLabel": "Delete range",
        "startTimeAriaLabel": "From time",
        "endTimeAriaLabel": "To time"
      }
    }
  ]
}

Editing Pills

Use the property allowEdit to let the user change a committed range in place instead of removing it and typing it again. Click a pill, or arrow onto it, to select it; the selection reveals a pencil icon next to the remove icon. The pencil, or F2 or E on the focused pill, loads the range back into the segments and moves focus to the first start segment. While you type, the pill’s label previews the new value. Enter in the segments or the pill’s check icon confirms the replacement; Escape or the cross icon cancels it and keeps the pill selected. A confirmed range that overlaps a neighbour merges into it, and confirming an unchanged range is treated as a cancel. Selecting is not a commit: the form value only changes on confirm.

On touch devices, where the pills collapse into the count bubble, the pencil is always visible inside the pills dropdown, and the pills and their icons grow to the pointer: coarse sizes listed under CSS Variables.

The tooltips and screen-reader announcements of the flow are localizable through editLabel, confirmEditLabel, cancelEditLabel, editAriaLabel, editStartedMessage, editCommittedMessage and editCancelledMessage. A {label} token in editAriaLabel, editStartedMessage and editCommittedMessage is replaced with the range’s display label by the widget itself, single braces on purpose, so the form’s {{ }} localization interpolation never consumes it.

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

export default [
  gui.inputs.rangeTimeInput('editableShifts', {
    allowEdit: true,
    separator: 'to',
    label: 'Shifts',
    defaultValue: [
      {
        start: '09:00:00',
        end: '12:00:00',
      },
      {
        start: '14:00:00',
        end: '17:00:00',
      },
    ],
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "rangeTimeInput",
      "path": "editableShifts",
      "label": "Shifts",
      "defaultValue": [
        {
          "start": "09:00:00",
          "end": "12:00:00"
        },
        {
          "start": "14:00:00",
          "end": "17:00:00"
        }
      ],
      "props": {
        "allowEdit": true,
        "separator": "to"
      }
    }
  ]
}

Styling

Range 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-intent-error`	Border and focus shadow color when invalid
`--gui-border-focus`	Border color when a pill or time segment is focused
`--gui-shadow-focus`	Box shadow when a pill or time segment is focused
`--gui-intent-primary`	Pill background color
`--gui-color-white`	Pill text and remove button color
`--gui-border-default`	Pills wrapper border and separator border color
`--gui-bg-default`	Scroll shadow gradient color and dropdown background color
`--gui-text-default`	Active piece (hour/minute) visual underline color
`--gui-radius-md`	Pill and dropdown border radius
`--gui-radius-full`	Pill count button and remove button border radius
`--gui-pill-height`	Pill height. `24px`, `32px` under `pointer: coarse`
`--gui-pill-action-size`	Size of the edit, confirm, cancel and remove icons. `16px`, `24px` under `pointer: coarse`
`--gui-pill-action-hit`	Hit area of each pill icon. `24px`, `32px` under `pointer: coarse`
`--gui-pill-font-size`	Pill label font size. `var(--gui-font-xs)`, `var(--gui-font-sm)` under `pointer: coarse`

Anatomy

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

<gui-range-time-input class="gui-range-time gui-field">
  <gui-range-time allow-edit="" class="gui-field">
    <span class="gui-label" id="fieldUid_label"><span class="gui-label__text">Shifts</span></span>
    <div class="gui-widget">
      <div role="group" class="gui-widget-input gui-parts-ring gui-range-time-input" aria-label="Shifts">
        <gui-pills class="gui-range-time-input__pills">
          <div class="gui-pills__strip-wrapper gui-pills--end-shadow gui-pills--start-shadow">
            <div class="gui-pills__strip" role="toolbar" tabindex="-1" aria-label="Selected time ranges">
              <span class="gui-sentinel gui-sentinel__start"></span>
              <button
                type="button"
                class="gui-pills__pill gui-pills__pill--clickable"
                tabindex="-1"
                aria-pressed="false"
                aria-label="09:00 AM - 12:00 PM"
                aria-description="Edit range 09:00 AM - 12:00 PM. Remove time"
              >
                <span class="gui-pills__pill-text">09:00 AM - 12:00 PM</span>
                <span aria-hidden="true" class="gui-pills__pill-action gui-pills__pill-action--edit" title="Edit">
                  <svg
                    xmlns="http://www.w3.org/2000/svg"
                    width="16"
                    height="16"
                    viewBox="0 0 256 256"
                    fill="currentColor"
                    aria-hidden="true"
                  >
                    <path d="M229.66,58.34l-32-…"></path>
                  </svg>
                </span>
                <span class="gui-pills__pill-remove" aria-hidden="true">
                  <svg
                    xmlns="http://www.w3.org/2000/svg"
                    width="16"
                    height="16"
                    viewBox="0 0 256 256"
                    fill="currentColor"
                    aria-hidden="true"
                  >
                    <path d="M165.66,101.66,139…"></path>
                  </svg>
                </span>
              </button>
              <button
                type="button"
                class="gui-pills__pill gui-pills__pill--clickable"
                tabindex="-1"
                aria-pressed="false"
                aria-label="02:00 PM - 05:00 PM"
                aria-description="Edit range 02:00 PM - 05:00 PM. Remove time"
              >
                <span class="gui-pills__pill-text">02:00 PM - 05:00 PM</span>
                <span aria-hidden="true" class="gui-pills__pill-action gui-pills__pill-action--edit" title="Edit">
                  <svg
                    xmlns="http://www.w3.org/2000/svg"
                    width="16"
                    height="16"
                    viewBox="0 0 256 256"
                    fill="currentColor"
                    aria-hidden="true"
                  >
                    <path d="M229.66,58.34l-32-…"></path>
                  </svg>
                </span>
                <span class="gui-pills__pill-remove" aria-hidden="true">
                  <svg
                    xmlns="http://www.w3.org/2000/svg"
                    width="16"
                    height="16"
                    viewBox="0 0 256 256"
                    fill="currentColor"
                    aria-hidden="true"
                  >
                    <path d="M165.66,101.66,139…"></path>
                  </svg>
                </span>
              </button>
              <span class="gui-sentinel gui-sentinel__end"></span>
            </div>
          </div>
          <div class="gui-pills__compact">
            <button
              type="button"
              aria-haspopup="true"
              class="gui-pills__count"
              aria-label="2 time ranges"
              aria-expanded="false"
              aria-controls="fieldUid_pills_dropdown"
            >
              2
            </button>
          </div>
        </gui-pills>
        <div class="gui-range-time-input__inputs">
          <div class="gui-parts gui-range-time-input__field" role="group" aria-label="Start time">
            <div dir="ltr" class="gui-parts__time-cluster gui-range-time-input__time-cluster">
              <div class="gui-parts__touch-target gui-range-time-input__touch-target">
                <input
                  type="text"
                  inputmode="numeric"
                  role="spinbutton"
                  autocomplete="off"
                  class="gui-parts__part gui-range-time-input__part"
                  data-type="hour"
                  data-group="start"
                  maxlength="2"
                  placeholder="hh"
                  tabindex="0"
                  aria-label="Hour"
                  aria-valuemin="1"
                  aria-valuemax="12"
                />
                <div class="gui-parts__visual-underline gui-range-time-input__visual-underline"></div>
              </div>
              <span class="gui-range-time-input__separator">:</span>
              <div class="gui-parts__touch-target gui-range-time-input__touch-target">
                <input
                  type="text"
                  inputmode="numeric"
                  role="spinbutton"
                  autocomplete="off"
                  class="gui-parts__part gui-range-time-input__part"
                  data-type="minute"
                  data-group="start"
                  maxlength="2"
                  placeholder="mm"
                  tabindex="-1"
                  aria-label="Minute"
                  aria-valuemin="0"
                  aria-valuemax="59"
                />
                <div class="gui-parts__visual-underline gui-range-time-input__visual-underline"></div>
              </div>
            </div>
            <span class="gui-range-time-input__separator"></span>
            <div class="gui-parts__touch-target gui-range-time-input__touch-target">
              <button
                type="button"
                class="gui-parts__part gui-parts__dayperiod gui-range-time-input__part gui-range-time-input__dayperiod"
                data-type="dayPeriod"
                data-group="start"
                tabindex="-1"
                aria-label="AM/PM"
              >
                AM
              </button>
              <div class="gui-parts__visual-underline gui-range-time-input__visual-underline"></div>
            </div>
          </div>
          <span class="gui-range-time-input__separator">to</span>
          <div class="gui-parts gui-range-time-input__field" role="group" aria-label="End time">
            <div dir="ltr" class="gui-parts__time-cluster gui-range-time-input__time-cluster">
              <div class="gui-parts__touch-target gui-range-time-input__touch-target">
                <input
                  type="text"
                  inputmode="numeric"
                  role="spinbutton"
                  autocomplete="off"
                  class="gui-parts__part gui-range-time-input__part"
                  data-type="hour"
                  data-group="end"
                  maxlength="2"
                  placeholder="hh"
                  tabindex="-1"
                  aria-label="Hour"
                  aria-valuemin="1"
                  aria-valuemax="12"
                />
                <div class="gui-parts__visual-underline gui-range-time-input__visual-underline"></div>
              </div>
              <span class="gui-range-time-input__separator">:</span>
              <div class="gui-parts__touch-target gui-range-time-input__touch-target">
                <input
                  type="text"
                  inputmode="numeric"
                  role="spinbutton"
                  autocomplete="off"
                  class="gui-parts__part gui-range-time-input__part"
                  data-type="minute"
                  data-group="end"
                  maxlength="2"
                  placeholder="mm"
                  tabindex="-1"
                  aria-label="Minute"
                  aria-valuemin="0"
                  aria-valuemax="59"
                />
                <div class="gui-parts__visual-underline gui-range-time-input__visual-underline"></div>
              </div>
            </div>
            <span class="gui-range-time-input__separator"></span>
            <div class="gui-parts__touch-target gui-range-time-input__touch-target">
              <button
                type="button"
                class="gui-parts__part gui-parts__dayperiod gui-range-time-input__part gui-range-time-input__dayperiod"
                data-type="dayPeriod"
                data-group="end"
                tabindex="-1"
                aria-label="AM/PM"
              >
                AM
              </button>
              <div class="gui-parts__visual-underline gui-range-time-input__visual-underline"></div>
            </div>
          </div>
        </div>
      </div>
      <div class="gui-visually-hidden" aria-live="polite"></div>
    </div>
  </gui-range-time>
</gui-range-time-input>