DatePicker

DatePicker is a component used for users to select a date.

<DatePicker />

Usage

import { DatePicker } from "@yamada-ui/react"

import { DatePicker } from "@/components/ui"

import { DatePicker } from "@workspaces/ui"

<DatePicker />

Change Variant

<VStack>
  <For each={["outline", "filled", "flushed", "plain"]}>
    {(variant, index) => (
      <DatePicker
        key={index}
        variant={variant}
        placeholder={toTitleCase(variant)}
      />
    )}
  </For>
</VStack>

Change Size

<VStack>
  <For each={["xs", "sm", "md", "lg", "xl"]}>
    {(size, index) => (
      <DatePicker key={index} size={size} placeholder={`Size (${size})`} />
    )}
  </For>
</VStack>

Change Color Scheme

<VStack>
  <For each={["success", "warning"]}>
    {(colorScheme, index) => (
      <DatePicker
        key={index}
        colorScheme={colorScheme}
        today
        defaultValue={new Date(new Date().setDate(1))}
      />
    )}
  </For>
</VStack>

Change Format

To change the format, set the format object.

const format = useMemo<DatePickerFormat>(
  () => ({
    input: null,
    month: "long",
    weekday: "narrow",
    year: "2-digit",
  }),
  [],
)

return <DatePicker format={format} />

Set Default Date

To set a default date, set defaultValue to a Date.

<DatePicker defaultValue={new Date(1993, 7, 18)} />

Set Default Input Value

To set a default input value, specify a string for defaultInputValue.

<DatePicker defaultInputValue="1993/08/18" />

Set Default Month

To set a default month, set defaultMonth to a Date.

<DatePicker defaultMonth={new Date("2025-10-01")} />

Set Minimum Date

To set the minimum selectable date, set minDate to a Date.

<DatePicker minDate={new Date(new Date().setDate(1))} />

Set Maximum Date

To set the maximum selectable date, set maxDate to a Date.

<DatePicker maxDate={new Date(new Date().setDate(18))} />

Allow Values Outside Minimum and Maximum Range

By default, if a date outside the minimum and maximum range is entered, it is automatically replaced with the minimum or maximum date. To disable this control and allow values outside the range, set allowInputBeyond to true.

<DatePicker
  minDate={new Date(new Date().setDate(1))}
  maxDate={new Date(new Date().setDate(18))}
  allowInputBeyond
/>

Disable Today Highlighting

To disable highlighting of today's date, set today to false.

<DatePicker today={false} />

Disable Specific Days of the Week

To disable specific days of the week, set excludeDate to a condition function.

<DatePicker excludeDate={(date) => [0, 1, 6].includes(date.getDay())} />

If you use this code, you need to add "use client" to the top of the file.

Enable Multiple Selection

To enable multiple date selection, set multiple to true.

<DatePicker multiple />

Set Maximum for Multiple Selection

To set the maximum number of selectable dates in multiple selection, set max to a number.

<DatePicker max={3} multiple />

Change Separator

To change the separator, specify a string for separator. By default, , is set.

<DatePicker multiple separator=";" />

Enable Range Selection

To enable range selection, set range to true.

<DatePicker range />

Change Start Day of Week

To change the start day of the week, set startDayOfWeek to "sunday" or "monday".

<VStack>
  <DatePicker placeholder="sunday" startDayOfWeek="sunday" />
  <DatePicker placeholder="monday" startDayOfWeek="monday" />
</VStack>

Change Weekend Days

To change which days are treated as weekends, set weekendDays to an array of days(numbers).

<DatePicker weekendDays={[0, 1]} />

Set Pattern

To set a pattern, set a regular expression to pattern.

<DatePicker pattern={/[^\w, ]/g} defaultValue={new Date()} />

Handle Parsing of Entered Values

To handle the parsing of entered values, use parseDate.

<DatePicker parseDate={(value) => new Date(value)} />

If you use this code, you need to add "use client" to the top of the file.

Set Holidays

To set holidays, set holidays to an array of Dates.

const holidays = useMemo(
  () => [
    new Date("2025-01-01"),
    new Date("2025-01-13"),
    new Date("2025-02-11"),
    new Date("2025-02-23"),
    new Date("2025-02-24"),
    new Date("2025-03-20"),
    new Date("2025-04-29"),
    new Date("2025-05-03"),
    new Date("2025-05-04"),
    new Date("2025-05-05"),
    new Date("2025-05-06"),
    new Date("2025-07-21"),
    new Date("2025-08-11"),
    new Date("2025-09-15"),
    new Date("2025-09-23"),
    new Date("2025-10-13"),
    new Date("2025-11-03"),
    new Date("2025-11-23"),
    new Date("2025-11-24"),
    new Date("2026-01-01"),
    new Date("2026-01-12"),
    new Date("2026-02-11"),
    new Date("2026-02-23"),
    new Date("2026-03-20"),
    new Date("2026-04-29"),
    new Date("2026-05-03"),
    new Date("2026-05-04"),
    new Date("2026-05-05"),
    new Date("2026-05-06"),
    new Date("2026-07-20"),
    new Date("2026-08-11"),
    new Date("2026-09-21"),
    new Date("2026-09-22"),
    new Date("2026-10-12"),
    new Date("2026-11-03"),
    new Date("2026-11-23"),
  ],
  [],
)

return <DatePicker holidays={holidays} />

Hide Outside the Current Month

To hide dates outside the current month, set styles using dayProps.

<DatePicker
  calendarProps={{
    dayProps: {
      css: { "&[data-outside]": { opacity: 0, pointerEvents: "none" } },
    },
  }}
/>

Change Offset

To change the offset, specify a value for gutter or offset.

<DatePicker gutter={16} />

Change Animation

To change the animation, specify "block-start" or "inline-end" for animationScheme. By default, "scale" is set.

<DatePicker animationScheme="inline-start" />

Change Placement

To change the placement, specify "end" or "start-center" for placement. By default, "end-start" is set.

<DatePicker
  animationScheme="inline-start"
  placement="center-end"
  rootProps={{ w: "xs" }}
/>

Blocking Scroll

To block scrolling, set blockScrollOnMount to true.

<DatePicker blockScrollOnMount />

To close the dropdown on scroll, set closeOnScroll to true.

<DatePicker closeOnScroll />

To handle the event of opening the dropdown on change, set a function to openOnChange.

<DatePicker
  openOnFocus={false}
  openOnChange={(ev) => ev.target.value.length > 1}
/>

If you use this code, you need to add "use client" to the top of the file.

To handle the event of closing the dropdown on change, set a function to closeOnChange.

<DatePicker
  openOnFocus={false}
  closeOnChange={(ev) => !ev.target.value.length}
/>

If you use this code, you need to add "use client" to the top of the file.

To disable opening the dropdown on focus, set openOnFocus to false.

<DatePicker openOnFocus={false} />

To disable opening the dropdown on click, set openOnClick to false.

<DatePicker openOnClick={false} />

Disable Focus After Clear

To disable focus after clear, set focusOnClear to false.

<DatePicker focusOnClear={false} />

Disable Close On Select

To disable closing the dropdown on select, set closeOnSelect to false.

<DatePicker closeOnSelect={false} />

Disable Close On Outside Click

To disable closing dropdown when clicking outside, set closeOnBlur to false.

<DatePicker closeOnBlur={false} />

Disable Close On Esc

To disable closing the dropdown with the Esc key, set closeOnEsc to false.

<DatePicker closeOnEsc={false} />

Disable Clear Button

To disable the clear button, set clearable to false.

<DatePicker clearable={false} />

Disallow Input

To disallow input, set allowInput to false.

<DatePicker allowInput={false} />

Change Shape

<VStack>
  <For each={["rounded", "circle", "square"]}>
    {(shape, index) => (
      <DatePicker
        key={index}
        defaultValue={{
          end: new Date(new Date().setDate(new Date().getDate() + 4)),
          start: new Date(),
        }}
        range
        calendarProps={{ shape }}
      />
    )}
  </For>
</VStack>

Disable

To disable, set disabled to true.

<VStack>
  <For each={["outline", "filled", "flushed"]}>
    {(variant, index) => (
      <DatePicker
        key={index}
        variant={variant}
        disabled
        placeholder={toTitleCase(variant)}
      />
    )}
  </For>
</VStack>

Read-Only

To make read-only, set readOnly to true.

<VStack>
  <For each={["outline", "filled", "flushed"]}>
    {(variant, index) => (
      <DatePicker
        key={index}
        variant={variant}
        readOnly
        placeholder={toTitleCase(variant)}
      />
    )}
  </For>
</VStack>

Invalid

To make invalid, set invalid to true.

<VStack>
  <For each={["outline", "filled", "flushed"]}>
    {(variant, index) => (
      <DatePicker
        key={index}
        variant={variant}
        invalid
        placeholder={toTitleCase(variant)}
      />
    )}
  </For>
</VStack>

Change Border Color

To customize focus and error border colors, set colors for focusBorderColor or errorBorderColor.

<VStack>
  <DatePicker focusBorderColor="green.500" placeholder="custom border color" />
  <DatePicker
    invalid
    errorBorderColor="orange.500"
    placeholder="custom border color"
  />
</VStack>

Customize Icon

<VStack>
  <DatePicker iconProps={{ color: "orange" }} />
  <DatePicker icon={<CalendarDaysIcon />} />
</VStack>

Customize Multiple Selection Display

<DatePicker
  multiple
  render={({ value, onClear }) => (
    <Tag size="sm" me="{gap}" onClose={onClear}>
      {value}
    </Tag>
  )}
/>

If you use this code, you need to add "use client" to the top of the file.

Customize Calendar

You can customize Calendar to change the display.

<VStack>
  <DatePicker>
    <Calendar.Navigation>
      <Calendar.Control justifyContent="flex-start" px="3">
        {({ month }) =>
          `${month.getFullYear()}/${(month.getMonth() + 1).toString().padStart(2, "0")}`
        }
      </Calendar.Control>
      <Calendar.PrevButton gridColumn="6 / 7" />
      <Calendar.NextButton gridColumn="7 / 8" />
    </Calendar.Navigation>

    <Calendar.Month />
  </DatePicker>

  <DatePicker
    calendarProps={{
      day: ({ value }) => (
        <Indicator
          colorScheme="blue"
          size="sm"
          disabled={value.getDate() % 4 !== 0}
          offset="-3px"
          labelProps={{ minBoxSize: "2" }}
        >
          <Text as="span">{value.getDate()}</Text>
        </Indicator>
      ),
    }}
  />
</VStack>

If you use this code, you need to add "use client" to the top of the file.

Control

const [value, onChange] = useState<Date | null>(new Date())

return <DatePicker value={value} onChange={onChange} />

Props

Prop	Default	Type / Description
`as`	-	`As` The HTML element to render.
`asChild`	-	`boolean` Merges its props onto its immediate child.
`css`	-	`CSSObject \| CSSObject[]` The CSS object.
`colorScheme`	-	`"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` Set color scheme variables.
`size`	`"md"`	`"lg" \| "md" \| "sm" \| "xl" \| "xs"` The size of the component.
`variant`	`"outline"`	`"filled" \| "flushed" \| "outline" \| "plain"` The variant of the component.
`allowInput`	`true`	`boolean` If `true`, allows input.
`allowInputBeyond`	`true`	`boolean` If `true`, allows input of dates beyond the `minDate` and `maxDate` restrictions.
`animationScheme`	`"scale"`	`"none" \| "scale" \| SimplePlacement` The animation of the element.
`autoUpdate`	`true`	`boolean` If `true`, automatically updates the position of the floating element when necessary.
`blockScrollOnMount`	`false`	`boolean` If `true`, scrolling will be disabled on the `body` when the modal opens.
`calendarProps`	-	`Calendar.RootProps<Multiple, Range>` The size of the calendar component.
`clearable`	`true`	`boolean` If `true`, display the clear icon.
`clearIcon`	-	`ReactNode` The icon to be used in the clear button.
`closeOnBlur`	`true`	`boolean` If `true`, the popover will close when you blur out it by clicking outside or tabbing out.
`closeOnChange`	`false`	`((ev: ChangeEvent<HTMLInputElement>) => boolean) \| boolean` If `true`, the date picker will be closed when the input value changes.
`closeOnEsc`	`true`	`boolean` If `true`, the popover will hide on pressing Esc key.
`closeOnScroll`	`false`	`boolean` If `true`, the popover will hide on scroll.
`closeOnSelect`	`true`	`boolean` If `true`, the list element will be closed when value is selected.
`contentProps`	-	`DatePickerContentProps` Props for content element.
`defaultInputValue`	-	`MaybeInputValue<Range>` The initial value of the input.
`defaultMonth`	`new Date()`	`Date` The initial month of the calendar.
`defaultOpen`	-	`boolean` If `true`, the element will be initially opened.
`defaultValue`	-	`NonNullable<MaybeDateValue<Multiple, Range>>` The initial value of the calendar.
`disabled`	`false`	`boolean` If `true`, disables the calendar.
`duration`	`0.2`	`MotionTransitionProps["duration"]` The animation duration.
`elementProps`	-	`InputGroup.ElementProps` The props for the end element.
`elements`	-	`{ floating?: HTMLElement \| null \| undefined; reference?: HTMLButtonElement \| null \| undefined }` Object containing the reference and floating elements.
`errorBorderColor`	-	`"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` The border color when the input is invalid.
`excludeDate`	-	`(date: Date) => boolean` Callback function to determine whether the day should be disabled.
`flip`	`true`	`boolean` If `true`, the popper will change its placement and flip when it's about to overflow its boundary area.
`focusBorderColor`	-	`"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` The border color when the input is focused.
`focusOnClear`	`true`	`boolean` If `true`, the input will be focused when the clear icon is clicked.
`format`	-	`DatePickerFormat` The format used for conversion. Check the docs to see the format of possible modifiers you can pass. https://day.js.org/docs/en/display/format#list-of-localized-formats
`gutter`	`8`	`number` The distance or margin between the reference and popper. It is used internally to create an `offset` modifier.
`holidays`	-	`Date[]` Define holidays.
`icon`	-	`ReactNode` The icon to be used in the date picker.
`iconProps`	-	`DatePickerIconProps` Props for icon element.
`inputProps`	-	`HTMLStyledProps<"input">` The props for the input element.
`inputValue`	-	`MaybeInputValue<Range>` The value of the input.
`invalid`	`false`	`boolean` If `true`, the field will be invalid.
`locale`	`"en-US"`	`AnyString \| "ar-AE" \| "bg-BG" \| "cs-CZ" \| "da-DK" \| "de-DE" \| "el-GR" \| "en-GB" \| "en-US" \| "es-ES" \| "et-EE" \| "fi-FI" \| "fr-CA" \| "fr-FR" \| "he-IL" \| "hr-HR" \| "hu-HU" \| ... 18 more ... \| "zh-TW"` The locale of the calendar.
`matchWidth`	`false`	`boolean` If `true`, the popper will match the width of the reference at all times. It's useful for `autocomplete`, `date-picker` and `select` patterns.
`max`	-	`number` The maximum selectable value.
`maxDate`	`new Date(2099, 11, 31)`	`Date` The maximum possible date.
`middleware`	-	`(false \| { name: string; options?: any; fn: (state: { x: number; y: number; placement: Placement; platform: { detectOverflow: (state: MiddlewareState, options?: DetectOverflowOptions \| Derivable<...> \| undefined) => Promise<...>; } & Platform; ... 4 more ...; elements: Elements; }) => Promisable<...>; } \| null \| und...` Array of middleware objects to modify the positioning or provide data for rendering.
`minDate`	`new Date(1900, 0, 1)`	`Date` The minimum possible date.
`month`	-	`Date` The month of the calendar.
`multiple`	`false`	`Multiple` If `true`, the calendar will be multiple.
`name`	-	`string` The `name` attribute of the input element.
`offset`	-	`[number, number]` The main and cross-axis offset to displace popper element from its reference element.
`onChange`	-	`(value: MaybeDateValue<Multiple, Range>) => void` The callback invoked when value state changes.
`onChangeMonth`	-	`(value: Date) => void` The callback invoked when month state changes.
`onClose`	-	`() => void \| Promise<void>` Callback invoked to close the element.
`onInputChange`	-	`(value: MaybeInputValue<Range>) => void` The callback invoked when input value state changes.
`onOpen`	-	`() => void \| Promise<void>` Callback invoked to open the element.
`open`	-	`boolean` If `true`, the element will be opened.
`openOnChange`	`true`	`((ev: ChangeEvent<HTMLInputElement>) => boolean) \| boolean` If `true`, the date picker will be opened when the input value changes.
`openOnClick`	`true`	`boolean` If `true`, the combobox will be opened when click on the field.
`openOnEnter`	`true`	`boolean` If `true`, the combobox will be opened when enter is pressed.
`openOnFocus`	`true`	`boolean` If `true`, the date picker will be opened when the input is focused.
`openOnSpace`	`true`	`boolean` If `true`, the combobox will be opened when space is pressed.
`parseDate`	-	`(value: string) => Date \| undefined` Function that converts the input value to Date type.
`pattern`	-	`RegExp` The pattern used to check the input element.
`placeholder`	-	`string` The placeholder for date picker.
`placement`	`"end-start"`	`Direction` The placement of the popper relative to its reference.
`platform`	-	`Platform` Custom or extended platform object.
`preventOverflow`	`true`	`boolean` If `true`, will prevent the popper from being cut off and ensure it's visible within the boundary area.
`range`	`false`	`Range` If `true`, enables date range selection.
`readOnly`	`false`	`boolean` If `true`, the combobox will be readonly.
`render`	-	`(props: DatePickerRenderProps) => ReactNode` The function to render the selected date.
`required`	`false`	`boolean` If `true`, the field will be required.
`rootProps`	-	`InputGroup.RootProps` Props for root element.
`selectFocusRef`	-	`RefObject<HTMLElement \| null>` The `ref` of the element that should receive focus when selected.
`selectOnSpace`	`true`	`boolean` If `true`, the item will be selected when space is pressed.
`separator`	`","`	`string` The visual separator between each value.
`startDayOfWeek`	`"monday"`	`StartDayOfWeek` Define the start day of the week.
`strategy`	`"absolute"`	`Strategy` The CSS positioning strategy to use.
`today`	`true`	`boolean` If `true`, highlight today.
`transferFocus`	`true`	`boolean` If `true`, the focus will be transferred to the popover content when the tab key is pressed.
`value`	-	`NonNullable<MaybeDateValue<Multiple, Range>>` The value of the calendar.
`weekendDays`	`[0, 6]`	`number[]` Define weekend days.
`whileElementsMounted`	-	`(reference: HTMLButtonElement, floating: HTMLElement, update: () => void) => () => void` A callback invoked when both the reference and floating elements are mounted, and cleaned up when either is unmounted. This is useful for setting up event listeners (e.g. pass `autoUpdate`).

Accessibility

The DatePicker follows the WAI-ARIA - Combobox Pattern for accessibility.

If you are not using Field.Root, set aria-label or aria-labelledby to DatePicker.

<DatePicker placeholder="YYYY/MM/DD" aria-label="Birthday" />

<VStack gap="sm">
  <Text as="h3" id="label">
    Birthday
  </Text>

  <DatePicker placeholder="YYYY/MM/DD" aria-labelledby="label" />
</VStack>

Key	Description	State
`Enter`	When the input value is valid, applies it to the selection. Toggles the focused date if focus is in the calendar.	-
`Backspace`	Clears the last selection.	-
`Escape`	Closes the calendar.	`closeOnEsc={true}`
`ArrowUp`	Moves focus to the date above if focus is in the calendar.	-
`ArrowDown`	Moves focus to the date below if focus is in the calendar.	-
`ArrowLeft`	Moves focus to the date to the left if focus is in the calendar. If it's the first date, moves to the last date of the previous month.	-
`ArrowRight`	Moves focus to the date to the right if focus is in the calendar. If it's the last date, moves to the first date of the next month.	-
`Home`	Moves focus to the first date in the same week if focus is in the calendar.	-
`End`	Moves focus to the last date in the same week if focus is in the calendar.	-
`PageUp`	Moves focus to the same date in the previous month if focus is in the calendar. If that date doesn't exist, moves to an enabled date in that month.	-
`Shift` + `PageUp`	Moves focus to the same date in the previous year if focus is in the calendar. If that date doesn't exist, moves to an enabled date in that month.	-
`PageDown`	Moves focus to the same date in the next month if focus is in the calendar. If that date doesn't exist, moves to an enabled date in that month.	-
`Shift` + `PageDown`	Moves focus to the same date in the next year if focus is in the calendar. If that date doesn't exist, moves to an enabled date in that month.	-
`Space`	Toggles the selection state of the focused date if focus is in the calendar.	-

ARIA Roles and Attributes

Component	Roles and Attributes	Usage
`DatePickerField`	`role="combobox"`	Indicates that it is a combobox.
	`aria-controls`	When the calendar is open, sets the `id` of the associated `DatePickerContent`. When closed, sets `undefined`.
	`aria-disabled`	Sets to `"true"` if `disabled` or `readOnly` is set.
	`aria-describedby`	When `DatePicker` is within `Field.Root` and `Field.Root` has `errorMessage` or `helperMessage`, or `Field.ErrorMessage` or `Field.HelperMessage` is set, sets their `id`.
	`aria-expanded`	Sets to `"true"` when the calendar is open, and `"false"` when it is closed.
	`aria-haspopup="dialog"`	Indicates that a dialog exists.
	`aria-invalid`	Sets to `"true"` if `invalid` is set.
	`aria-readonly`	Sets to `"true"` if `readOnly` is set.
	`aria-required`	Sets to `"true"` if `required` is set.
`DatePickerContent`	`role="dialog"`	Indicates that it is a dialog.
	`aria-hidden`	When the calendar is open, sets to `"false"`. When closed, sets to `"true"`.
`DatePickerIcon`	`role="button"`	Indicates that it is a button when `clearable` and there is a value.
	`aria-disabled`	When `clearable` and there is a value, and `disabled` or `readOnly` is set, sets to `"true"`.
	`aria-label`	When `clearable` and there is a value, sets `"Clear value"`.
`Calendar.YearSelect`	`aria-label`	Sets `"Choose the year"`.
`Calendar.MonthSelect`	`aria-label`	Sets `"Choose the month"`.
`Calendar.Control`	`role="status"`	Indicates that it is a status.
	`aria-live="polite"`	Indicates that it may be updated outside of focus.
`Calendar.Month`	`role="grid"`	Indicates that it is a grid.
	`aria-label`	Sets the displayed month and year, like `"February 2026"`.
	`aria-multiselectable`	Sets `"true"` if multiple selection or range selection is enabled.
`Calendar.PrevButton`	`aria-label`	Sets `"Go to the previous month"`.
`Calendar.NextButton`	`aria-label`	Sets `"Go to the next month"`.
`CalendarDay`	`aria-label`	Sets the date, like `"Thursday, February 5, 2026"`. If today, sets `"Today, Thursday, February 5, 2026"`.
	`aria-disabled`	Sets `"true"` if the date is disabled.
	`aria-selected`	Sets `"true"` if the date is selected.