DateFieldNew

Import

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

Usage

"use client";

import {DateField, DateInputGroup, Label} from "@heroui/react";

export function Basic() {

Anatomy

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

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

DateField combines label, date input, description, and error into a single accessible component.

With Description

"use client";

import {DateField, DateInputGroup, Description, Label} from "@heroui/react";

export function WithDescription() {

Required Field

"use client";

import {DateField, DateInputGroup, Description, Label} from "@heroui/react";

export function Required() {

Validation

Use isInvalid together with FieldError to surface validation messages.

"use client";

import {DateField, DateInputGroup, FieldError, Label} from "@heroui/react";

export function Invalid() {

With Validation

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

"use client";

import type {DateValue} from "@internationalized/date";

import {DateField, DateInputGroup, Description, FieldError, Label} from "@heroui/react";

Controlled

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

"use client";

import type {DateValue} from "@internationalized/date";

import {Button, DateField, DateInputGroup, Description, Label} from "@heroui/react";

Disabled State

"use client";

import {DateField, DateInputGroup, Description, Label} from "@heroui/react";
import {getLocalTimeZone, today} from "@internationalized/date";

With Icons

Add prefix or suffix icons to enhance the date field.

"use client";

import {Calendar} from "@gravity-ui/icons";
import {DateField, DateInputGroup, Label} from "@heroui/react";

"use client";

import {Calendar} from "@gravity-ui/icons";
import {DateField, DateInputGroup, Label} from "@heroui/react";

"use client";

import {Calendar, ChevronDown} from "@gravity-ui/icons";
import {DateField, DateInputGroup, Description, Label} from "@heroui/react";

Full Width

"use client";

import {Calendar, ChevronDown} from "@gravity-ui/icons";
import {DateField, DateInputGroup, Label} from "@heroui/react";

On Surface

When used inside a Surface component, DateField and its child DateInputGroup automatically apply on-surface styling.

"use client";

import {Calendar} from "@gravity-ui/icons";
import {DateField, DateInputGroup, Description, Label, Surface} from "@heroui/react";

Form Example

Complete form example with validation and submission handling.

"use client";

import type {DateValue} from "@internationalized/date";

import {Calendar} from "@gravity-ui/icons";

Styling

Passing Tailwind CSS classes

import {DateField, Label, DateInputGroup, Description} from '@heroui/react';

function CustomDateField() {
  return (
    <DateField className="gap-2 rounded-xl border border-border/60 bg-surface p-4 shadow-sm">
      <Label className="text-sm font-semibold text-default-700">
        Appointment date
      </Label>
      <DateInputGroup className="rounded-lg border border-border/60 bg-surface px-3 py-2">
        <DateInputGroup.Input>
          {(segment) => <DateInputGroup.Segment segment={segment} />}
        </DateInputGroup.Input>
      </DateInputGroup>
      <Description className="text-xs text-default-500">
        Select a date for your appointment.
      </Description>
    </DateField>
  );
}

Customizing the component classes

DateField has minimal default styling. Override the .date-field class to customize the container styling.

@layer components {
  .date-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;
    }
  }
}

CSS Classes

• .date-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. DateInputGroup styling is documented below in the API Reference section.

Interactive States

DateField 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

DateField Props

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

Base Props

Value Props

Validation Props

Format Props

State Props

Form Props

Accessibility Props

Composition Components

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

• Label - Field label component from @heroui/react
• DateInputGroup - Date input component with segmented editing from @heroui/react (documented below)
• 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 DateField for composition:

import {parseDate} from '@internationalized/date';
import {DateField, Label, DateInputGroup, Description, FieldError} from '@heroui/react';

<DateField
  isRequired
  isInvalid={hasError}
  minValue={today(getLocalTimeZone())}
  value={date}
  onChange={setDate}
>
  <Label>Appointment Date</Label>
  <DateInputGroup>
    <DateInputGroup.Input>
      {(segment) => <DateInputGroup.Segment segment={segment} />}
    </DateInputGroup.Input>
  </DateInputGroup>
  <Description>Select a date from today onwards.</Description>
  <FieldError>Please select a valid date.</FieldError>
</DateField>

DateValue Types

DateField uses types from @internationalized/date:

• CalendarDate - Date without time or timezone
• CalendarDateTime - Date with time but no timezone
• ZonedDateTime - Date with time and timezone
• Time - Time only

Example:

import {parseDate, today, getLocalTimeZone} from '@internationalized/date';

// Parse from string
const date = parseDate('2024-01-15');

// Today's date
const todayDate = today(getLocalTimeZone());

// Use in DateField
<DateField value={date} onChange={setDate}>
  {/* ... */}
</DateField>

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

DateFieldRenderProps

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

DateInputGroup Props

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

DateInputGroup.Input Props

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

The DateInput component accepts a render prop function that receives date segments. Each segment represents a part of the date (year, month, day, etc.).

DateInputGroup.Segment Props

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

DateInputGroup.Prefix Props

DateInputGroup.Prefix accepts standard HTML div attributes:

DateInputGroup.Suffix Props

DateInputGroup.Suffix accepts standard HTML div attributes:

DateInputGroup 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;
  }
}

DateInputGroup CSS Classes

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

DateInputGroup 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