DatePicker

Composable date picker built on React Aria DatePicker with DateField and Calendar composition

Usage

1import { DatePicker, DateField, Calendar, Label } from '@lenso/ui';

1"use client";2
3/** Adapted from the pinned HeroUI v3.2.6 basic.json. Copyright NextUI Inc. Apache-2.0. Local RAC label and StyleX replace source Label and utility classes. */4import { Calendar, DateField, DatePicker } from "@lenso/ui";5import * as stylex from "@stylexjs/stylex";6
7const styles = stylex.create({ field: { width: 288 } });8export function Basic() {9  return (10    <DatePicker xstyle={styles.field} name="date">11      <DatePicker.Label>Date</DatePicker.Label>12      <DateField.Group fullWidth>13        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>14        <DateField.Suffix>15          <DatePicker.Trigger>16            <DatePicker.TriggerIndicator />17          </DatePicker.Trigger>18        </DateField.Suffix>19      </DateField.Group>20      <DatePicker.Popover>21        <Calendar aria-label="Event date">22          <Calendar.Header>23            <Calendar.YearPickerTrigger>24              <Calendar.YearPickerTriggerHeading />25              <Calendar.YearPickerTriggerIndicator />26            </Calendar.YearPickerTrigger>27            <Calendar.NavButton slot="previous" />28            <Calendar.NavButton slot="next" />29          </Calendar.Header>30          <Calendar.Grid>31            <Calendar.GridHeader>32              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}33            </Calendar.GridHeader>34            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>35          </Calendar.Grid>36          <Calendar.YearPickerGrid>37            <Calendar.YearPickerGridBody>38              {({ year }) => <Calendar.YearPickerCell year={year} />}39            </Calendar.YearPickerGridBody>40          </Calendar.YearPickerGrid>41        </Calendar>42      </DatePicker.Popover>43    </DatePicker>44  );45}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Anatomy

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

1import {Calendar, DateField, DatePicker, Label} from '@lenso/ui';2
3export default () => (4  <DatePicker>5    <Label />6    <DateField.Group>7      <DateField.Input>8        {(segment) => <DateField.Segment segment={segment} />}9      </DateField.Input>10      <DateField.Suffix>11        <DatePicker.Trigger>12          <DatePicker.TriggerIndicator />13        </DatePicker.Trigger>14      </DateField.Suffix>15    </DateField.Group>16    <DatePicker.Popover>17      <Calendar aria-label="Choose date">18        <Calendar.Header>19          <Calendar.YearPickerTrigger>20            <Calendar.YearPickerTriggerHeading />21            <Calendar.YearPickerTriggerIndicator />22          </Calendar.YearPickerTrigger>23          <Calendar.NavButton slot="previous" />24          <Calendar.NavButton slot="next" />25        </Calendar.Header>26        <Calendar.Grid>27          <Calendar.GridHeader>28            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}29          </Calendar.GridHeader>30          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>31        </Calendar.Grid>32      </Calendar>33    </DatePicker.Popover>34  </DatePicker>35)

Examples

Disabled

1"use client";2/** HeroUI v3.2.6 adapted example. Copyright NextUI Inc. Apache-2.0. */3export { Disabled } from "./scenarios";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Controlled

1"use client";2/** HeroUI v3.2.6 adapted example. Copyright NextUI Inc. Apache-2.0. */3export { Controlled } from "./scenarios";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Validation

1"use client";2/** HeroUI v3.2.6 adapted example. Copyright NextUI Inc. Apache-2.0. */3export { WithValidation } from "./scenarios";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Format Options

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

1"use client";2/** Adapted from HeroUI v3.2.6 format-options.json. Copyright NextUI Inc. Apache-2.0. */3import { DatePicker, TimeField } from "@lenso/ui";4import {5  getLocalTimeZone,6  parseDate,7  parseZonedDateTime,8  type DateValue,9} from "@internationalized/date";10import { useMemo, useState } from "react";11import * as stylex from "@stylexjs/stylex";12import { PickerCalendar, PickerInput } from "./parts";13import { FormatControls, formatStyles, type Granularity, type HourCycle } from "./format-controls";14
15export function FormatOptions() {16  const [granularity, setGranularity] = useState<Granularity>("minute");17  const [hourCycle, setHourCycle] = useState<HourCycle>(12);18  const [hideTimeZone, setHideTimeZone] = useState(false);19  const [shouldForceLeadingZeros, setShouldForceLeadingZeros] = useState(false);20  const timeGranularity = granularity !== "day" ? granularity : undefined;21  const defaultValue = useMemo<DateValue>(22    () =>23      granularity === "day"24        ? parseDate("2026-02-03")25        : parseZonedDateTime(`2026-02-03T08:45:00[${getLocalTimeZone()}]`),26    [granularity],27  );28  return (29    <div {...stylex.props(formatStyles.stack)}>30      <DatePicker31        key={granularity}32        xstyle={formatStyles.field}33        defaultValue={defaultValue}34        granularity={granularity}35        hourCycle={hourCycle}36        hideTimeZone={hideTimeZone}37        shouldForceLeadingZeros={shouldForceLeadingZeros}38        name="date"39      >40        {({ state }) => (41          <>42            <DatePicker.Label>Date and time</DatePicker.Label>43            <PickerInput />44            <DatePicker.Popover xstyle={formatStyles.popover}>45              <PickerCalendar />46              {timeGranularity && (47                <div {...stylex.props(formatStyles.timeRow)}>48                  <span {...stylex.props(formatStyles.label)}>Time</span>49                  <TimeField50                    aria-label="Time"51                    granularity={timeGranularity}52                    hourCycle={hourCycle}53                    hideTimeZone={hideTimeZone}54                    name="time"55                    shouldForceLeadingZeros={shouldForceLeadingZeros}56                    value={state.timeValue}57                    onChange={(value) => {58                      if (value) state.setTimeValue(value);59                    }}60                  >61                    <TimeField.Group variant="secondary">62                      <TimeField.Input>63                        {(segment) => <TimeField.Segment segment={segment} />}64                      </TimeField.Input>65                    </TimeField.Group>66                  </TimeField>67                </div>68              )}69            </DatePicker.Popover>70          </>71        )}72      </DatePicker>73      <FormatControls74        {...{75          granularity,76          setGranularity,77          hourCycle,78          setHourCycle,79          hideTimeZone,80          setHideTimeZone,81          shouldForceLeadingZeros,82          setShouldForceLeadingZeros,83        }}84      />85    </div>86  );87}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Form Example

1"use client";2/** HeroUI v3.2.6 adapted example. Copyright NextUI Inc. Apache-2.0. */3export { FormExample } from "./scenarios";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Custom Indicator

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

1"use client";2/** HeroUI v3.2.6 adapted example. Copyright NextUI Inc. Apache-2.0. */3export { WithCustomIndicator } from "./scenarios";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Render Function

1"use client";2/** Adapted from HeroUI v3.2.6 render-function.json. Copyright NextUI Inc. Apache-2.0. RAC 1.21 native DOM render functions preserve props, refs and input semantics. */3import { DateField, DatePicker } from "@lenso/ui";4import { PickerCalendar, styles } from "./parts";5
6export function RenderFunction() {7  return (8    <DatePicker9      xstyle={styles.field}10      name="date"11      render={(props) => <div {...props} data-custom="date-picker" />}12    >13      <DatePicker.Label render={(props) => <span {...props} data-custom="date-picker-label" />}>14        Date15      </DatePicker.Label>16      <DateField.Group17        fullWidth18        render={(props) => <div {...props} data-custom="date-field-group" />}19      >20        <DateField.Input render={(props) => <div {...props} data-custom="date-field-input" />}>21          {(segment) => (22            <DateField.Segment23              render={(props) => <span {...props} data-custom="date-field-segment" />}24              segment={segment}25            />26          )}27        </DateField.Input>28        <DateField.Suffix>29          <DatePicker.Trigger30            render={(props) => <button {...props} data-custom="date-picker-trigger" />}31          >32            <DatePicker.TriggerIndicator />33          </DatePicker.Trigger>34        </DateField.Suffix>35      </DateField.Group>36      <DatePicker.Popover>37        <PickerCalendar />38      </DatePicker.Popover>39    </DatePicker>40  );41}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

International Calendar

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:

1"use client";2/** HeroUI v3.2.6 adapted example. Copyright NextUI Inc. Apache-2.0. */3export { InternationalCalendar } from "./scenarios";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

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:

Customization

Tailwind CSS

1"use client";2/** HeroUI v3.2.6 adapted example. Copyright NextUI Inc. Apache-2.0. */3export { CustomStyles } from "./scenarios";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Global CSS

To customize DatePicker base classes, use @layer components.

1@layer components {2  .date-picker {3    @apply inline-flex flex-col gap-1;4  }5
6  .date-picker__trigger {7    @apply inline-flex items-center justify-between;8  }9
10  .date-picker__trigger-indicator {11    @apply text-muted;12  }13
14  .date-picker__popover {15    @apply min-w-[var(--trigger-width)] p-0;16  }17}

Styling Reference

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

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.
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, DatePickerRenderProps>`	-	Overrides the default DOM element with a custom 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.

@internationalized/date — date types (CalendarDate, CalendarDateTime, ZonedDateTime) and utilities used by all date components
I18nProvider — override locale for a subtree
useLocale — read the current locale and layout direction

Calendar

Composable date picker with month grid, navigation, and year picker support built on React Aria Calendar

RangeCalendar

Composable date range picker with month grid, navigation, and year picker support built on React Aria RangeCalendar

DateField

Date input field with labels, descriptions, and validation built on React Aria DateField

DatePicker

Usage

Anatomy

Examples

Disabled

Controlled

Validation

Format Options

Form Example

Custom Indicator

Render Function

International Calendar

Customization

Tailwind CSS

Global CSS

Styling Reference

CSS Classes

Interactive States

API Reference

DatePicker

Composition Parts

Related packages

Related Components