TimeField

Usage

import { TimeField } from '@heroui/react';

Anatomy

import {TimeField, Label, Description, FieldError} from '@heroui/react';

export default () => (
  <TimeField>
    <Label />
    <TimeField.Group>
      <TimeField.Input>
        {(segment) => <TimeField.Segment segment={segment} />}
      </TimeField.Input>
    </TimeField.Group>
    <Description />
    <FieldError />
  </TimeField>
)

TimeField combines label, time input, description, and error into a single accessible component.

Examples

With Icons

Add prefix or suffix icons to enhance the time field.

On Surface

When used inside a Surface component, use variant="secondary" on TimeField.Group to apply the lower emphasis variant suitable for surface backgrounds.

With Description

Required Field

Disabled State

Full Width

Validation

Use isInvalid together with FieldError to surface validation messages.

Controlled

Control the value to synchronize with other components or state management.

Form Example

Complete form example with validation and submission handling.

With Validation

TimeField supports validation with minValue, maxValue, and custom validation logic.

Render Function

<ComponentPreview name="time-field-render-function" />

Customization

Tailwind CSS

Global CSS

TimeField has minimal default styling. Override the .time-field class to customize the container styling.

@layer components {
  .time-field {
    @apply flex flex-col gap-1;

    &[data-invalid="true"],
    &[aria-invalid="true"] {
      [data-slot="description"] {
        @apply hidden;
      }
    }

    [data-slot="label"] {
      @apply w-fit;
    }

    [data-slot="description"] {
      @apply px-1;
    }
  }
}

Styling Reference

HeroUI follows the BEM methodology to ensure component variants and states are reusable and easy to customize.

CSS Classes

• .time-field – Root container with minimal styling (flex flex-col gap-1)

Note: Child components (Label, Description, FieldError) have their own CSS classes and styling. See their respective documentation for customization options. TimeField.Group styling is documented below in the API Reference section.

Interactive States

TimeField automatically manages these data attributes based on its state:

• Invalid: [data-invalid="true"] or [aria-invalid="true"] - Automatically hides the description slot when invalid
• Required: [data-required="true"] - Applied when isRequired is true
• Disabled: [data-disabled="true"] - Applied when isDisabled is true
• Focus Within: [data-focus-within="true"] - Applied when any child input is focused

API Reference

TimeField

TimeField inherits all props from React Aria's TimeField component.

Base Props

Value Props

Validation Props

Format Props

State Props

Form Props

Accessibility Props

Composition Components

TimeField works with these separate components that should be imported and used directly:

• Label - Field label component from @heroui/react
• TimeField.Group - Time input group component (documented below)
• TimeField.Input - Input component with segmented editing from @heroui/react
• TimeField.Segment - Individual time segment (hour, minute, second, etc.)
• TimeField.Prefix / TimeField.Suffix - Prefix and suffix slots for the input group
• Description - Helper text component from @heroui/react
• FieldError - Validation error message from @heroui/react

Each of these components has its own props API. Use them directly within TimeField for composition:

import {parseTime} from '@internationalized/date';
import {TimeField, Label, Description, FieldError} from '@heroui/react';

<TimeField
  isRequired
  isInvalid={hasError}
  minValue={parseTime('09:00')}
  maxValue={parseTime('17:00')}
  value={time}
  onChange={setTime}
>
  <Label>Appointment Time</Label>
  <TimeField.Group>
    <TimeField.Input>
      {(segment) => <TimeField.Segment segment={segment} />}
    </TimeField.Input>
  </TimeField.Group>
  <Description>Select a time between 9:00 AM and 5:00 PM.</Description>
  <FieldError>Please select a valid time.</FieldError>
</TimeField>

TimeValue Types

TimeField uses types from @internationalized/date:

• Time - Time only (hour, minute, second)
• CalendarDateTime - Date with time but no timezone (TimeField displays only the time portion)
• ZonedDateTime - Date with time and timezone (TimeField displays only the time portion)

Example:

import {parseTime, Time, getLocalTimeZone, now} from '@internationalized/date';

// Parse from string
const time = parseTime('14:30');

// Create from current time
const currentTime = now(getLocalTimeZone());
const timeValue = new Time(currentTime.hour, currentTime.minute, currentTime.second);

// Use in TimeField
<TimeField value={time} onChange={setTime}>
</TimeField>

Note: TimeField uses the @internationalized/date package for time manipulation, parsing, and type definitions. See the Internationalized Date documentation for more information about available types and functions.

Render Props

When using render props with className, style, or children, these values are available:

TimeField.Group

TimeField.Group accepts all props from React Aria's Group component plus the following:

TimeField.Input

TimeField.Input accepts all props from React Aria's DateInput component plus the following:

The TimeField.Input component accepts a render prop function that receives date segments. Each segment represents a part of the time (hour, minute, second, etc.).

TimeField.Segment

TimeField.Segment accepts all props from React Aria's DateSegment component:

TimeField.Prefix

TimeField.Prefix accepts standard HTML div attributes:

TimeField.Suffix

TimeField.Suffix accepts standard HTML div attributes:

TimeField.Group Styling

Customizing the component classes

The base classes power every instance. Override them once with @layer components.

@layer components {
  .date-input-group {
    @apply inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none;

    &:hover,
    &[data-hovered="true"] {
      @apply bg-field-hover;
    }

    &[data-focus-within="true"],
    &:focus-within {
      @apply status-focused-field;
    }

    &[data-invalid="true"] {
      @apply status-invalid-field;
    }

    &[data-disabled="true"],
    &[aria-disabled="true"] {
      @apply status-disabled;
    }
  }

  .date-input-group__input {
    @apply flex flex-1 items-center gap-px rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
  }

  .date-input-group__segment {
    @apply inline-block rounded-md px-0.5 text-end tabular-nums outline-none;

    &:focus,
    &[data-focused="true"] {
      @apply bg-accent-soft text-accent-soft-foreground;
    }
  }

  .date-input-group__prefix,
  .date-input-group__suffix {
    @apply pointer-events-none shrink-0 text-field-placeholder flex items-center;
  }
}

TimeField.Group CSS Classes

• .date-input-group – Root container styling
• .date-input-group__input – Input wrapper styling
• .date-input-group__segment – Individual time segment styling
• .date-input-group__prefix – Prefix element styling
• .date-input-group__suffix – Suffix element styling

TimeField.Group Interactive States

• Hover: :hover or [data-hovered="true"]
• Focus Within: [data-focus-within="true"] or :focus-within
• Invalid: [data-invalid="true"] (also syncs with aria-invalid)
• Disabled: [data-disabled="true"] or [aria-disabled="true"]
• Segment Focus: :focus or [data-focused="true"] on segment elements
• Segment Placeholder: [data-placeholder="true"] on segment elements

Related Components