DatePicker | HeroUI v3 (Previously NextUI) - Beautiful by default, customizable by design.

Import

import { DatePicker, DateField, Calendar, Label } from '@heroui/react';

Usage

Date

mmddyyyy

"use client";

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

export function Basic() {

Anatomy

DatePicker follows a composition-first API. Compose DateField and Calendar explicitly to control structure and styling.

import {Calendar, DateField, DatePicker, Label} from '@heroui/react';

export default () => (
  <DatePicker>
    <Label />
    <DateField.Group>
      <DateField.Input>
        {(segment) => <DateField.Segment segment={segment} />}
      </DateField.Input>
      <DateField.Suffix>
        <DatePicker.Trigger>
          <DatePicker.TriggerIndicator />
        </DatePicker.Trigger>
      </DateField.Suffix>
    </DateField.Group>
    <DatePicker.Popover>
      <Calendar aria-label="Choose date">
        <Calendar.Header>
          <Calendar.YearPickerTrigger>
            <Calendar.YearPickerTriggerHeading />
            <Calendar.YearPickerTriggerIndicator />
          </Calendar.YearPickerTrigger>
          <Calendar.NavButton slot="previous" />
          <Calendar.NavButton slot="next" />
        </Calendar.Header>
        <Calendar.Grid>
          <Calendar.GridHeader>
            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
          </Calendar.GridHeader>
          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
        </Calendar.Grid>
      </Calendar>
    </DatePicker.Popover>
  </DatePicker>
)

Controlled

Date

2172026

Current value: 2026-02-17

"use client";

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

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

Validation

Appointment date

mmddyyyy

"use client";

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

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

Format Options

Control how DatePicker values are displayed with props such as granularity, hourCycle, hideTimeZone, and shouldForceLeadingZeros.

Date and time

232025

Granularity

Hour cycle

Hide timezoneForce leading zeros

"use client";

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

import {Calendar, DateField, DatePicker, Label, ListBox, Select, Switch} from "@heroui/react";

Disabled

Date

2172026

This date picker is disabled.

"use client";

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

Custom Indicator

DatePicker.TriggerIndicator renders the default IconCalendar when no children are provided. Pass children to replace it.

Date

mmddyyyy

Replace the default calendar icon by passing custom children.

"use client";

import {Calendar, DateField, DatePicker, Description, Label} from "@heroui/react";
import {Icon} from "@iconify/react";

Form Example

"use client";

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

import {

By default, DatePicker displays dates using the calendar system for the user's locale. You can override this by wrapping your DatePicker with I18nProvider and setting the Unicode calendar locale extension.

The example below shows the Indian calendar system:

Event date

28111947शक

"use client";

import {Calendar, DateField, DatePicker, Label} from "@heroui/react";
import {getLocalTimeZone, today} from "@internationalized/date";
import {I18nProvider} from "react-aria-components";

Note: The onChange event always returns a date in the same calendar system as the value or defaultValue (Gregorian if no value is provided), regardless of the displayed locale. This ensures your application logic works consistently with a single calendar system while still displaying dates in the user's preferred format.

For a complete list of supported calendar systems and their identifiers, see:

Custom Render Function

Date

mmddyyyy

"use client";

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

export function CustomRenderFunction() {

Related Components

Calendar

DateField

TimeField

Styling

Passing Tailwind CSS classes

You can style each composition part independently:

import {Calendar, DateField, DatePicker, Label} from '@heroui/react';

function CustomDatePicker() {
  return (
    <DatePicker className="w-[320px] gap-2">
      <Label className="text-sm font-semibold">Date</Label>
      <DateField.Group className="rounded-xl border border-border/60 bg-surface" fullWidth variant="secondary">
        <DateField.Input>
          {(segment) => <DateField.Segment segment={segment} />}
        </DateField.Input>
        <DateField.Suffix>
          <DatePicker.Trigger className="w-full">
            <DatePicker.TriggerIndicator className="text-default-600" />
          </DatePicker.Trigger>
        </DateField.Suffix>
      </DateField.Group>
      <DatePicker.Popover className="rounded-xl p-2">
        <Calendar aria-label="Custom date picker calendar">
          {/* Calendar parts */}
        </Calendar>
      </DatePicker.Popover>
    </DatePicker>
  );
}

Customizing the component classes

To customize DatePicker base classes, use @layer components.

@layer components {
  .date-picker {
    @apply inline-flex flex-col gap-1;
  }

  .date-picker__trigger {
    @apply inline-flex items-center justify-between;
  }

  .date-picker__trigger-indicator {
    @apply text-muted;
  }

  .date-picker__popover {
    @apply min-w-[var(--trigger-width)] p-0;
  }
}

HeroUI follows BEM naming for reusable customization.

CSS Classes

DatePicker uses these classes in packages/styles/components/date-picker.css:

.date-picker - Root wrapper.
.date-picker__trigger - Trigger part that opens the popover.
.date-picker__trigger-indicator - Default/custom indicator slot.
.date-picker__popover - Popover content wrapper.

Interactive States

DatePicker supports React Aria data attributes and pseudo states:

Open: [data-open="true"] on trigger.
Disabled: [data-disabled="true"] or [aria-disabled="true"] on trigger.
Focus visible: :focus-visible or [data-focus-visible="true"] on trigger.
Hover: :hover or [data-hovered="true"] on trigger.

API Reference

DatePicker Props

DatePicker inherits all props from React Aria DatePicker.

Prop	Type	Default	Description
`value`	`DateValue \| null`	-	Controlled selected date value.
`defaultValue`	`DateValue \| null`	-	Default selected value in uncontrolled mode.
`onChange`	`(value: DateValue \| null) => void`	-	Called when selected date changes.
`isOpen`	`boolean`	-	Controlled popover open state.
`defaultOpen`	`boolean`	`false`	Initial popover open state.
`onOpenChange`	`(isOpen: boolean) => void`	-	Called when popover open state changes.
`isDisabled`	`boolean`	`false`	Disables date selection and trigger interactions.
`isInvalid`	`boolean`	-	Marks the field as invalid for validation state.
`minValue`	`DateValue`	-	Minimum selectable date.
`maxValue`	`DateValue`	-	Maximum selectable date.
`name`	`string`	-	Name used for HTML form submission.
`children`	`ReactNode \| (values: DatePickerRenderProps) => ReactNode`	-	Composed content or render function.

Composition Parts

Component	Description
`DatePicker.Root`	Root date picker container and state owner.
`DatePicker.Trigger`	Trigger button, usually rendered inside `DateField.Suffix`.
`DatePicker.TriggerIndicator`	Indicator slot with default calendar icon.
`DatePicker.Popover`	Popover wrapper for `Calendar` content.

DatePickerUpdated

Import

Usage

Anatomy

Controlled

Validation

Format Options

Disabled

Custom Indicator

Form Example

International Calendar

Custom Render Function

Related Components

Styling

Passing Tailwind CSS classes

Customizing the component classes

CSS Classes

Interactive States

API Reference

DatePicker Props

Composition Parts

On this page

Related Components