TimePicker

Import

import { TimePicker } from '@envsemble/envui';

Usage

<TimePicker label="Starts at" value={start} onValueChange={setStart} clearable />

The value is a time of day as HH:mm on the 24-hour clock, or null for none: control it with value and onValueChange, which receives HH:mm, or null once the field is cleared, or leave it uncontrolled with defaultValue. It shows the value and its wheels on the clock of locale, EnvUIProvider's or else the browser's, unless hourCycle sets one: h23 for 18:00 with no AM/PM wheel, h12 for 6:00 PM. formatOptions sets how the field shows it, as Intl.DateTimeFormat options, by default the short time style. label, description and error work as on TextField. clearable adds a clear button to the field and the popup, named by clearLabel, and nowLabel names the popup's shortcut to the current time. The popup stays open as its wheels turn.

Available times

min and max, as HH:mm, are the earliest and latest times. minuteStep is the minutes between the times the list offers, from 1 to 60, 15 by default.

In a form

<form onSubmit={submit}>
  <TimePicker label="From" name="from" defaultValue="09:00" required />
  <TimePicker label="To" name="to" defaultValue="17:00" required error={error} />
  <Button type="submit">Save shift</Button>
</form>

name submits the time as HH:mm, without a date or a zone, so two times compare as text; a form reset restores defaultValue, and required keeps an empty field's form from submitting and focuses it. Use readOnly, not disabled, to show a time people can't change. For one moment, a day and a time, use a single DatePicker with granularity="minute".

Sizes

size is sm, md or lg; without it, the field takes its container's control height. visibleLabel={false} hides the label, with a placeholder while the field is empty.

Composition

TimePicker shares DatePicker's field and its picker card, env-picker-popup with env-date-picker-popup and env-time-picker-popup: the wheels in its body, env-picker-popup-body, and Now and Clear in its footer, env-picker-popup-footer with env-date-picker-actions. The wheels are for hours, minutes and, on a 12-hour clock, the day period, each row an env-time-list-row, the chosen one with data-centered. className and style reach the root, and ref the field's button.

Customize

Its popup is frosted, as every popup is: --env-popup-opacity, --env-popup-blur and --env-popup-shadow, set on a theme, change it, as Popover describes.

Accessibility

You provide

A label, or aria-label on a field without one.
Validation and its error.
The labels in the application's language.

envUI provides

The field as a combobox button named by its label, with its description and error.
Each wheel a spinbutton named Hours, Minutes or AM/PM, with the time as the locale writes it.

Props

A field for a time of day that shows the value in the reader's locale and opens wheels of its hours, minutes every `minuteStep` and, on a 12-hour clock, the day's halves to choose it.

Prop	Type	Description
`value`	`stringnull`	The value: a time of day as HH:mm on the 24-hour clock. null, or an empty string, for none.
`defaultValue`Default `null`	`stringnull`	The value an uncontrolled field starts with, and that a form reset restores; none by default.
`onValueChange`	`(value: string \| null) => void`	Receives the new value as HH:mm, or null once the field is cleared.
`min`	`string`	The earliest time, as HH:mm; earlier times are unavailable.
`max`	`string`	The latest time, as HH:mm; later times are unavailable.
`minuteStep`Default `15`	`number`	The minutes between the times the list offers, from 1 to 60. A value between them still shows in the list, in its place.
`locale`	`string`	The locale of the shown value and the list's times, with its own 12- or 24-hour clock unless `hourCycle` sets one: EnvUIProvider's, else the browser's.
`hourCycle`Default `the locale's`	`'h12''h23'`	The clock of the shown value and the wheels, whatever the locale's: h23 for 18:00, with no AM/PM wheel, or h12 for 6:00 PM. The value stays HH:mm on the 24-hour clock.
`formatOptions`	`Intl.DateTimeFormatOptions`	How the field shows the value: Intl.DateTimeFormat options, by default the short time style.
`clearLabel`Default `'Clear', or EnvUIProvider's messages.timePicker.clear`	`string`	Accessible name of the field's clear button and text of the popup's.
`nowLabel`Default `'Now', or EnvUIProvider's messages.timePicker.now`	`string`	The popup's shortcut to the current time.
`ref`	`Ref<HTMLButtonElement>`	The field's button, which shows the value and opens the popup.
`className`	`string`	The field's class, on its root element.
`style`	`CSSProperties`	Styles of the field's root element.
`name`	`string`	The name the value is submitted under with a form.
`required`Default `false`	`boolean`	A value is needed: an empty field keeps its form from submitting and takes focus.
`readOnly`Default `false`	`boolean`	The value can be read and focused but not changed.
`placeholder`	`string`	Shown while the field is empty and its label floats or is hidden.
`clearable`Default `false`	`boolean`	A clear button in the field and in the popup removes the value.
`open`	`boolean`	Whether the popup is open; with `onOpenChange` it controls it.
`defaultOpen`Default `false`	`boolean`	Whether an uncontrolled popup starts open; closed by default.
`onOpenChange`	`(open: boolean, details: PickerOpenChangeDetails) => void`	Called with the new state, and why, when the popup opens or closes.
`label`	`ReactNode`	The field's visible name, such as Project name; it also names the control for assistive technology.
`description`	`ReactNode`	Lasting guidance under the field, such as a format or a limit, linked to the control as its description.
`error`	`ReactNode`	A message under the field that says how to correct the value. While it is set, the control is invalid (aria-invalid) and the message joins its description, after the description.
`size`	`'sm''md''lg'`	The control height, sm, md or lg; without it, the container's, and else md. sm is for a field with its label hidden.
`visibleLabel`Default `true`	`boolean`	The label shows in the field, where it rests while the field is empty and floats into the outline while the field is in use or has a value. false hides it, for a field whose purpose is clear without it, such as a search in a toolbar: the label still names the field for assistive technology, and a placeholder gives the visible guidance.

Also accepts the native props of <button>, such as ref, className and aria-* attributes.

Part names

Each part's class and state attributes are public and versioned, for an application's CSS to style.

env-time-picker: The time field.
env-time-picker-popup: The popup with the times.

Strings

EnvUIProvider's messages overrides each, and a component's own label prop wins over it.

messages.timePicker.clear: "Clear" The clear button's name.
messages.timePicker.now: "Now" Picks the current time.
messages.timePicker.hours: "Hours" Names the column of hours.
messages.timePicker.minutes: "Minutes" Names the column of minutes.
messages.timePicker.dayPeriod: "AM/PM" Names the column of the day's halves, on a 12-hour clock.

Changelog

1.0.0: showLabel is visibleLabel, named after the label that visibleLabel={false} hides.

TimePicker, for a time of day chosen on wheels of hours, minutes and day periods on the locale's clock, with minuteStep, min and max.
1.0.0-prerelease.6: The popup opens over --env-motion-duration-medium, fading in and growing from 98 % with --env-motion-ease-enter, rather than growing from 96 % over the slow duration, so it shows from its first frames rather than late.

A mouse drags a wheel as a finger does: the rows follow the pointer while its button is down, and a quick drag let go glides on and eases into a row; a press that doesn't move still chooses the row under it.

As a wheel turns to a row pressed or scrolled to, the fill stays on that row rather than passing over the rows on the way, and a row's text takes the fill's color only while it is on the fill, so a value it leaves is never white on the popup; the field shows the new time once the wheel comes to rest.

hourCycle, h12 or h23, sets the clock of the field and its wheels whatever the locale's, such as 18:00 with no AM/PM wheel in English; the value stays HH:mm.

The wheels' rows are a little less than a row height tall, as the calendar's days are, 24 px at the compact scale; touch screens keep the touch height.

A clearable field's clear button and its clock icon stand a step apart, so they don't crowd each other in a small field.

While its list of times is open, the field keeps its focused frame, the accent edge and label, also when focus is in the popup, as when it opens under the pointer.

The chosen hour and minute take the chosen day's solid accent fill rather than the selection's tint, and are round and as tall as a day, as the chosen day is, so a chosen day and time look alike and the wheels stay narrow; a wheel with fewer values than it shows rows, such as minutes every 15, no longer loops and shows a value twice, while its arrow keys still wrap around. A light fade at a wheel's edges hints that it scrolls, while every value it shows stays legible, and times outside min and max are struck through in the disabled color, so they no longer look like the fade.

The floating variant and the variant prop are gone: the field is outlined, and takes size="lg" in a long form on a page. The field takes a text area's rounded corners rather than round ends. A small one with a visible label takes the medium height, so its floated label and its value each have room, and says so in the console while developing: sm is for a field with its label hidden.
1.0.0-prerelease.5: The popup is frosted: the popup's color lets a little of what is behind through, blurred, with a soft shadow and no outline edge but a faint hairline in dark, and is solid with its edge at high contrast and with reduced transparency. Its inset is a panel's, as wide as a popup row's corner: 14 px, 11.2 px at the compact scale.