Calendar

Pick a date or a range from a month that stays on screen.

import { Calendar } from "macbetter/calendar"

export default function Example() {
  return <Calendar aria-label="Delivery date" defaultValue="2026-11-20" />
}

When to use it

Use a calendar when the month itself helps: choosing a delivery day, seeing which days are free, picking a reporting period. It stays on the page; for a field that opens a calendar only when asked, use a Date Picker.

Today is marked in accent text. The chosen day fills with the accent. Days that can't be picked are dimmed, and stay focusable so keyboard users hear why.

Usage

import { Calendar } from "macbetter/calendar"

Values are ISO strings like "2026-11-20". With no children, Calendar draws its header and a grid for each month. To change one part, write the parts out: CalendarHeader, CalendarHeading, CalendarPrevious, CalendarNext and CalendarGrid, which draws its own weekday row and days.

Ranges and two months

mode="range" picks a start and an end. Moving the pointer previews the range, and the days between the two circles join into one continuous band that rounds off where a week wraps. months={2} shows two months side by side.

import { Calendar } from "macbetter/calendar"

export default function Example() {
  return (
    <Calendar
      aria-label="Report period"
      mode="range"
      months={2}
      defaultValue={["2026-11-09", "2026-11-19"]}
    />
  )
}

Compact

size="sm" is the dense month of a macOS popover or sidebar, with single-letter weekdays. unavailable takes dates, ranges, weekdays or a function.

import { Calendar } from "macbetter/calendar"

export default function Example() {
  return <Calendar size="sm" aria-label="Go to date" defaultValue="2026-11-18" unavailable={{ weekday: [0, 6] }} />
}

Platform behavior

• macOS. 13-point days in 26-point circles, a 13-point semibold month title, and small gray chevrons that highlight under the pointer.
• iPadOS and iOS. 20-point days in 40-point circles, a 17-point semibold title, uppercase weekday abbreviations, and accent chevrons with 44-point touch targets, as in the iOS graphical date picker.
• Every platform. Pressing a day gives a small, instant squeeze. Days from neighboring months are hidden unless you pass showOutsideDays.

Accessibility

• The month is a grid named by its title, and the title is announced as it changes.
• Arrow keys move by day and week, Home and End to the week's ends, Page Up and Page Down by month. Enter or Space picks the focused day; Escape cancels an unfinished range.
• Previous and Next are named "Previous month" and "Next month"; pass aria-label in another language.

API

Calendar

CalendarHeader takes the props of a div. CalendarGrid takes an offset for the month it shows. CalendarDay draws its number in a circle unless it has children.

Data attributes

CSS variables