TimeInput

TimeInput uses a browser/OS time picker on coarse pointers by default and Astryx's typed field on fine pointers. It converts values to a standard format and supports arrow-key adjustment on the typed surface. Use it in forms, scheduling flows, or any interface where users need to select a specific time.

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

Time Input

TimeInput uses a browser/OS time picker on coarse pointers by default and Astryx's typed field on fine pointers. It converts values to a standard format and supports arrow-key adjustment on the typed surface. Use it in forms, scheduling flows, or any interface where users need to select a specific time.

Usage guidance

• Base props such as ref, id, data-, aria-, and DOM event handlers go to the time input, the element that is focused and announced. A DOM handler runs after TimeInput's own handler for the same event and still receives events it handled (including ones it called preventDefault on), so it cannot cancel built-in behavior.
• Choose the hour format (12h or 24h) that matches your audience's locale: 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.
• Set min and max constraints when the context has a valid range, like business hours or event windows, so users cannot submit an out-of-bounds time.
• Provide a description or placeholder that hints at the expected format or purpose, like "Business hours: 9 AM – 5 PM".
• Use the status prop to surface validation errors inline: show a message like "Time must be during business hours" so users know exactly what to fix.
• Enable hasClear when the field is optional, so users can remove a previously selected time.
• Place TimeInput inside InputGroup when the time needs a single-line prefix or suffix addon, like a start/end label or timezone marker.
• Avoid: Don't use TimeInput for combined date-and-time selection; pair it with a separate DateInput instead.
• Avoid: Don't hide the label; even when space is tight, keep the label visible or provide a description so the purpose is clear.
• Avoid: Wrap a disabled TimeInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.

Theming API

{
  "targets": [
    {
      "className": "astryx-time-input",
      "visualProps": [
        "size",
        "status"
      ],
      "states": [
        "disabled"
      ]
    }
  ]
}

Anatomy

• Clock icon: A leading clock icon that identifies the field and opens the browser/OS picker in native mode.
• Time control: A real input type=time in native modes, or Astryx's editable text field for fine pointers, presentation="text-input", seconds, and custom increments.
• Clear button: A trailing button to reset the value, shown when hasClear is true and a value is set.
• Status icon: A trailing icon indicating error, warning, or success state.
• Spinner: Replaces trailing content during loading to show an async action is in progress.

Examples

• Time Input: A time input that uses the browser/OS picker on touch by default and Astryx typed entry on fine pointers.
• TimeInput — Constrained: Time inputs with min/max constraints limiting selection to specific windows. Use to prevent out-of-bounds selections for appointments, reservations, or shift scheduling.
• TimeInput — Formats: 12-hour, 24-hour, and seconds formats side by side. Use 12h for US-centric UIs, 24h for international or technical contexts, and seconds for precise timing.
• TimeInput — Increment: Time input with a custom step increment. Arrow keys jump by the specified interval (e.g. 15 minutes) for quick slot-based scheduling.
• TimeInput — States: Default, disabled, error, warning, and success states. Use status messages to give users clear feedback about their time selection.