Time Field

<TimeField />

Installation

npm install react-aria-components

"use client";

import * as React from "react";
import {
  TimeField as AriaTimeField,
  type TimeFieldProps as AriaTimeFieldProps,
  type TimeValue,
} from "react-aria-components";
import { tv, type VariantProps } from "tailwind-variants";
import { DateInput, DateSegment } from "./date-input";
import { Field, type FieldProps } from "./field";
import { InputRoot, type inputStyles } from "./input";

const timeFieldStyles = tv({
  slots: {
    root: "flex flex-col items-start gap-2",
  },
});

interface TimeFieldProps<T extends TimeValue>
  extends TimeFieldRootProps<T>,
    Omit<FieldProps, "children">,
    VariantProps<typeof inputStyles> {
  prefix?: React.ReactNode;
  suffix?: React.ReactNode;
  isLoading?: boolean;
  loaderPosition?: "prefix" | "suffix";
}

const TimeField = <T extends TimeValue>({
  className,
  size,
  label,
  description,
  errorMessage,
  prefix,
  suffix,
  isLoading,
  loaderPosition = "suffix",
  isRequired,
  isDisabled,
  necessityIndicator,
  contextualHelp,
  ...props
}: TimeFieldProps<T>) => {
  return (
    <TimeFieldRoot
      className={className}
      isRequired={isRequired}
      isDisabled={isLoading || isDisabled}
      {...props}
    >
      <Field
        label={label}
        description={description}
        errorMessage={errorMessage}
        isRequired={isRequired}
        necessityIndicator={necessityIndicator}
        contextualHelp={contextualHelp}
      >
        <InputRoot
          size={size}
          prefix={prefix}
          suffix={suffix}
          isLoading={isLoading}
          loaderPosition={loaderPosition}
        >
          <DateInput>{(segment) => <DateSegment segment={segment} />}</DateInput>
        </InputRoot>
      </Field>
    </TimeFieldRoot>
  );
};

interface TimeFieldRootProps<T extends TimeValue> extends Omit<AriaTimeFieldProps<T>, "className"> {
  className?: string;
}
const TimeFieldRoot = <T extends TimeValue>({ className, ...props }: TimeFieldRootProps<T>) => {
  const { root } = timeFieldStyles();
  return <AriaTimeField className={root({ className })} {...props} />;
};

export type { TimeFieldProps, TimeFieldRootProps };
export { TimeField, TimeFieldRoot };

Usage

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

Options

Label

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

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

Sizes

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

<TimeField size="sm" />
<TimeField size="md" />
<TimeField size="lg" />

Prefix and suffix

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

<TimeField prefix={<TimerIcon />} />
<TimeField 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.

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

Contextual help

A ContextualHelp element may be placed next to the label to provide additional information or help about a TimeField.

<TimeField
  label="Appointment"
  contextualHelp={<ContextualHelp />  }
/>

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.

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

Time zones

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

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

Granularity

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

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

Placeholder value

Use the placeholderValue prop to control the default values of each segment. The default value is midnight.

<TimeField placeholderValue={new Time(9)} />

Hide time zone

Use the hideTimeZone prop to hide the time zone abbreviation.

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

Hour cycle

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

<TimeField hourCycle={24} />

Loading

Use the isLoading prop to control the loading state of the TimeField. Use the loaderPosition prop to control the position of the loader.

<TimeField isLoading loaderPosition="prefix" />
<TimeField isLoading loaderPosition="suffix" />

Disabled

Use the isDisabled prop to disable the TimeField.

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

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

<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" />

Uncontrolled

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

<TimeField defaultValue={new Time(11, 45)} />

Controlled

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

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

Composition

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

<TimeFieldRoot>
  <Label>Meeting time</Label>
  <InputRoot>
    <DateInput>{(segment) => <DateSegment segment={segment} />}</DateInput>
  </InputRoot>
  <Description>Please select a time between 9 AM and 5 PM.</Description>
</TimeFieldRoot>

API Reference

Accessibility

Keyboard interactions