Calendar
FreeA month grid for picking one date or a range, with keyboard navigation and limits on which days can be chosen.
npx wunderui-cli add calendarPlayground
November 2026
Installation
npx wunderui-cli add calendarWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import {
Calendar,
CalendarDay,
CalendarHeader,
CalendarPeriodCell,
CalendarPeriodPicker,
} from "@/components/wunderui/calendar"
import type {
CalendarDayProps,
CalendarHeaderProps,
CalendarPeriodCellProps,
CalendarPeriodPickerProps,
CalendarProps,
} from "@/components/wunderui/calendar"Then use it:
import { useState } from "react"
import { Calendar } from "@/components/ui/calendar"
export function Schedule() {
const [date, setDate] = useState<Date | undefined>(new Date())
return <Calendar mode="single" size="md" selected={date} onSelect={setDate} />
}Expected result: You see the current month as a six-week grid with today chosen. Click another day to move the choice, and use the arrows or arrow keys to change the month.
When to use
Use Calendar for
- Showing a month next to a schedule, with a dot on the days that have events
- Picking one day, or a start and an end day, where the calendar is the main control
- A booking window with days that are blocked, booked or still open
Use something else for
- Date Picker for a date in a form field, where the calendar opens in a popover
- Agenda for a list of events grouped by day
- Timeline for events in the order they happened
Header
The header shows the month with previous and next arrows. Use month and year buttons when people jump far, like to a birth date.
November 2026
November 2026
November 2026
November 2026
November 2026
Period picker
CalendarPeriodPicker picks a month or a year directly. The month and year header opens it, and it also works on its own.
2026
2020 – 2031
Day
CalendarDay is one cell. What a day means (selected, in a range, outside the month) is separate from the pointer state, so one day can be today, selected and focused at once.
Marks and limits
Mark days that carry data with a dot, limit the choice with a minimum, maximum or disabled days, and give a reason for blocked days. Hover a past day in the last tab to see it.
November 2026
November 2026
November 2026
Status
While data loads or fails, the days cannot be picked. The calendar only blocks them, and the banner that explains why is yours to place.
November 2026
November 2026
Loading availability
November 2026
No open slots in November
November 2026
Availability could not load
Keyboard interactions
The day grid is one Tab stop with roving focus. Tab enters on the chosen day, today or the first of the month, and the keys below move inside the grid.
- TaborShift+Tab
- Moves focus into the grid once, then on to the next control. The header buttons are separate tab stops before the grid.
- ArrowLeftorArrowRight
- Moves focus one day back or forward. At the edge of the month it opens the neighbouring month.
- ArrowUporArrowDown
- Moves focus one week back or forward.
- HomeorEnd
- Moves focus to the first or the last day of the week.
- PageUporPageDown
- Moves focus one month back or forward, keeping the day of the month where it exists. With Shift it moves one year.
- EnterorSpace
- Picks the focused day. A blocked day stays reachable with the arrow keys but is not picked, and nothing is picked while is not .
- Escape
- In the month or year picker: goes back to the days.
Behavior and motion
What the calendar does with state, the grid, restrictions and motion.
- Controlled or not
- You can control the selection and the visible month, or let the calendar keep them. The month starts on the default month, the chosen day or today.
- Six weeks
- The grid always shows six weeks, Monday first, so the height stays the same in every month. Days of neighbouring months are dimmed but still clickable.
- Range
- In range mode a click before the start swaps the two ends. While only the start exists, days up to the hovered or focused day show a preview band.
- Limits
- Days outside the minimum and maximum are blocked and the month arrows lock at the edge. Blocked days are dimmed, announced as unavailable and skipped by Enter, but arrow keys still reach them.
- Status
- A loading, empty or error status blocks every day, and loading marks the grid as busy. The calendar draws no banner itself.
- Names
- Each day is named with its full date, such as Thursday, November 12, 2026, plus its marked label or blocked reason. The grid is named by its month heading.
- Motion
- A day changes its fill quickly on hover and press. Only colour changes and nothing moves.
- Reduced motion
- With reduced motion nothing changes, since the calendar has no movement. The Tooltip on a blocked day keeps its own motion.
Anatomy
The figure marks the header, weekday row, range start, range band, a marked day and today. The period picker, restrictions and status banner replace or sit next to the grid.
November 2026
- data-slot="calendar"
An inline month grid, Monday first, for a single day or a range, with 32 px or 40 px days. For a field with a popover, use DatePicker.
- 1Optional
The month title between the previous and next buttons, as a plain label or two buttons that open the month and year picker. A hidden arrow keeps its slot, so the title stays centred.
- 2
Seven weekday labels, Mo to Su, each read as the full weekday by screen readers. The grid always shows six weeks, so its height never changes.
- 3
One button per day: selection, today, outside days and unavailable days describe the date, while hover, pressed and focus describe the pointer. The figure marks the start of a range.
- 4Optional
In range mode, days between start and end form one connected tint band with filled, rounded ends. While only the start exists, hovering a later day previews the band.
- 5Optional
A dot under the number of a day that has data, such as an event or an open slot. The dot is never the only cue: a label is added to the day's accessible name.
- 6Optional
Today has a ring on top of any selection. You can override today's date, which helps in demos and tests.
- Optional
A 3 by 4 grid of months or twelve years with its own previous and next buttons. It opens from the month and year header and also works on its own.
- Optional
A blocked day can show its reason in a tooltip and in its accessible name. A loading, empty or error status blocks every day, and the banner that explains it sits next to the calendar.
- Optional
One month or year button in the period picker.
Best practices
- Do
Use Calendar to show a month inline, next to a schedule or in your own popover. To pick a date in a form field, use DatePicker.
- Do
In range mode the first click sets the start, the second the end, and a third starts a new range. A range without an end is a draft, so say in the interface what is missing.
- Do
Use the larger size (40 px days) when the calendar is the main control and the smaller one (32 px) in dense panels.
- Do
Use the month and year header for birth dates and other far dates, so nobody pages month by month. Set the starting month, or control the month when two calendars must move together.
- Do
Limit the choice with a minimum and maximum, and block single days with a list or a rule such as weekends. Say why in a tooltip or in the text nearby.
- Do
Mark days that carry data and name the meaning, for example has events or has open slots.
- Do
While data loads or fails, set the status and show a banner beside the calendar that explains why and offers a retry.
- Don’t
Don't rely on a dot alone to show that a day has events. Name its meaning and list the events next to the calendar.
- Don’t
Don't show hover, pressed or the range preview as a confirmed choice. A confirmed day never changes on hover, and the preview band is lighter.
- Don’t
Don't block days without saying why. Screen readers announce a blocked day as unavailable, but a sighted person sees only a dimmed number.
API reference
One table per part. Calendar, CalendarHeader and CalendarPeriodPicker list every prop, while CalendarDay and CalendarPeriodCell are buttons that also take every native button attribute.
An inline month grid, Monday first, for a single day or a range, with 32 px or 40 px days. For a field with a popover, use DatePicker.
| Prop | Type | Default | Description |
|---|---|---|---|
| mode | "single" | "single" | picks one day and picks a start and an end. It also decides the shape of and : a , or . |
| selected | Date | — | The chosen day () or range (). The calendar does not keep it: update it in . |
| onSelect | (date) => void | — | Called with the day that was picked, or in mode with the new . A range without is a draft. |
| month | Date | — | The visible month, to control it. Use it with when two calendars must move together. |
| defaultMonth | Date | — | The month to open on when is not set. Defaults to the month of the chosen day, else today. |
| onMonthChange | (month) => void | — | Called with the first day of the new month when the arrows, the keyboard or the period picker change it. |
| min | Date | — | The earliest day that can be picked. Keyboard focus stops here and earlier months cannot be opened. |
| max | Date | — | The latest day that can be picked. Keyboard focus stops here and later months cannot be opened. |
| disabled | CalendarDisabled | — | Days inside and that cannot be picked: a list of dates, or a function that returns true for a blocked day. They stay reachable with the arrow keys and are announced as unavailable. |
| size | "sm" | "md" | "sm" | The size of the day cells: is 32 px (the default) and is 40 px. |
| header | "label" | "month-year" | "label" | shows the month as a title; shows two buttons that open the month and year picker. |
| navigation | "both" | "previous" | "next" | "none" | "both" | Which arrows to show: (the default), , or . A hidden arrow keeps its slot. |
| markedDays | Date[] | (date) => boolean | — | Days that get a dot under the number: a list of dates, or a function that returns true for a marked day. |
| markedLabel | string | "marked" | Words added to the accessible name of a marked day, for example . Defaults to . |
| disabledReason | string | — | When set, every blocked day shows this text in a tooltip and in its accessible name. |
| status | "ready" | "loading" | "empty" | "error" | "ready" | The state of the data behind the calendar: (the default), , or . Anything but blocks every day. |
| today | Date | — | Overrides the date of today, which defaults to . Use it for demos and tests. |
| hoverDay | Date | — | Shows the range preview up to this day as if it were hovered. For documentation. |
| reasonDefaultOpenDay | Date | — | The blocked day whose tooltip starts open. For documentation. |
| className | string | — | Extra classes for the calendar root. |
The month title between the previous and next buttons, as a plain label or two buttons that open the month and year picker. A hidden arrow keeps its slot, so the title stays centred.
| Prop | Type | Default | Description |
|---|---|---|---|
| month required | Date | — | The month the title shows. |
| type | "label" | "month-year" | "label" | for a title, for two buttons. |
| navigation | "both" | "previous" | "next" | "none" | "both" | Which arrows to show: , , or . |
| size | "sm" | "md" | "sm" | or , to match the size of the days. |
| previousDisabled | boolean | — | Disables the previous button, for example at the minimum date. |
| nextDisabled | boolean | — | Disables the next button, for example at the maximum date. |
| onPrevious | () => void | — | Called when the previous button is pressed. |
| onNext | () => void | — | Called when the next button is pressed. |
| onMonthClick | () => void | — | Called when the month button of the header is pressed. |
| onYearClick | () => void | — | Called when the year button of the header is pressed. |
| headingId | string | — | The id of the title, so the grid can name itself by it. |
| className | string | — | Extra classes for the header row. |
One button per day: selection, today, outside days and unavailable days describe the date, while hover, pressed and focus describe the pointer. The figure marks the start of a range.
| Prop | Type | Default | Description |
|---|---|---|---|
| selection | "none" | "single" | "start" | "middle" | "end" | "preview" | "none" | What the day means in the choice: , , , , or (the lighter band while a range is being chosen). |
| today | boolean | — | Rings the day as today, on top of any selection. |
| outside | boolean | — | Dims the day because it belongs to the neighbouring month. |
| unavailable | boolean | — | Dims the day and blocks the pointer. Set it for days outside and , blocked days and every day while the data is not ready. |
| marked | boolean | — | Draws a dot under the number. |
| interaction | "rest" | "hover" | "pressed" | "focus" | "rest" | Forces the look of a pointer state (, , , ) for documentation. Real hover, press and focus need no prop. |
| size | "sm" | "md" | "md" | The size of the cell: is 32 px and is 40 px. |
A 3 by 4 grid of months or twelve years with its own previous and next buttons. It opens from the month and year header and also works on its own.
| Prop | Type | Default | Description |
|---|---|---|---|
| type required | "month" | "year" | — | shows the twelve months of a year, shows twelve years. |
| month | Date | — | The reference month: its year is shown, or the window of twelve years that contains it. |
| selected | Date | — | The chosen month or year, filled in the grid. |
| onSelect | (date) => void | — | Called with the first day of the chosen month, or with a date in the chosen year. |
| onNavigate | (reference) => void | — | Called with the new reference date when the previous or next button moves to another year or window. |
| today | Date | — | Overrides the date of today, which gets the ring. |
| min | Date | — | Months or years before this are unavailable. |
| max | Date | — | Months or years after this are unavailable. |
| className | string | — | Extra classes for the picker root. |
One month or year button in the period picker.
| Prop | Type | Default | Description |
|---|---|---|---|
| selected | boolean | — | Fills the cell as the chosen month or year. |
| current | boolean | — | Rings the cell as the current month or year. |
| unavailable | boolean | — | Dims the cell and blocks the pointer. |
| interaction | "rest" | "hover" | "pressed" | "focus" | "rest" | Forces the look of a pointer state for documentation. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("calendar")npx wunderui-cli add calendarThe full library index for assistants is at /llms.txt.