Components
Date and time
Time Field

Time Field

TimeFields allow users to enter and edit time values using a keyboard.

Aria docs Report an issue Edit this page

––

default.tsx

<TimeField aria-label="Event time" />

Installation

npm

pnpm

yarn

bun

npx dotui-cli@latest add time-field

Usage

Use a TimeField to allow users to enter and edit time values using a keyboard.

import { TimeField } from "@/components/core/time-field";
 
<TimeField label="Event time" description="Please select your event time." />;

import { Label, Description } from "@/components/dynamic-core/field";
import {
  TimeFieldRoot,
  TimeFieldInput,
} from "@/components/dynamic-core/time-field";
 
<TimeFieldRoot>
  <Label>Meeting time</Label>
  <TimeFieldInput />
  <Description>Please select a time between 9 AM and 5 PM.</Description>
  <FieldError />
</TimeFieldRoot>;

Uncontrolled

An initial, uncontrolled value can be provided to the TimeField using the defaultValue prop.

uncontrolled.tsx

<TimeField aria-label="Event time" defaultValue={new Time(11, 45)} />

Controlled

Use the value and onChange props to control the value of the input.

selected time: 11:45:00

controlled.tsx

const [time, setTime] = React.useState(new Time(11, 45));
return <TimeField aria-label="Event time" value={time} onChange={setTime} />

Options

Label

A visual label can be provided for the TimeField using the label prop or a hidden label using aria-label prop.

Event time

––

label.tsx

<TimeField label="Event time" />
<TimeField aria-label="Event time" />

Size

Use the size prop to control the size of the TimeField.
The default variant is "md".

small (sm)

––

medium (md)

––

large (lg)

––

sizes.tsx

<TimeField label="small (sm)" size="sm" />
<TimeField label="medium (md)" size="md" />
<TimeField label="large (lg)" size="lg" />

Prefix and suffix

To add additional context for the TimeField, such as an icon, use the prefix and suffix props.

––

prefix-and-suffix.tsx

<TimeField aria-label="Event time" prefix={<TimerIcon />} />
<TimeField aria-label="Event time" suffix={<TimerIcon />} />

Description

A description can be supplied to TimeField via the description prop. The description is always visible unless the isInvalid prop is true and an error message is provided.

Appointment

––

Please select a time between 9 AM and 5 PM.

description.tsx

<TimeField label="Appointment" description="Please select a time between 9 AM and 5 PM." />

Error message

An errorMessage can be supplied to TimeField via the errorMessage prop, which will be displayed when the isInvalid prop is set to true.

Meeting

––

Meetings start every 15 minutes.

error-message.tsx

<TimeField label="Meeting" isInvalid errorMessage="Meetings start every 15 minutes." />

Disabled

Use the isDisabled prop to disable the TimeField.

Event time

––

disabled.tsx

<TimeField label="Event time" isDisabled />

ReadOnly

The isReadOnly boolean prop makes the TimeField's text content immutable. Unlike isDisabled, the TimeField remains focusable and the contents can still be copied.

Event time

read-only.tsx

<TimeField label="Event time" value={new Time(11)} isReadOnly />

Required

Use the isRequired prop to mark the TimeField as required. Use the necessityIndicator prop to control the visual style of the required state.

Event time

––

required.tsx

<TimeField label="Event time" isRequired />
<TimeField label="Event time" isRequired necessityIndicator="icon" />
<TimeField label="Event time" isRequired necessityIndicator="label" />
<TimeField label="Event time" necessityIndicator="label" />

Value options

Time zones

TimeField is time zone aware when a ZonedDateTime object is provided as the value.

UTC

time-zones.tsx

<TimeField
  aria-label="Event time"
  defaultValue={parseAbsoluteToLocal("2021-11-07T07:45:00Z")}
/>

Granularity

The granularity prop allows you to control the smallest unit that is displayed by TimeField.

UTC

granularity.tsx

<TimeField
  aria-label="Event time"
  granularity="second"
  defaultValue={parseAbsoluteToLocal("2021-04-07T18:45:22Z")}
/>

Format Options

Placeholder value

placeholderValue controls the default values of each segment when the user first interacts with them, e.g. using the up and down arrow keys. The default value is midnight.

––

placeholder.tsx

<TimeField aria-label="Event time" placeholderValue={new Time(9)} />

Hide time zone

Use the hideTimeZone prop to hide the time zone abbreviation.

hide-time-zone.tsx

<TimeField
  aria-label="Appointment time"
  defaultValue={parseZonedDateTime("2022-11-07T10:45[America/Los_Angeles]")}
  hideTimeZone
/>

Hour cycle

Use the hourCycle prop to control the hour cycle of the TimeField.

––

hour-cycle.tsx

<TimeField aria-label="Appointment time" hourCycle={24} />

Composition

If you need to customize things further, you can drop down to the composition level.

Meeting time

––

Please select a time between 9 AM and 5 PM.

composition.tsx

<TimeFieldRoot>
  <Label>Meeting time</Label>
  <TimeFieldInput />
  <Description>Please select a time between 9 AM and 5 PM.</Description>
  <FieldError />
</TimeFieldRoot>

API Reference

Prop	Type	Default	Description
`hourCycle`	`12 \| 24`	`'minute'`	Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale.
`granularity`	`'hour' \| 'minute' \| 'second'`	-	Determines the smallest unit that is displayed in the time picker.
`hideTimeZone`	`boolean`	-	Whether to hide the time zone abbreviation.
`shouldForceLeadingZeros`	`boolean`	-	Whether to always show leading zeros in the hour field. By default, this is determined by the user's locale.
`placeholderValue`	`TimeValue`	-	A placeholder time that influences the format of the placeholder shown when no value is selected. Defaults to 12:00 AM or 00:00 depending on the hour cycle.
`minValue`	`TimeValue`	-	The minimum allowed time that a user may select.
`maxValue`	`TimeValue`	-	The maximum allowed time that a user may select.
`isDisabled`	`boolean`	-	Whether the input is disabled.
`isReadOnly`	`boolean`	-	Whether the input can be selected but not changed by the user.
`isRequired`	`boolean`	-	Whether user input is required on the input before form submission.
`isInvalid`	`boolean`	-	Whether the input value is invalid.
`validate`	`(value: MappedTimeValue<TimeValue>) => ValidationError \| true \| null \| undefined`	-	A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.
`autoFocus`	`boolean`	-	Whether the element should receive focus on render.
`value`	`TimeValue \| null`	-	The current value (controlled).
`defaultValue`	`TimeValue \| null`	-	The default value (uncontrolled).
`name`	`string`	-	The name of the input element, used when submitting an HTML form.
`validationBehavior`	`'native' \| 'aria'`	`'aria'`	Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
`children`	`ReactNode \| (values: DateFieldRenderProps & {defaultChildren: ReactNode \| undefined}) => ReactNode`	-	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string`	-	The CSS className for the element.
`style`	`CSSProperties \| (values: DateFieldRenderProps & {defaultStyle: CSSProperties}) => CSSProperties`	-	The inline style for the element. A function may be provided to compute the style based on component state.

Event	Type	Description
`onChange`	`(value: MappedTimeValue<TimeValue>) => void`	Handler that is called when the value changes.
`onFocus`	`(e: FocusEvent<Target>) => void`	Handler that is called when the element receives focus.
`onBlur`	`(e: FocusEvent<Target>) => void`	Handler that is called when the element loses focus.
`onFocusChange`	`(isFocused: boolean) => void`	Handler that is called when the element's focus status changes.
`onKeyDown`	`(e: KeyboardEvent) => void`	Handler that is called when a key is pressed.
`onKeyUp`	`(e: KeyboardEvent) => void`	Handler that is called when a key is released.

Accessibility

Keyboard interactions

Key	Description
`Tab`	Places focus on the first segment. If a segment is already in focus, moves focus to the next segment. If last segment in in focus, moves focus to the next element in the page tab sequence.
`ArrowRight` `ArrowLeft`	Moves focus between segments.
`ArrowUp` `ArrowDown`	Increments/decrements the value of the segment.

Range Calendar Date Field

dotUI

Bringing singularity to the web.

Product

Community

Support

Built by mehdibha. The source code is available on GitHub.

Buttons

Forms and inputs

Menus and selection

Date and time

Colors

Drag and drop

Feedback

Data display

Navigation

Overlays

Time Field

Installation

Usage

Uncontrolled

Controlled

Options

Label

Size

Prefix and suffix

Description

Error message

Disabled

ReadOnly

Required

Value options

Time zones

Granularity

Format Options

Placeholder value

Hide time zone

Hour cycle

Composition

API Reference

Accessibility

Keyboard interactions

Product

Community

Support