Calendar

Choose a date or explore a month using a calendar grid.

View component source ↗

Preview

Example

A minimal example to get started.

September 2026

Installation

Install this component and its dependencies in a project initialized with shadcn.

pnpm dlx shadcn@latest add https://ui.hyunjoon.net/r/calendar.json

Usage

This is the basic example. Use the Code tab above for the selected example. Adjust import aliases to match your project.

import { useState } from "react";

import { Calendar } from "@/components/ui/calendar";

export default function Example() {
  const [date, setDate] = useState<Date | undefined>(new Date(2026, 8, 20));
  return (
    <Calendar
      mode="single"
      selected={date}
      onSelect={setDate}
      defaultMonth={new Date(2026, 8, 1)}
      className="rounded-lg border"
    />
  );
}

API reference

Derived from the installed component types. Native DOM props are also supported where applicable. A dash means no explicit default is documented. Some props depend on the selected mode.

Calendar

Calendar properties
Prop	Type	Default	Description
`mode`	"single" \| "multiple" \| "range" \| undefined "single" \| "multiple" \| "range" \| undefined	`—`	Enable the selection of a single day, multiple days, or a range of days.
`required`	false \| undefined \| true \| undefined false \| undefined \| true \| undefined	`—`	Whether the selection is required.
`className`	string \| undefined string \| undefined	`—`	Class name to add to the root element.
`classNames`	Partial<ClassNames> \| undefined Partial<ClassNames> \| undefined	`—`	Change the class names used by DayPicker. Use this prop when you need to change the default class names — for example, when importing the style via CSS modules or when using a CSS framework.
`modifiersClassNames`	ModifiersClassNames \| undefined ModifiersClassNames \| undefined	`—`	Change the class name for the day matching the `modifiers`.
`style`	React.CSSProperties \| undefined React.CSSProperties \| undefined	`—`	Style to apply to the root element.
`styles`	Partial<Styles> \| undefined Partial<Styles> \| undefined	`—`	Change the inline styles of the HTML elements.
`modifiersStyles`	ModifiersStyles \| undefined ModifiersStyles \| undefined	`—`	Change the class name for the day matching the modifiers.
`id`	string \| undefined string \| undefined	`—`	A unique id to add to the root element.
`defaultMonth`	Date \| undefined Date \| undefined	`The current month`	The initial month to show in the calendar. Use this prop to let DayPicker control the current month. If you need to set the month programmatically, use month and onMonthChange.
`month`	Date \| undefined Date \| undefined	`—`	The month displayed in the calendar. As opposed to `defaultMonth`, use this prop with `onMonthChange` to change the month programmatically.
`numberOfMonths`	number \| undefined number \| undefined	`1`	The number of displayed months.
`startMonth`	Date \| undefined Date \| undefined	`—`	The earliest month to start the month navigation.
`endMonth`	Date \| undefined Date \| undefined	`—`	The latest month to end the month navigation.
`pagedNavigation`	boolean \| undefined boolean \| undefined	`—`	Paginate the month navigation displaying the `numberOfMonths` at a time.
`reverseMonths`	boolean \| undefined boolean \| undefined	`—`	Render the months in reversed order (when numberOfMonths is set) to display the most recent month first.
`hideNavigation`	boolean \| undefined boolean \| undefined	`—`	Hide the navigation buttons. This prop won't disable the navigation: to disable the navigation, use disableNavigation.
`disableNavigation`	boolean \| undefined boolean \| undefined	`—`	Disable the navigation between months. This prop won't hide the navigation: to hide the navigation, use hideNavigation.
`captionLayout`	"label" \| "dropdown" \| "dropdown-months" \| "dropdown-years" \| undefined "label" \| "dropdown" \| "dropdown-months" \| "dropdown-years" \| undefined	`"label"`	Show dropdowns to navigate between months or years. - `label`: Displays the month and year as a label. Default value. - `dropdown`: Displays dropdowns for both month and year navigation. - `dropdown-months`: Displays a dropdown only for the month navigation. - `dropdown-years`: Displays a dropdown only for the year navigation. Note: By default, showing the dropdown will set the startMonth to 100 years ago and endMonth to the end of the current year. You can override this behavior by explicitly setting `startMonth` and `endMonth`.
`reverseYears`	boolean \| undefined boolean \| undefined	`—`	Reverse the order of years in the dropdown when using `captionLayout="dropdown"` or `captionLayout="dropdown-years"`.
`navLayout`	"around" \| "after" \| undefined "around" \| "after" \| undefined	`—`	Adjust the positioning of the navigation buttons. - `around`: Displays the buttons on either side of the caption. - `after`: Displays the buttons after the caption. This ensures the tab order matches the visual order. If not set, DayPicker preserves its legacy layout, but the tab order may not align with the visual order when using `captionLayout="dropdown"`.
`fixedWeeks`	boolean \| undefined boolean \| undefined	`—`	Display always 6 weeks per each month, regardless of the month’s number of weeks. Weeks will be filled with the days from the next month.
`hideWeekdays`	boolean \| undefined boolean \| undefined	`—`	Hide the row displaying the weekday row header.
`showOutsideDays`	boolean \| undefined boolean \| undefined	`true`	Show the outside days (days falling in the next or the previous month). Note: when a broadcastCalendar is set, this prop defaults to true.
`showWeekNumber`	boolean \| undefined boolean \| undefined	`—`	Show the week numbers column. Weeks are numbered according to the local week index.
`animate`	boolean \| undefined boolean \| undefined	`—`	Animate navigating between months.
`broadcastCalendar`	boolean \| undefined boolean \| undefined	`—`	Display the weeks in the month following the broadcast calendar. Setting this prop will ignore weekStartsOn (always Monday) and showOutsideDays will default to true.
`ISOWeek`	boolean \| undefined boolean \| undefined	`—`	Use ISO week dates instead of the locale setting. Setting this prop will ignore `weekStartsOn` and `firstWeekContainsDate`.
`timeZone`	string \| undefined string \| undefined	`—`	The time zone (IANA or UTC offset) to use in the calendar (experimental). See [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for the possible values.
`noonSafe`	boolean \| undefined boolean \| undefined	`—`	Keep calendar math at noon in the configured timeZone to avoid historical second-level offsets drifting dates across midnight. This prop sets the time of the dates to noon (12:00).
`components`	Partial<CustomComponents> \| undefined Partial<CustomComponents> \| undefined	`—`	Change the components used for rendering the calendar elements.
`footer`	React.ReactNode React.ReactNode	`—`	Add a footer to the calendar, acting as a live region. Use this prop to communicate the calendar's status to screen readers. Prefer strings over complex UI elements.
`autoFocus`	boolean \| undefined boolean \| undefined	`—`	When a selection mode is set, DayPicker will focus the first selected day (if set) or today's date (if not disabled). Use this prop when you need to focus DayPicker after a user action, for improved accessibility.
`disabled`	Matcher \| Matcher[] \| undefined Matcher \| Matcher[] \| undefined	`—`	Apply the `disabled` modifier to the matching days. Disabled days cannot be selected when in a selection mode is set.
`hidden`	Matcher \| Matcher[] \| undefined Matcher \| Matcher[] \| undefined	`—`	Apply the `hidden` modifier to the matching days. Will hide them from the calendar.
`today`	Date \| undefined Date \| undefined	`—`	The today’s date. Default is the current date. This date will get the `today` modifier to style the day.
`modifiers`	Record<string, Matcher \| Matcher[] \| undefined> \| undefined Record<string, Matcher \| Matcher[] \| undefined> \| undefined	`—`	Add modifiers to the matching days.
`labels`	Partial<Labels> \| undefined Partial<Labels> \| undefined	`—`	Labels creators to override the defaults. Use this prop to customize the aria-label attributes in DayPicker.
`formatters`	Partial<Formatters> \| undefined Partial<Formatters> \| undefined	`—`	Formatters used to format dates to strings. Use this prop to override the default functions.
`dir`	string \| undefined string \| undefined	`—`	The text direction of the calendar. Use `ltr` for left-to-right (default) or `rtl` for right-to-left.
`aria-label`	string \| undefined string \| undefined	`—`	The aria-label attribute to add to the container element.
`aria-labelledby`	string \| undefined string \| undefined	`—`	The aria-labelledby attribute to add to the container element.
`role`	"dialog" \| "application" \| undefined "dialog" \| "application" \| undefined	`—`	The role attribute to add to the container element.
`nonce`	string \| undefined string \| undefined	`—`	A cryptographic nonce ("number used once") which can be used by Content Security Policy for the inline `style` attributes.
`title`	string \| undefined string \| undefined	`—`	Add a `title` attribute to the container element.
`lang`	string \| undefined string \| undefined	`—`	Add the language tag to the container element. When omitted, DayPicker uses the active locale code (`locale.code`). Set this prop to override the language tag.
`locale`	Partial<DayPickerLocale> \| undefined Partial<DayPickerLocale> \| undefined	enUS - The English locale default of `date-fns`.	The locale object used to localize dates. Pass a locale from `react-day-picker/locale` to localize the calendar.
`numerals`	Numerals \| undefined Numerals \| undefined	`latn` Latin (Western Arabic)	The numeral system to use when formatting dates. - `latn`: Latin (Western Arabic) - `arab`: Arabic-Indic - `arabext`: Eastern Arabic-Indic (Persian) - `deva`: Devanagari - `beng`: Bengali - `guru`: Gurmukhi - `gujr`: Gujarati - `orya`: Oriya - `tamldec`: Tamil - `telu`: Telugu - `knda`: Kannada - `mlym`: Malayalam
`weekStartsOn`	0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined 0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined	`—`	The index of the first day of the week (0 - Sunday). Overrides the locale's default.
`firstWeekContainsDate`	1 \| 4 \| undefined 1 \| 4 \| undefined	`—`	The day of January that is always in the first week of the year.
`useAdditionalWeekYearTokens`	boolean \| undefined boolean \| undefined	`—`	Enable `DD` and `DDDD` for week year tokens when formatting or parsing dates.
`useAdditionalDayOfYearTokens`	boolean \| undefined boolean \| undefined	`—`	Enable `YY` and `YYYY` for day of year tokens when formatting or parsing dates.
`onMonthChange`	MonthChangeEventHandler \| undefined MonthChangeEventHandler \| undefined	`—`	Event fired when the user navigates between months.
`onNextClick`	MonthChangeEventHandler \| undefined MonthChangeEventHandler \| undefined	`—`	Event handler when the next month button is clicked.
`onPrevClick`	MonthChangeEventHandler \| undefined MonthChangeEventHandler \| undefined	`—`	Event handler when the previous month button is clicked.
`onDayClick`	DayEventHandler<React.MouseEvent<Element, MouseEvent>> \| undefined DayEventHandler<React.MouseEvent<Element, MouseEvent>> \| undefined	`—`	Event handler when a day is clicked.
`onDayFocus`	DayEventHandler<React.FocusEvent<Element, Element>> \| undefined DayEventHandler<React.FocusEvent<Element, Element>> \| undefined	`—`	Event handler when a day is focused.
`onDayBlur`	DayEventHandler<React.FocusEvent<Element, Element>> \| undefined DayEventHandler<React.FocusEvent<Element, Element>> \| undefined	`—`	Event handler when a day is blurred.
`onDayKeyDown`	DayEventHandler<React.KeyboardEvent<Element>> \| undefined DayEventHandler<React.KeyboardEvent<Element>> \| undefined	`—`	Event handler when a key is pressed on a day.
`onDayMouseEnter`	DayEventHandler<React.MouseEvent<Element, MouseEvent>> \| undefined DayEventHandler<React.MouseEvent<Element, MouseEvent>> \| undefined	`—`	Event handler when the mouse enters a day.
`onDayMouseLeave`	DayEventHandler<React.MouseEvent<Element, MouseEvent>> \| undefined DayEventHandler<React.MouseEvent<Element, MouseEvent>> \| undefined	`—`	Event handler when the mouse leaves a day.
`dateLib`	Partial<DateLib> \| undefined Partial<DateLib> \| undefined	`—`	Replace the default date library with a custom one. Experimental: not guaranteed to be stable (may not respect semver).
`selected`	Date \| undefined \| Date[] \| undefined \| DateRange \| undefined Date \| undefined \| Date[] \| undefined \| DateRange \| undefined	`—`	The selected date.
`onSelect`	OnSelectHandler<Date \| undefined> \| undefined \| OnSelectHandler<Date> \| undefined \| OnSele… OnSelectHandler<Date \| undefined> \| undefined \| OnSelectHandler<Date> \| undefined \| OnSelectHandler<Date[] \| undefined> \| undefined \| OnSelectHandler<Date[]> \| undefined \| OnSelectHandler<DateRange \| undefined> \| undefined \| OnSelectHandler<DateRange> \| undefined	`—`	Event handler when a day is selected.
`buttonVariant`	"link" \| "default" \| "destructive" \| "outline" \| "secondary" \| "ghost" \| null \| undefined "link" \| "default" \| "destructive" \| "outline" \| "secondary" \| "ghost" \| null \| undefined	`"ghost"`	Visual variant used for calendar navigation buttons.
`min`	number \| undefined number \| undefined	`—`	The minimum number of selectable days.
`max`	number \| undefined number \| undefined	`—`	The maximum number of selectable days.
`excludeDisabled`	boolean \| undefined boolean \| undefined	`—`	When `true`, the range will reset when including a disabled day.
`resetOnSelect`	boolean \| undefined boolean \| undefined	`—`	When `true`, clicking a day starts a new range if there is no current start date or if a range is already complete. In those cases, the clicked day becomes the start of the new range. When `required` is `false`, clicking the same day of a single-day range clears the selection.

CalendarDayButton

CalendarDayButton properties
Prop	Type	Default	Description
`day`Required	CalendarDay CalendarDay	`—`	The day to render.
`modifiers`Required	Modifiers Modifiers	`—`	The modifiers to apply to the day.
`disabled`	boolean \| undefined boolean \| undefined	`—`	Prevents user interaction.
`name`	string \| undefined string \| undefined	`—`	Field name used in form data.
`type`	"button" \| "submit" \| "reset" \| undefined "button" \| "submit" \| "reset" \| undefined	`—`	The native input or button behavior.
`value`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	The current value when controlled by the application.
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	React.FocusEventHandler<HTMLButtonElement> \| undefined React.FocusEventHandler<HTMLButtonElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLButtonElement> \| undefined React.FocusEventHandler<HTMLButtonElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLButtonElement, Element> \| undefined React.ChangeEventHandler<HTMLButtonElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLButtonElement> \| undefined React.KeyboardEventHandler<HTMLButtonElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLButtonElement> \| undefined React.MouseEventHandler<HTMLButtonElement> \| undefined	`—`	Called when the element is activated.
`locale`	Partial<DayPickerLocale> \| undefined Partial<DayPickerLocale> \| undefined	`—`	Locale used for date labels and formatting.

Usage notes

Set mode to single, multiple, or range. Connect selected and onSelect when the application controls the selection.