Calendar
A month grid the traveller picks one day or a range from.
November 2026
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
1 | 2 | 3 | 4 | 5 | 6 | 7 |
8 | 9 | 10 | 11 | 12 | 13 | 14 |
15 | 16 | 17 | 18 | 19 | 20 | 21 |
22 | 23 | 24 | 25 | 26 | 27 | 28 |
29 | 30 | 1 | 2 | 3 | 4 | 5 |
6 | 7 | 8 | 9 | 10 | 11 | 12 |
Installation
npx shadcn@latest add @flyingsalmon/calendarUsage
import { useState } from 'react'
import { Calendar } from '@/components/ui/calendar'
export function CalendarUsage() {
const [departure, setDeparture] = useState<string | null>(null)
return (
<Calendar
aria-label="Departure"
value={departure}
onChange={setDeparture}
/>
)
}Examples
A range
Two taps is the range path: one on the first day, one on the last. Dragging across the grid works too. While the first day is anchored, the pointer or the keyboard cursor previews the range, and Escape drops the anchor.
November 2026
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
1 | 2 | 3 | 4 | 5 | 6 | 7 |
8 | 9 | 10 | 11 | 12 | 13 | 14 |
15 | 16 | 17 | 18 | 19 | 20 | 21 |
22 | 23 | 24 | 25 | 26 | 27 | 28 |
29 | 30 | 1 | 2 | 3 | 4 | 5 |
6 | 7 | 8 | 9 | 10 | 11 | 12 |
December 2026
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
29 | 30 | 1 | 2 | 3 | 4 | 5 |
6 | 7 | 8 | 9 | 10 | 11 | 12 |
13 | 14 | 15 | 16 | 17 | 18 | 19 |
20 | 21 | 22 | 23 | 24 | 25 | 26 |
27 | 28 | 29 | 30 | 31 | 1 | 2 |
3 | 4 | 5 | 6 | 7 | 8 | 9 |
Brian Nguyen travels Nov 25, 2026 to Dec 2, 2026.
Locale
The locale sets the weekday names, the heading, and the first day of the week. Under de-DE the week opens on Monday.
November 2026
| Mo | Di | Mi | Do | Fr | Sa | So |
|---|---|---|---|---|---|---|
26 | 27 | 28 | 29 | 30 | 31 | 1 |
2 | 3 | 4 | 5 | 6 | 7 | 8 |
9 | 10 | 11 | 12 | 13 | 14 | 15 |
16 | 17 | 18 | 19 | 20 | 21 | 22 |
23 | 24 | 25 | 26 | 27 | 28 | 29 |
30 | 1 | 2 | 3 | 4 | 5 | 6 |
Disabled
The whole calendar dims, both month buttons disable, and the grid leaves the tab order.
November 2026
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
1 | 2 | 3 | 4 | 5 | 6 | 7 |
8 | 9 | 10 | 11 | 12 | 13 | 14 |
15 | 16 | 17 | 18 | 19 | 20 | 21 |
22 | 23 | 24 | 25 | 26 | 27 | 28 |
29 | 30 | 1 | 2 | 3 | 4 | 5 |
6 | 7 | 8 | 9 | 10 | 11 | 12 |
Read-only
The grid stays reachable and shows the value, but nothing can change it. Say in the surrounding copy why the date is fixed.
November 2026
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
1 | 2 | 3 | 4 | 5 | 6 | 7 |
8 | 9 | 10 | 11 | 12 | 13 | 14 |
15 | 16 | 17 | 18 | 19 | 20 | 21 |
22 | 23 | 24 | 25 | 26 | 27 | 28 |
29 | 30 | 1 | 2 | 3 | 4 | 5 |
6 | 7 | 8 | 9 | 10 | 11 | 12 |
Guidelines
When to use
- When the calendar is the interface itself: a page or a card where the traveller scans a month to choose a day.
When not to use
- Use Date picker when a date belongs in a form. It adds the label, the typed segments, the error, and the hidden inputs around this grid.
Do and don’t
- DoStrike through the days the traveller cannot pick, and keep them in the grid.The month keeps its shape, so the weekdays still line up, and the traveller sees the day exists but is taken.
- DoShow two months side by side when a trip can cross a month end.Both ends of the trip stay in view. Paging away from the start day to find the end loses the traveller’s place.
- Don’tPut a failure message on the grid.The grid carries no label and no message. A failed date shows on the field or card that hosts the calendar, where the traveller reads the question.
- Don’tFix a date in a read-only calendar without saying why.A grid that ignores presses looks broken. A line beside it turns the refusal into information.
Accessibility
| Key | Description |
|---|---|
| Tab | Reaches the previous button, the next button, and then the grid as one stop, landing on the selected day or today. |
| ArrowLeftArrowRightArrowUpArrowDown | Moves across days and weeks, and pages the grid at a month edge. |
| PageUpPageDown | Moves one month back or forward. |
| Shift+PageUpShift+PageDown | Moves one year back or forward. |
| HomeEnd | Goes to the first or last day of the month. |
| EnterSpace | Selects the focused day. In a range, the first press anchors and the second commits. |
| Escape | Drops an anchored range start without calling onChange. |
Screen readers hear the grid’s name with the visible month, each day with its weekday and its today, selected, or unavailable status, and the range announcements the underlying library provides. Focus is the highlight: a focused day steps one shade deeper on its own tint, with no ring. For the field that wraps this grid, see Date picker.
API
Calendar
mode selects the value shape, and the value and handler types follow it.
| Prop | Type | Default | Description |
|---|---|---|---|
| aria-label | string | Required | The grid’s accessible name. Required, because the grid has no visible label: a screen reader announces it with the visible month. |
| mode | CalendarMode | CalendarMode.Single | Single takes one day. Range takes a pair. |
| value | string | CalendarRange | null | – | The controlled value: an ISO YYYY-MM-DD day, { start, end }, or null. Pass null to clear it: pressing the selected day again keeps it selected, so the grid never empties itself. |
| onChange | (value) => void | – | Reports the selection as ISO YYYY-MM-DD days. In range mode it fires once, on commit, with start never after end. |
| months | 1 | 2 | 1 | How many months show side by side. They page together. |
| locale | string | "en-US" | Sets the weekday names, the heading, and the week start. |
| min, max | string | – | ISO YYYY-MM-DD bounds. Days outside them are struck through, and the month buttons disable at the edge. |
| isDateDisabled | (date: string) => boolean | – | Strikes the days it refuses. |
| disabled | boolean | false | Dims the calendar, disables the month buttons, and leaves the tab order. |
| readOnly | boolean | false | Keeps the grid reachable but unchangeable. |
| autoFocus | boolean | false | Focuses the grid on mount. |
| className | string | – | Styles the calendar root. |