Calendar
React calendar for Tailwind and shadcn: single, range or multiple dates, two months, preset ranges, a hover preview of the range and full arrow-key support.
Installation
npx shadcn@latest add @minidev/calendar
MiniDev UI is in the shadcn registry directory, so the short form works with no setup. Older CLI versions can use the full URL: npx shadcn@latest add https://ui.minidev.pro/r/calendar.json
Usage
import { Calendar } from "@/components/ui/calendar"
export function Example() {
return (
<Calendar />
)
}
API reference
| Prop | Type | Default |
|---|---|---|
| mode"single" picks one day, "range" a from/to pair, "multiple" any set of days. | M | "single" as M |
| valueControlled selection: a Date, a `{ from, to }` range or a Date[], to match `mode`. | CalendarValue<M> | null | - |
| defaultValueStarting selection when uncontrolled. | CalendarValue<M> | null | null |
| onValueChangeFires with the whole new selection on every pick. | (value: CalendarValue<M>) => void | - |
| monthsMonths shown at once. Two sit side by side from the sm breakpoint and stack on phones. | 12 | 1 |
| defaultMonthThe first month shown. Defaults to the selection's month, else the current month. | Date | - |
| minEarliest day that can be picked. | Date | - |
| maxLatest day that can be picked. | Date | - |
| disabledDays that cannot be picked: a list of dates or a test function. | Date[] | ((date: Date) => boolean) | - |
| weekStartsOnFirst column of the week: 0 is Sunday, 1 is Monday. | 01 | 0 |
| localeBCP 47 locale for month, weekday and day labels. Fixed by default so server and client render the same text. | string | "en-US" |
| presetsReady-made ranges shown in a rail beside the grid. Range mode only. | CalendarPreset[] | - |
| showOutsideDaysShow the days of the previous and next month in muted text. | boolean | true |
| className | string | - |
When to use
Use it inline or inside a Popover when people need to see the month: bookings, report periods, availability. Set mode to "single", "range" or "multiple"; value is then a Date, a { from, to } range or a Date[]. months={2} shows two months side by side from the sm breakpoint, and presets adds a rail of ready-made ranges in range mode. Bound it with min, max and disabled. Month and day names come from Intl.DateTimeFormat in locale. It has no frame, so it sits flush in a Popover or card; on its own add className="rounded-xl border border-border bg-surface shadow-raised". For a typed native field use DatePicker or DateRangePicker, for a date plus a time use DateTimePicker, and to show events use EventCalendar.
Keyboard interactions
| Key | Action |
|---|---|
| ArrowLeftorArrowRight | Moves focus one day back or forward. Past the edge of the visible months, the next or previous month slides in. |
| ArrowUporArrowDown | Moves focus one week back or forward. |
| PageUporPageDown | Moves focus one month, keeping the day where it exists: 31 January goes to 28 February. |
| ShiftPageUporShiftPageDown | Moves focus one year. |
| HomeorEnd | Moves focus to the first or last day of the week, following weekStartsOn. |
| EnterorSpace | Picks the focused day. Disabled days do nothing. |
| Tab | Moves through the preset buttons, the previous and next month buttons, then the days. All grids share one tab stop. |
Accessibility
- Each month is a
role="grid"named by its month and year, with weekday column headers labelled by the full day name. In range and multiple mode the grid hasaria-multiselectable. - Each day is a
<button>whosearia-labelis the full date fromIntl.DateTimeFormat, such as "Saturday, November 14, 2026". Picked days and days inside a finished range setaria-selectedon their cell, today hasaria-current="date", and disabled days havearia-disabledbut stay focusable. - Only one day has
tabIndex=0: the last focused day, else the selection, else today, else the 1st of the first month shown. Arrow keys stop atminandmax, and days from neighbouring months are never a tab stop. - Month changes are announced by a visually hidden
aria-live="polite"region. The month slides with the snappy spring, which becomes an instant swap underuseReducedMotion.
Frequently asked questions
How do I build a date range picker with Calendar?
Set mode="range". onValueChange receives { from, to }, and to stays undefined until the second click; a click before from restarts the range on that day, and a click after a finished range starts a new one. For a field that opens a calendar, put it in a Popover with a Button trigger.
Does a range skip disabled days?
No. disabled, min and max stop a day from being clicked, but a range from 3 to 10 November still contains a disabled 7 November. If a gap must not be crossed, such as a booked night, check the range in onValueChange before you store it.
How do I use Calendar with React Hook Form or a plain form?
Calendar has no name and renders no input, so FormData will not see it. With React Hook Form, wrap it in a Controller and pass value={field.value} and onValueChange={field.onChange}. For a native date field use DatePicker; DateTimePicker takes a name and submits an ISO string.
Why is the calendar empty in the server HTML?
Today depends on the visitor's clock, so Calendar reads it only in the browser: with no value, defaultValue or defaultMonth, the server renders an empty box of the same size and the browser fills it in. Pass defaultMonth to get days in the server HTML. locale defaults to "en-US" for the same reason; pass the user's locale and weekStartsOn={1} where Monday comes first.
Dependencies
npm
Built from
Examples
Delivery day
One day, bounded by min and max, with weekends disabled by a test function and Monday as the first column.
Report period with presets
Two months side by side and a rail of preset ranges. After the first click, the band previews the range under the pointer.
On-call rota
Multiple mode toggles each day on and off and returns the days sorted.