TimeField

The <TimeField> allows users to enter and edit time values using the keyboard. Each part of the time value—such as hour, minute, and optionally AM/PM—is displayed in an individually editable segment. These segments are focusable and can be incremented or decremented using the arrow keys, or edited by typing. This segmented approach ensures correct formatting and parsing of time values across different locales and hour cycles, and provides a reliable, keyboard-friendly way to input time.

Anatomy

A <TimeField> consists of a label and a group of segments representing each unit of a time, such as hours, minutes and seconds.

Appearance

The appearance of a component can be customized using the variant and size props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.

Variant

Size

The selected theme does not has any options for "variant" and "size".

Event time

145PM

Property	Type	Description
`variant`	`-`	The available variants of this component.
`size`	`-`	The available sizes of this component.

Usage

The <TimeField> component is a flexible input element for selecting times within forms. It improves user experience by offering a clear and structured way to enter time values, minimizing errors from manual input. With support for labels, descriptions, and time formatting options like 12- or 24-hour cycles, it communicates its function effectively. The component also allows setting default values and customizing granularity (e.g., hours, minutes, seconds). This makes the <TimeField> ideal for applications that require accurate and accessible time selection.

Min/Max Values

The minValue and maxValue props are used to perform built-in validation. This prevents the user from choosing times outside the valid range.

Preview

Code

Pick a time

1200PM

Time must be during office hours form 09:00 - 17:00

Props

Did you know? You can explore, test, and customize props live in Marigold's storybook. Watch the effects they have in real-time!

View TimeField stories

aria-describedby?

string;

Identifies the element (or elements) that describes the object.

aria-details?

string;

Identifies the element (or elements) that provide a detailed, extended description for the object.

aria-label?

string;

Defines a string value that labels the current element.

aria-labelledby?

string;

Identifies the element (or elements) that labels the current element.

autoFocus?

boolean;

Whether the element should receive focus on render.

defaultValue?

TimeValue | null;

The default value (uncontrolled).

description?

ReactNode;

A helpful text.

disabled?

boolean;

If true, the input is disabled.

Defaults to:

"false"

error?

boolean;

If true, the field is considered invalid and if set the errorMessage is shown instead of the description.

Defaults to:

"false"

errorMessage?

ReactNode | ((v: ValidationResult) => ReactNode);

An error message.

granularity?

"hour" | "minute" | "second";

Determines the smallest unit that is displayed in the time picker.

Defaults to:

"minute"

hideTimeZone?

boolean;

Whether to hide the time zone abbreviation.

hourCycle?

12 | 24;

Whether to display the time in 12 or 24 hour format

Defaults to:

id?

string;

The element's unique identifier. See MDN.

label?

ReactNode;

Specifies the label of the field.

maxValue?

TimeValue | null;

The maximum allowed time that a user may select.

minValue?

TimeValue | null;

The minimum allowed time that a user may select.

name?

string;

The name of the input element, used when submitting an HTML form. See MDN.

onBlur?

(e: FocusEvent<Element, Element>) => void;

Handler that is called when the element loses focus.

onChange?

(value: TimeValue | null) => void;

Handler that is called when the value changes.

onFocus?

(e: FocusEvent<Element, Element>) => void;

Handler that is called when the element receives 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.

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.

readOnly?

boolean;

If true, the input is readOnly.

Defaults to:

"false"

ref?

Ref<HTMLInputElement>;

Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref). @see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}

required?

boolean;

If true, the input is required.

Defaults to:

"false"

shouldForceLeadingZeros?

boolean;

Whether to always show leading zeros in the hour field. Default is determined by the user's locale.

Defaults to:

"none"

validate?

(value: TimeValue) => true | ValidationError | null;

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.

validationBehavior?

"native" | "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.

Defaults to: