Calendar React component
An inline month calendar for picking one day, a range or several days, with event dots under their days, an agenda for the selected day, months that slide in from the side they come from, a month picker, week numbers and full keyboard control.
About the Calendar component
Calendar is a full month view that lives on the page rather than in a popover, for booking screens, schedules and dashboards. It can pick one day, a range or any set of days, slides between months with arrows, and can show colored dots for events under their days with an agenda of the selected day's events listed below the grid. Today is marked, and a Today button jumps back to the current month.
mode picks single, range or multiple, each with its own value, default and change handler (value, range or dates). month or defaultMonth with onMonthChange set the month on show. minDate, maxDate and isDateDisabled block days, weekStartsOn starts weeks on Sunday (0) or Monday (1, the default), and locale names the months and weekdays. showWeekNumbers, showOutsideDays and showTodayButton toggle those parts, and size picks sm, md or lg. Dates are handled in local time.
When to use it
Use Calendar when the calendar itself belongs on the page: booking and availability screens, a schedule next to a list of events, picking several days at once, or a dashboard widget. It shows where things are in the month at a glance.
If the date only needs to go into a form field, use Date Picker instead; it keeps the calendar in a popover until it's needed.
Installation
Add the Calendar component to your project with the shadcn CLI. It lands in components/calendar.tsx as plain React + Tailwind CSS source you own and can edit.
npx shadcn@latest add @reactframe/calendarOr copy the source by hand and install its dependencies:
npm install motion clsx tailwind-mergeProps
<Calendar /> accepts 26 props, all optional.
| Prop | Type | Default |
|---|---|---|
| mode single: one day. range: a start and end day. multiple: any set of days. | "single" | "range" | "multiple" | "single" |
| value | Date | null | — |
| defaultValue | Date | null | null |
| onValueChange | (value: Date | null) => void | — |
| range | object | — |
| range.from | Date | — |
| range.to | Date | — |
| defaultRange | object | {} |
| defaultRange.from | Date | — |
| defaultRange.to | Date | — |
| onRangeChange | (range: CalendarRange) => void | — |
| dates | Date[] | — |
- mode
single: one day. range: a start and end day. multiple: any set of days.
"single" | "range" | "multiple"Default: "single" - valueDate | null
- defaultValueDate | nullDefault: null
- onValueChange(value: Date | null) => void
- rangeobject
- range.fromDate
- range.toDate
- defaultRangeobjectDefault: {}
- defaultRange.fromDate
- defaultRange.toDate
- onRangeChange(range: CalendarRange) => void
- datesDate[]
Show all 30 propsShow fewer
| defaultDates | Date[] | [] |
| onDatesChange | (dates: Date[]) => void | — |
| month The month on show (any day in it). | Date | — |
| defaultMonth | Date | — |
| onMonthChange | (month: Date) => void | — |
| events Dots under their days, and a list of the selected day's events when showAgenda is on. | { date: Date; title: string; time?: string; color?: string }[] | [] |
| showAgenda | boolean | false |
| minDate | Date | — |
| maxDate | Date | — |
| isDateDisabled | (date: Date) => boolean | — |
| weekStartsOn | 0 | 1 | 1 |
| locale | string | "en-US" |
| showWeekNumbers | boolean | false |
| showOutsideDays | boolean | true |
| showTodayButton A "Today" button in the header that jumps back to the current month. | boolean | true |
| size | "sm" | "md" | "lg" | "md" |
| theme | "dark" | "light" | "dark" |
| className | string | — |
- defaultDatesDate[]Default: []
- onDatesChange(dates: Date[]) => void
- month
The month on show (any day in it).
Date - defaultMonthDate
- onMonthChange(month: Date) => void
- events
Dots under their days, and a list of the selected day's events when showAgenda is on.
{ date: Date; title: string; time?: string; color?: string }[]Default: [] - showAgendabooleanDefault: false
- minDateDate
- maxDateDate
- isDateDisabled(date: Date) => boolean
- weekStartsOn0 | 1Default: 1
- localestringDefault: "en-US"
- showWeekNumbersbooleanDefault: false
- showOutsideDaysbooleanDefault: true
- showTodayButton
A "Today" button in the header that jumps back to the current month.
booleanDefault: true - size"sm" | "md" | "lg"Default: "md"
- theme"dark" | "light"Default: "dark"
- classNamestring
npm dependencies
Installed for you by the shadcn CLI.
Calendar FAQ
- Can people pick a range or several days?
- Yes. mode="range" picks a start and end day (the band follows the pointer while you choose the end); mode="multiple" toggles any number of days.
- How do events show up?
- Pass events with a date, title and optional time and colour. Each day shows up to three dots, and with showAgenda the selected day's events are listed under the grid.
- Is it keyboard accessible?
- It's a grid with one tab stop: arrows move by day and week, Home and End jump to the week's edges, Page Up and Page Down change month, and Enter or Space selects.
- Why is the calendar an empty box in the server HTML?
- Without a month or a selected date it waits for the browser's clock to know which month is current, because the server's date and time zone can differ. Pass defaultMonth (or a value) and it renders that month on the server too.
