引入

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

用法

日期

mmddyyyy

"use client";

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

export function Basic() {

组件结构

DatePicker 采用组合优先的 API。请显式组合 DateField 与 Calendar，以便完全控制结构与样式。

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

受控

日期

5292026

当前值：2026-05-29

"use client";

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

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

校验

预约日期

mmddyyyy

"use client";

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

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

格式选项

使用 granularity、hourCycle、hideTimeZone、shouldForceLeadingZeros 等 props 控制 DatePicker 值的展示方式。

"use client";

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

禁用

日期

5292026

该日期选择器已禁用。

"use client";

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

自定义指示器

未提供子节点时，DatePicker.TriggerIndicator 会渲染默认的 IconCalendar。传入子节点即可替换。

日期

mmddyyyy

通过传入自定义子元素替换默认日历图标。

"use client";

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

表单示例

"use client";

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

import {

国际化历法

默认情况下，DatePicker 会使用用户语言环境对应的历法显示日期。你可以使用 I18nProvider 包裹 DatePicker，并通过 Unicode 历法语言扩展覆盖。

下方示例展示印度历法系统：

活动日期

831948शक

"use client";

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

说明： onChange 事件返回的日期始终与 value 或 defaultValue 使用同一历法系统（未提供值时为公历），与界面展示的本地化格式无关。这能确保应用逻辑在单一历法系统下保持一致，同时仍可按用户偏好展示日期。

支持的历法系统及其标识符完整列表见：

自定义渲染函数

日期

mmddyyyy

"use client";

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

export function CustomRenderFunction() {

Related Components

Calendar

RangeCalendar

DateField

样式

传入 Tailwind CSS 类

你可以分别为各个组合部分添加样式：

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

自定义组件类

要自定义 DatePicker 的基础类，请使用 @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 遵循 BEM 命名，便于复写与定制。

CSS 类

DatePicker 在 packages/styles/components/date-picker.css 中使用以下类：

.date-picker - 根包裹层。
.date-picker__trigger - 打开弹出层的触发区域。
.date-picker__trigger-indicator - 默认或自定义指示器插槽。
.date-picker__popover - 弹出层内容包裹。

交互状态

DatePicker 支持 React Aria 的 data 属性与伪类状态：

展开：触发器上的 [data-open="true"]。
禁用：触发器上的 [data-disabled="true"] 或 [aria-disabled="true"]。
焦点可见：触发器上的 :focus-visible 或 [data-focus-visible="true"]。
悬停：触发器上的 :hover 或 [data-hovered="true"]。

API 参考

DatePicker Props

DatePicker 继承 React Aria DatePicker 的全部 props。

Prop	类型	默认值	描述
`value`	`DateValue \| null`	-	受控的选中日期值。
`defaultValue`	`DateValue \| null`	-	非受控模式下的默认选中值。
`onChange`	`(value: DateValue \| null) => void`	-	选中日期变化时调用。
`isOpen`	`boolean`	-	受控的弹出层打开状态。
`defaultOpen`	`boolean`	`false`	弹出层初始打开状态。
`onOpenChange`	`(isOpen: boolean) => void`	-	弹出层打开状态变化时调用。
`isDisabled`	`boolean`	`false`	禁用日期选择与触发器交互。
`isInvalid`	`boolean`	-	将字段标记为无效以呈现校验状态。
`minValue`	`DateValue`	-	可选择的最小日期。
`maxValue`	`DateValue`	-	可选择的最大日期。
`name`	`string`	-	HTML 表单提交使用的 name。
`children`	`ReactNode \| (values: DatePickerRenderProps) => ReactNode`	-	组合内容或渲染函数。
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, DatePickerRenderProps>`	-	使用自定义渲染函数覆盖默认 DOM 元素。

组合部件

组件	描述
`DatePicker.Root`	根日期选择器容器与状态持有者。
`DatePicker.Trigger`	触发按钮，通常渲染在 `DateField.Suffix` 内。
`DatePicker.TriggerIndicator`	带默认日历图标的指示器插槽。
`DatePicker.Popover`	包裹 `Calendar` 内容的弹出层。

DatePicker 日期选择器

引入

用法

组件结构

受控

校验

格式选项

禁用

自定义指示器

表单示例

国际化历法

自定义渲染函数

Related Components

样式

传入 Tailwind CSS 类

自定义组件类

CSS 类

交互状态

API 参考

DatePicker Props

组合部件

相关包

本页目录

Related Components