Calendar

When to useLink to "When to use"

• Choosing a day where seeing the month helps (a booking, a due date).
• A month view of plans or events: renderDay puts your content in each day, markDay tints days and adds dots.

Use something else when:

• the date goes into a form field: DateField, which types or picks
• people pick a time of day: TimeField

UsageLink to "Usage"

import { Calendar } from "@arshad-shah/cynosure";

<Calendar value={date} onChange={setDate} min="2026-01-01" isDateDisabled={isFullyBooked} />

Dates are YYYY-MM-DD strings: no time and no time zone. Month and day names come from Intl in the locale you give (the browser's by default), and the week starts where that locale starts it.

Limits and unavailable daysLink to "Limits and unavailable days"

min and max stop focus and the month buttons. isDateDisabled marks days that can be focused (so people can hear about them) but not chosen.

A month of plansLink to "A month of plans"

renderDay(date, state) adds your content under each day's number; the grid then fills its container. onMonthChange tells you which month to load.

With renderDay a day is at least --cy-calendar-content-size tall: 2.5 times the cell size by default, and 66px on touch screens (1.5 times the 44px target), so a six-week month is under 520px tall in a 390px-wide container. Set the token for taller or shorter days; a day never drops below the touch target.

Marked daysLink to "Marked days"

markDay(date, state) marks a day without drawing it. Return any of:

• tone: tints the day softly with that tone. Days of other months are not tinted; the selected day keeps its fill and today its ring.
• dots: one small dot per entry under the number, each a tone or any CSS colour. Three at most are drawn; further entries are dropped, so put the count in label.
• label: words added to the day's name after its date, so the marks are not colour alone.

state is { selected, today, outside, disabled, weekend }. weekend follows the locale where the browser knows its weekend, and is Saturday and Sunday otherwise.

<Calendar
  markDay={(date, day) => ({
    tone: day.weekend ? "neutral" : undefined,
    dots: tasks[date]?.map((task) => task.colour),
    label: tasks[date] ? `${tasks[date].length} tasks` : undefined,
  })}
/>

The month shownLink to "The month shown"

Left alone, the calendar starts on defaultMonth (or the month of the value or focused date), moves itself, and follows a new value to its month.

Pass month (YYYY-MM, or any YYYY-MM-DD date of that month) to own it. Every way of leaving the month then calls onMonthChange with the first day of the month asked for, and the grid waits for the new month. If you do not move, focus stays on the day it was on. A new value in another month does not move a controlled month: set month too.

const [month, setMonth] = useState("2026-11");

<Calendar month={month} onMonthChange={setMonth} />

Jumping to a month and yearLink to "Jumping to a month and year"

monthPicker turns the heading into a button that opens a panel: a year to step through and its twelve months. Months and years outside min and max are disabled. It is off by default.

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

• Roles: a grid named by the month title, column headers with the full day name as abbr, and one Tab stop on the focused day.
• Names: each day reads as its full date, then any markDay label, then any renderDay content; today is aria-current="date"; unavailable days are aria-disabled.
• Announcements: the month title is a polite live region.
• Focus: the focused day is always a day of the month shown. When the month changes it is the same day number there (or the month's last day), kept within min and max where the month has such a day.
• Month picker: the heading button is named by the month and "Choose month and year" and opens a dialog. Focus moves into it; TabTab moves through the year buttons and the months, EnterEnter or SpaceSpace chooses a month, closes the panel and puts focus back on the heading. EscapeEscape closes it and changes nothing. The month shown is aria-current.
• Forced colours: a tinted day has a dashed outline and dots take the text colour.
• Labels: labels replaces previous, next, monthPicker, previousYear and nextYear.

TouchLink to "Touch"

Days are at least 44px on touch screens, also with renderDay: a grid in a container narrower than seven targets scrolls. Tap a day to choose it; the month buttons and the month picker's buttons have the same hit area.

ThemingLink to "Theming"

The selected day uses the accent and its on-accent text colour.

RelatedLink to "Related"

DateField · TimeField · Popover