Skip to content
flyingsalmon

Calendar

A month grid the traveller picks one day or a range from.

Departure, November 2026

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

Installation

npx shadcn@latest add @flyingsalmon/calendar

Usage

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.

Trip dates, November to December 2026

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
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

Brian Nguyen travels Nov 25, 2026 to Dec 2, 2026.

Unavailable days

isDateDisabled receives each day as an ISO string and strikes the ones it refuses. They stay reachable by arrow key but cannot be selected. Weekends are struck here.

Weekday departure, November 2026

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

Locale

The locale sets the weekday names, the heading, and the first day of the week. Under de-DE the week opens on Monday.

Abreise, November 2026

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

Disabled

The whole calendar dims, both month buttons disable, and the grid leaves the tab order.

Departure, November 2026

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

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.

Booked departure, November 2026

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

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

  • Do
    Strike 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.
  • Do
    Show 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’t
    Put 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’t
    Fix 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

KeyDescription
TabReaches the previous button, the next button, and then the grid as one stop, landing on the selected day or today.
ArrowLeftArrowRightArrowUpArrowDownMoves across days and weeks, and pages the grid at a month edge.
PageUpPageDownMoves one month back or forward.
Shift+PageUpShift+PageDownMoves one year back or forward.
HomeEndGoes to the first or last day of the month.
EnterSpaceSelects the focused day. In a range, the first press anchors and the second commits.
EscapeDrops 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.

PropTypeDefaultDescription
aria-labelstringRequiredThe grid’s accessible name. Required, because the grid has no visible label: a screen reader announces it with the visible month.
modeCalendarModeCalendarMode.SingleSingle takes one day. Range takes a pair.
valuestring | 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.
months1 | 21How many months show side by side. They page together.
localestring"en-US"Sets the weekday names, the heading, and the week start.
min, maxstring–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.
disabledbooleanfalseDims the calendar, disables the month buttons, and leaves the tab order.
readOnlybooleanfalseKeeps the grid reachable but unchangeable.
autoFocusbooleanfalseFocuses the grid on mount.
classNamestring–Styles the calendar root.

  • Date picker

    The form field that hosts this grid in a floating panel.
  • Accessibility

    How the registry measures contrast and handles focus.
  • Motion

    The spring presets and durations behind the paging.