---
title: Calendar
description: "`Calendar` is a component for displaying or selecting dates in a calendar."
links:
- source: https://github.com/yamada-ui/yamada-ui/tree/main/packages/react/src/components/calendar
- storybook: https://yamada-ui.github.io/yamada-ui?path=/story/components-calendar--basic
---
```tsx
```
## Usage
```tsx
import { Calendar } from "@yamada-ui/react"
```
```tsx
import { Calendar } from "@/components/ui"
```
```tsx
import { Calendar } from "@workspaces/ui"
```
```tsx
```
### Change Size
```tsx
{(size, index) => (
)}
```
### Change Color Scheme
```tsx
{(colorScheme, index) => (
)}
```
### Change Shape
```tsx
{(shape, index) => (
)}
```
### Change Format
To change the format, set the `format` object.
```tsx
const format = useMemo(
() => ({
month: "long",
weekday: "narrow",
year: "2-digit",
}),
[],
)
return
```
### Set Default Date
To set a default date, set `defaultValue` to a `Date`.
```tsx
```
### Set Default Month
To set a default month, set `defaultMonth` to a `Date`.
```tsx
```
### Set Minimum Date
To set the minimum selectable date, set `minDate` to a `Date`.
```tsx
```
### Set Maximum Date
To set the maximum selectable date, set `maxDate` to a `Date`.
```tsx
```
### Disable
To disable the calendar, set `disabled` to `true`.
```tsx
```
### Disable Today Highlighting
To disable highlighting of today's date, set `today` to `false`.
```tsx
```
### Disable Specific Days of the Week
To disable specific days of the week, set `excludeDate` to a condition function.
```tsx
[0, 1, 6].includes(date.getDay())} />
```
### Allow Multiple Selection
To allow multiple date selection, set `multiple` to `true`.
```tsx
```
### Set Maximum for Multiple Selection
To set the maximum number of selectable dates in multiple selection, set `max` to a number.
```tsx
```
### Enable Range Selection
To enable range selection, set `range` to `true`.
```tsx
```
### Change Start Day of Week
To change the start day of the week, set `startDayOfWeek` to `"sunday"` or `"monday"`.
```tsx
```
### Change Weekend Days
To change which days are treated as weekends, set `weekendDays` to an array of days(numbers).
```tsx
```
### Set Holidays
To set holidays, set `holidays` to an array of `Date`s.
```tsx
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"),
],
[],
)
return
```
### Hide Outside the Current Month
To hide dates outside the current month, set styles using `dayProps`.
```tsx
```
### Customize Components
You can customize components to change the display.
```tsx preview
{({ month }) =>
`${month.getFullYear()}/${(month.getMonth() + 1).toString().padStart(2, "0")}`
}
(
{value.getDate()}
)}
/>
```
### Control
```tsx
const [value, setValue] = useState(new Date())
return
```
## Props
### Calendar.Root
| 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"` | `"2xl" \| "lg" \| "md" \| "sm" \| "xl" \| "xs"` | The size of the component. |
| `buttonProps` | - | `HTMLStyledProps<"button">` | Props for the button component. |
| `controlProps` | - | `CalendarControlProps` | Props for the control component. |
| `day` | - | `string \| number \| bigint \| boolean \| ReactElement> \| Iterable \| ReactPortal \| Promise<...> \| ((props: { ...; }) => ReactNode)` | The day component to use. |
| `dayProps` | - | `Omit` | Props for the day component. |
| `defaultMonth` | `new Date()` | `Date` | The initial month of the calendar. |
| `defaultValue` | - | `MaybeDateValue` | The initial value of the calendar. |
| `disabled` | `false` | `boolean` | If `true`, disables the calendar. |
| `excludeDate` | - | `(date: Date) => boolean` | Callback function to determine whether the day should be disabled. |
| `fixed` | `true` | `boolean` | If `true`, the calendar will be fixed rows. |
| `format` | - | `CalendarFormat` | The format used for conversion. Check the docs to see the format of possible modifiers you can pass. |
| `holidays` | - | `Date[]` | Define holidays. |
| `locale` | `"en-US"` | `AnyString \| Locale` | The locale of the calendar. |
| `max` | - | `number` | The maximum selectable value. |
| `maxDate` | `new Date(2099, 11, 31)` | `Date` | The maximum possible date. |
| `minDate` | `new Date(1900, 0, 1)` | `Date` | The minimum possible date. |
| `month` | - | `Date` | The month of the calendar. |
| `monthProps` | - | `CalendarMonthProps` | Props for the month component. |
| `monthSelectProps` | - | `CalendarMonthSelectProps` | Props for the month select component. |
| `multiple` | `false` | `Multiple` | If `true`, the calendar will be multiple. |
| `navigationProps` | - | `Omit` | Props for the navigation component. |
| `nextButtonProps` | - | `CalendarNextButtonProps` | Props for the next button component. |
| `onChange` | - | `(value: MaybeDateValue) => void` | The callback invoked when value state changes. |
| `onChangeMonth` | - | `(value: Date) => void` | The callback invoked when month state changes. |
| `prevButtonProps` | - | `CalendarPrevButtonProps` | Props for the prev button component. |
| `range` | `false` | `Range` | If `true`, enables date range selection. |
| `selectProps` | - | `Select.RootProps` | Props for the select component. |
| `shape` | `"circle"` | `"circle" \| "rounded" \| "square"` | The shape of the cell |
| `startDayOfWeek` | `"monday"` | `StartDayOfWeek` | Define the start day of the week. |
| `today` | `true` | `boolean` | If `true`, highlight today. |
| `value` | - | `MaybeDateValue` | The value of the calendar. |
| `weekdayProps` | - | `HTMLStyledProps<"th">` | Props for the weekday component. |
| `weekdaysProps` | - | `HTMLStyledProps<"tr">` | Props for the weekdays component. |
| `weekendDays` | `[0, 6]` | `number[]` | Define weekend days. |
| `weekProps` | - | `HTMLStyledProps<"tr">` | Props for the week component. |
| `weeksProps` | - | `HTMLStyledProps<"tbody">` | Props for the weeks component. |
| `yearSelectProps` | - | `CalendarYearSelectProps` | Props for the year select component. |
### Calendar.Control
| 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. |
| `children` | - | `ReactNodeOrFunction<{ month: Date }>` | The control children to use. |
### Calendar.Month
| 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. |
| `day` | - | `ReactNodeOrFunction<{ value: Date }>` | The day component to use. |
### Calendar.MonthSelect
| 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` | - | `"lg" \| "md" \| "sm" \| "xl" \| "xs"` | The size of the component. |
| `variant` | - | `"filled" \| "flushed" \| "outline" \| "plain"` | The variant of the component. |
| `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. |
| `clearable` | `false` | `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. |
| `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` | - | `SelectContentProps` | Props for content element. |
| `defaultOpen` | - | `boolean` | If `true`, the element will be initially opened. |
| `defaultValue` | - | `Multiple extends true ? string[] : string` | The initial value of the select. |
| `disabled` | `false` | `boolean` | If `true`, the combobox will be disabled. |
| `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" \| "ActiveBorder" \| "ActiveCaption" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" \| "amber.400" \| "amber.50" \| "amber.500" ...` | The border color when the input is invalid. |
| `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" \| "ActiveBorder" \| "ActiveCaption" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" \| "amber.400" \| "amber.50" \| "amber.500" ...` | The border color when the input is focused. |
| `focusOnClear` | `true` | `boolean` | If `true`, the field will be focused when the clear icon is clicked. |
| `groupProps` | - | `Omit` | Props for group element. |
| `gutter` | `8` | `number` | The distance or margin between the reference and popper. It is used internally to create an `offset` modifier. |
| `icon` | - | `ReactNode` | The icon to be used in the select. |
| `iconProps` | - | `SelectIconProps` | Props for icon element. |
| `includePlaceholder` | `true` | `boolean` | If `true`, include placeholder in options. |
| `invalid` | `false` | `boolean` | If `true`, the field will be invalid. |
| `items` | `[]` | `ComboboxItem[]` | If provided, generate options based on items. |
| `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. |
| `middleware` | - | `(false \| { name: string; options?: any; fn: (state: { x: number; y: number; placement: Placement; platform: Platform; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; elements: Elements; }) => Promisable<...>; } \| null \| undefined)[]` | Array of middleware objects to modify the positioning or provide data for rendering. |
| `multiple` | `false` | `Multiple` | If `true`, the select 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: Multiple extends true ? string[] : string) => void` | The callback invoked when value state changes. |
| `onClose` | - | `() => void \| Promise` | Callback invoked to close the element. |
| `onOpen` | - | `() => void \| Promise` | Callback invoked to open the element. |
| `open` | - | `boolean` | If `true`, the element will be opened. |
| `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. |
| `openOnSpace` | `true` | `boolean` | If `true`, the combobox will be opened when space is pressed. |
| `optionProps` | - | `Omit` | Props for option element. |
| `placeholder` | - | `string` | The placeholder for select. |
| `placeholderProps` | - | `Omit` | Props for placeholder element. |
| `placement` | `"end"` | `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. |
| `readOnly` | `false` | `boolean` | If `true`, the combobox will be readonly. |
| `render` | - | `(props: SelectRenderProps) => ReactNode` | The function to render the selected items. |
| `required` | `false` | `boolean` | If `true`, the field will be required. |
| `rootProps` | - | `InputGroup.RootProps` | Props for root element. |
| `selectFocusRef` | - | `RefObject` | 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. |
| `strategy` | `"absolute"` | `Strategy` | The CSS positioning strategy to use. |
| `transferFocus` | `true` | `boolean` | If `true`, the focus will be transferred to the popover content when the tab key is pressed. |
| `value` | - | `Multiple extends true ? string[] : string` | The value of the select. |
| `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`). |
| `wrap` | `false` | `boolean` | If `true`, wrap the value text. |
### Calendar.Navigation
| 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. |
### Calendar.NextButton
| 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. |
### Calendar.PrevButton
| 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. |
### Calendar.YearSelect
| 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` | - | `"lg" \| "md" \| "sm" \| "xl" \| "xs"` | The size of the component. |
| `variant` | - | `"filled" \| "flushed" \| "outline" \| "plain"` | The variant of the component. |
| `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. |
| `clearable` | `false` | `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. |
| `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` | - | `SelectContentProps` | Props for content element. |
| `defaultOpen` | - | `boolean` | If `true`, the element will be initially opened. |
| `defaultValue` | - | `Multiple extends true ? string[] : string` | The initial value of the select. |
| `disabled` | `false` | `boolean` | If `true`, the combobox will be disabled. |
| `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" \| "ActiveBorder" \| "ActiveCaption" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" \| "amber.400" \| "amber.50" \| "amber.500" ...` | The border color when the input is invalid. |
| `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" \| "ActiveBorder" \| "ActiveCaption" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" \| "amber.400" \| "amber.50" \| "amber.500" ...` | The border color when the input is focused. |
| `focusOnClear` | `true` | `boolean` | If `true`, the field will be focused when the clear icon is clicked. |
| `groupProps` | - | `Omit` | Props for group element. |
| `gutter` | `8` | `number` | The distance or margin between the reference and popper. It is used internally to create an `offset` modifier. |
| `icon` | - | `ReactNode` | The icon to be used in the select. |
| `iconProps` | - | `SelectIconProps` | Props for icon element. |
| `includePlaceholder` | `true` | `boolean` | If `true`, include placeholder in options. |
| `invalid` | `false` | `boolean` | If `true`, the field will be invalid. |
| `items` | `[]` | `ComboboxItem[]` | If provided, generate options based on items. |
| `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. |
| `middleware` | - | `(false \| { name: string; options?: any; fn: (state: { x: number; y: number; placement: Placement; platform: Platform; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; elements: Elements; }) => Promisable<...>; } \| null \| undefined)[]` | Array of middleware objects to modify the positioning or provide data for rendering. |
| `multiple` | `false` | `Multiple` | If `true`, the select 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: Multiple extends true ? string[] : string) => void` | The callback invoked when value state changes. |
| `onClose` | - | `() => void \| Promise` | Callback invoked to close the element. |
| `onOpen` | - | `() => void \| Promise` | Callback invoked to open the element. |
| `open` | - | `boolean` | If `true`, the element will be opened. |
| `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. |
| `openOnSpace` | `true` | `boolean` | If `true`, the combobox will be opened when space is pressed. |
| `optionProps` | - | `Omit` | Props for option element. |
| `placeholder` | - | `string` | The placeholder for select. |
| `placeholderProps` | - | `Omit` | Props for placeholder element. |
| `placement` | `"end"` | `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. |
| `readOnly` | `false` | `boolean` | If `true`, the combobox will be readonly. |
| `render` | - | `(props: SelectRenderProps) => ReactNode` | The function to render the selected items. |
| `required` | `false` | `boolean` | If `true`, the field will be required. |
| `rootProps` | - | `InputGroup.RootProps` | Props for root element. |
| `selectFocusRef` | - | `RefObject` | 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. |
| `strategy` | `"absolute"` | `Strategy` | The CSS positioning strategy to use. |
| `transferFocus` | `true` | `boolean` | If `true`, the focus will be transferred to the popover content when the tab key is pressed. |
| `value` | - | `Multiple extends true ? string[] : string` | The value of the select. |
| `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`). |
| `wrap` | `false` | `boolean` | If `true`, wrap the value text. |
## Accessibility
Currently, this section is being updated due to the migration of v2.