Skip to content
omaris

Inputs

Time Field

A time input: a field that reads 2:30 PM and opens a ClockPicker — under the field on a desktop, in a bottom sheet on a phone.

import { TimeField } from 'omaris'
Learn

Examples

Basic

A field that opens the clock picker — under the field on a desktop, with the cursor already in the hour box, and in a bottom sheet on a phone. Nothing changes until OK.

<script lang="ts">	import { TimeField } from 'omaris';​	let at = $state<string | null>(null);</script>​<TimeField class="w-64 max-w-full" label="Reminder" showNow bind:value={at} />

Range

TimeRangeField holds a span of the day: opening hours, a shift, quiet hours that run overnight. With a name it posts as 09:00/17:30.

<script lang="ts">	import { TimeRangeField, type TimeRange } from 'omaris';​	let hours = $state<TimeRange | null>({ start: '09:00', end: '17:30' });	let quiet = $state<TimeRange | null>({ start: '22:00', end: '07:00' });</script>​<TimeRangeField	class="w-64 max-w-full"	label="Opening hours"	minuteStep={15}	durations={[240, 480, 600]}	bind:value={hours}/><TimeRangeField class="w-64 max-w-full" label="Quiet hours" minuteStep={30} bind:value={quiet} />

States

The same frame, sizes and states as a text field. min, max and minuteStep grey times out in the picker rather than rejecting them after.

8 AM to 8 PM

Pick a start time.

<script lang="ts">	import { TimeField } from 'omaris';</script>​<TimeField	class="w-56 max-w-full"	variant="filled"	label="Pickup"	min="08:00"	max="20:00"	minuteStep={15}	supportingText="8 AM to 8 PM"/><TimeField	class="w-56 max-w-full"	label="Start time"	required	invalid	supportingText="Pick a start time."/><TimeField class="w-56 max-w-full" label="Logged" disabled value="14:20" />

Overridden

classes reaches the frame's parts and pickerClasses the picker's. A name posts the stored "HH:mm", so the field works in a plain form.

<script lang="ts">	import { TimeField } from 'omaris';</script>​<form class="w-44 max-w-full">	<TimeField		label="Send at"		name="send-at"		size="sm"		value="08:05"		view="input"		classes={{ field: 'rounded-full', value: 'font-mono', icon: 'text-primary' }}		pickerClasses={{ input: 'rounded-full' }}	/></form>

When to use it

Use it for

  • A time in a form: a reminder, a pickup time, a send-at. It reads 2:30 PM until pressed, then opens a Clock Picker under the field — or, on a phone, in a bottom sheet.
  • A span of the day with TimeRangeField: opening hours, a shift, quiet hours that end the next morning.
  • A form posted the plain way: with name, a time goes as 14:30 and a range as 09:00/17:30.

Not for

Do

  • Give it a label, and a placeholder that says what is missing — "Pick a pickup time" rather than a format mask.
  • Put the window in min, max, minuteStep and isTimeDisabled, so the picker greys out what cannot be chosen instead of the form rejecting it.
  • Use the same variant and size as the fields around it; it is the same frame as Input.
  • Use view="input" for a keyboard-heavy desktop form, and showNow when "now" is the usual answer.

Don't

  • Pass it a Date. The value is "HH:mm", stored 24-hour, or null; a range is { start, end }.
  • Leave clearable on for a required time — an × that empties a field that cannot be empty is a trap.
  • Set mobileQuery wider than a phone. The sheet is for a thumb.

API

TimeField

A time input: a field that reads 2:30 PM and opens a ClockPicker — under the field on a desktop, in a bottom sheet on a phone.

It wears Input's frame — the same variants, sizes, label, supporting text and invalid state — so a form that mixes the two lines up.

Typing first on a desktop. Opening it puts the cursor in the hour box, so 9, 3, 0, Enter sets 9:30 without touching the mouse — or paste 9:30 pm. On a phone it opens on the dial instead, where a thumb is faster than a keyboard. Either way nothing changes until OK; Cancel or Escape leaves the field as it was.

The value is "HH:mm", stored 24-hour ("14:30") and shown 12-hour, always — and posted as is with a name.

import { TimeField } from 'omaris'
<TimeField label="Reminder" bind:value={at} minuteStep={5} />

Parts

Every element this renders is reachable from outside. Pass Tailwind for one part as classes={{ part: '…' }}; class covers the root and is merged last, so it always wins.

root
Wrapper: label, field, supporting text.
field
The frame: border, background, height.
control
The button that opens the calendar: the whole frame, minus the clear button.
value
The formatted date, or the placeholder.
placeholder
Added to value while there is no date.
icon
The calendar glyph at the end.
action
The clear button.
label
The label above the frame.
support
The helper or error line under the frame.
panel
The popover the calendar opens in, on a desktop.
sheet
The bottom sheet it opens in, on a phone.

Props

value bindable

Defaults to null

string | null

"HH:mm" stored 24-hour, or null. Bindable.

variant

Defaults to 'outline'

DateFieldVariant

outline, filled or ghost — the same frames as Input.

size

Defaults to 'default'

DateFieldSize

sm, default or lg — the same heights as Input.

label
string

Label above the field.

required

Defaults to false

boolean

Marks the label required.

supportingText
string

Helper line under the field. Turns into the error text when invalid.

invalid

Defaults to false

boolean

Marks the field invalid and wires up aria-invalid.

placeholder

Defaults to 'Select a time'

string

Shown, greyed, while there is no time.

format

Defaults to { hour: 'numeric', minute: '2-digit' }

Intl.DateTimeFormatOptions

Intl.DateTimeFormat options for the text in the field. The hour is always 12-hour.

minuteStep

Defaults to 1

number

Minutes between selectable times.

min
string

Earliest selectable time, "HH:mm". A min later than max wraps over midnight.

max
string

Latest selectable time, "HH:mm".

isTimeDisabled
(time: string, end: RangeEnd) => boolean

Times that cannot be picked.

shape
ShapeName

The outline of the dial's face.

view

Defaults to 'dial'

ClockView

Open on the dial or on the boxes alone. A phone always opens on the dial.

showNow

Defaults to false

boolean

A Now button in the picker.

locale
string

BCP-47 tag for the field and the picker. Defaults to <html lang>.

clearable

Defaults to true

boolean

Show an × that empties the field once it has a time.

open bindable

Defaults to false

boolean

Whether the picker is open. Bindable.

mobileQuery

Defaults to '(max-width: 639px)'

string

What counts as a phone, where the picker opens in a bottom sheet.

labels
ClockPickerLabels

The picker's words, and OK and Cancel.

onchange
(value: string | null) => void

Fires on OK or a clear.

class
string

Merged onto the root wrapper.

classes
DateFieldClasses

Per-part Tailwind overrides for the frame. class still covers the root.

pickerClasses
ClockPickerClasses

Per-part overrides for the picker inside the popup.

ref bindable

Defaults to null

HTMLButtonElement | null

The trigger button.

TimeRangeField

A span of the day in a field — opening hours, a shift, a quiet-hours window. It reads 9:00 AM – 5:30 PM and opens a range ClockPicker: Start and End tabs, the length of the span, a bar that draws it across the day, and optional duration chips.

Moving the start carries the end with it, so a two-hour slot stays two hours. An end before the start runs overnight — 10:00 PM – 6:00 AM — unless overnight={false}. Nothing changes until OK.

The value is { start, end }, each "HH:mm" stored 24-hour, or null; with a name it posts as 09:00/17:30.

import { TimeRangeField } from 'omaris'
<TimeRangeField label="Opening hours" bind:value={hours} minuteStep={15} />

Parts

Every element this renders is reachable from outside. Pass Tailwind for one part as classes={{ part: '…' }}; class covers the root and is merged last, so it always wins.

root
Wrapper: label, field, supporting text.
field
The frame: border, background, height.
control
The button that opens the calendar: the whole frame, minus the clear button.
value
The formatted date, or the placeholder.
placeholder
Added to value while there is no date.
icon
The calendar glyph at the end.
action
The clear button.
label
The label above the frame.
support
The helper or error line under the frame.
panel
The popover the calendar opens in, on a desktop.
sheet
The bottom sheet it opens in, on a phone.

Props

value bindable

Defaults to null

TimeRange | null

{ start, end }, or null. Bindable.

variant

Defaults to 'outline'

DateFieldVariant

outline, filled or ghost — the same frames as Input.

size

Defaults to 'default'

DateFieldSize

sm, default or lg — the same heights as Input.

label
string

Label above the field.

required

Defaults to false

boolean

Marks the label required.

supportingText
string

Helper line under the field. Turns into the error text when invalid.

invalid

Defaults to false

boolean

Marks the field invalid and wires up aria-invalid.

placeholder

Defaults to 'Select a time range'

string

Shown, greyed, while there is no range.

format

Defaults to { hour: 'numeric', minute: '2-digit' }

Intl.DateTimeFormatOptions

Intl.DateTimeFormat options for the two ends. The hour is always 12-hour.

minuteStep

Defaults to 1

number

Minutes between selectable times.

min
string

Earliest selectable time for either end, "HH:mm".

max
string

Latest selectable time for either end, "HH:mm".

isTimeDisabled
(time: string, end: RangeEnd) => boolean

Times that cannot be picked. end says which end is asking.

overnight

Defaults to true

boolean

A range may end the next day. On by default.

minDuration
number

Shortest range, in minutes.

maxDuration
number

Longest range, in minutes.

durations

Defaults to []

number[]

Chips that set the end this many minutes after the start.

shape
ShapeName

The outline of the dial's face.

view

Defaults to 'dial'

ClockView

Open on the dial or on the boxes alone. A phone always opens on the dial.

locale
string

BCP-47 tag for the field and the picker. Defaults to <html lang>.

clearable

Defaults to true

boolean

Show an × that empties the field once it has a range.

open bindable

Defaults to false

boolean

Whether the picker is open. Bindable.

mobileQuery

Defaults to '(max-width: 639px)'

string

What counts as a phone, where the picker opens in a bottom sheet.

labels
ClockPickerLabels

The picker's words, and OK and Cancel.

onchange
(value: TimeRange | null) => void

Fires on OK or a clear.

class
string

Merged onto the root wrapper.

classes
DateFieldClasses

Per-part Tailwind overrides for the frame. class still covers the root.

pickerClasses
ClockPickerClasses

Per-part overrides for the picker inside the popup.

ref bindable

Defaults to null

HTMLButtonElement | null

The trigger button.