Accessibility

Everything you can do with a pointer in the built-in views, you can also do from the keyboard: move around, open an event, and move, resize, or create one. A screen reader hears each step. Try it here: Tab into the calendar or click a day, then use the keys below. The strip under the calendar shows what a screen reader announces.

KeyboardCopy Anchor Link

Each view is one tab stop. Tab enters it on the day, slot, or event you last focused, or on today, and the keys below move focus inside it. Moving past the visible range navigates the view. Inside a view, arrow, Home, End, and Page keys always belong to the view, so they never trigger your app's own shortcuts, even where there's nowhere to move.

Moving aroundCopy Anchor Link

In the resource columns view, each resource's days come before the next resource's, and inside a column the week and day keys apply.

Shift+Enter opens the view named day; in the resource timeline it expands or collapses a group instead. In the week view it needs the dayView option, and the day view has nothing to open. The table shows left-to-right calendars; with direction="rtl" on Root, ← and → swap so they follow the layout (see Right-to-left).

Changing eventsCopy Anchor Link

With onEventChange on Root, the month, week, day, resource columns, and resource timeline views can change events from the keyboard, just as a drag does. The year view shows events without changing them, so Space there opens a day's events. Moving a picked-up event into another resource's column or row swaps that resource, as dropping it there would.

A saved change goes through your policies and shows as pending like any other. Read-only events say so when you pick them up, and stay where they are. The agenda has no cells to move events to, so it only navigates and opens them.

useCalendarKeyboard({ snap, createDuration }) sets the slot length (the pointer's snap, 15 minutes by default) and how long a slot create starts out (one hour).

AnnouncementsCopy Anchor Link

Keyboard and pointer moves, resizes, and creates are announced through a polite live region. Render Announcer once inside Root, with the messages from the registry:

import { calendarAnnouncements } from "@/components/calendar/announcements";

<Calendar.Root
  defaultAnchorDate={Temporal.PlainDate.from("2026-10-08")}
  defaultTimeZone="Europe/Berlin"
  events={meetings}
  locale="en-US"
  onEventChange={saveMeeting}
  weekRules={{ firstDay: 1, minimalDays: 4, weekend: [6, 7] }}
>
  <Calendar.Announcer messages={calendarAnnouncements} />
  <Calendar.ActiveView />
</Calendar.Root>;

Announcer renders a visually hidden <div role="status" aria-live="polite">. Without it nothing is announced. Picking up Standup and moving it down a slot, for example, reads:

1. "Picked up Standup, Thursday, October 8, 9:30 – 9:45 AM. Use the arrow keys to move it, then Enter to drop it or Escape to cancel."
2. "Thursday, October 8, 9:45 – 10:00 AM"
3. "Moved Standup to Thursday, October 8, 9:45 – 10:00 AM." once onEventChange has saved it.

In a calendar with resources, picking up, moving and creating an event also name the resources it books, from Root's resources: "Moved Standup to Thursday, October 8, 9:45 – 10:00 AM, Orchid." While moving, a step names them only when they change.

Customize and localize themCopy Anchor Link

The packages ship no text. calendarAnnouncements lives in registry/calendar/announcements.ts, in your app once you copy the UI source, so you can edit it in place. To translate it, write a CalendarAnnouncementMessages object of your own, with one builder per phase:

Each builder receives the update and a context, and returns the text to speak or null to stay silent. The update has cause ("move", "resize-start", "resize-end", or "create"), input ("keyboard" or "pointer"), event (null while creating), and the original and proposed placements. The context has locale, timeZone, and formatRange(placement), which formats a placement as the drag preview labels it ("9:30 – 10:00 AM").

import type { CalendarAnnouncementMessages } from "@moltenship/calendar";

const titleOf = ({ event }: { readonly event: { readonly title: string } | null }) =>
  event === null ? "Der neue Termin" : event.title;

export const announcementsDe: CalendarAnnouncementMessages = {
  start: (update) =>
    update.cause === "create"
      ? "Neuer Termin. Mit den Pfeiltasten verlängern, Eingabe zum Speichern."
      : `${titleOf(update)} aufgenommen. Pfeiltasten zum Verschieben, Eingabe zum Ablegen.`,
  step: ({ proposed }, { formatRange }) => (proposed === null ? null : formatRange(proposed)),
  commit: (update, { formatRange }) => `${titleOf(update)}: ${formatRange(update.proposed)}.`,
  reject: (update) =>
    update.reason === "superseded" ? null : `${titleOf(update)} bleibt, wo er war.`,
  cancel: () => "Abgebrochen.",
};

formatRange follows the calendar's locale. To change how ranges read, add an optional formatRange(placement, { locale, timeZone }) to your messages; the default is formatPlacementRange. It labels the drag preview and becomes the context's formatRange, so it changes spoken ranges only in builders that call that helper, as the German example does. calendarAnnouncements spells dates out with describeWhen from event-label.ts instead; edit that to change how its announcements read.

Pointer gesturesCopy Anchor Link

The built-in views pass the same announcer to the pointer layer, so drags are announced by the same messages and the drag preview labels ranges with the same formatRange. In your own views, do the same:

const announcer = useCalendarAnnouncer();
const pointerRef = useCalendarPointer({ announcer, events, onPropose, timeZone });

Event namesCopy Anchor Link

Every event is a <button> named in full: "Standup, Thursday, October 8, 9:30 – 9:45 AM, Work calendar, saving". The name leads with the title, then says when, where (the resource, in the resource columns view), an optional detail, and whether a change is still saving. useEventLabel builds it in registry/calendar/event-label.ts, where the English words live, so edit or translate them there. Pass describeEvent: (event) => string to a view to add the detail, such as the calendar's name.

ARIA patternsCopy Anchor Link

All views share these:

• One tab stop with a roving tabIndex: only the focused day, slot, or event has tabIndex={0}. The header's "Open date" buttons and the all-day row's expand toggle are out of the tab order; Shift+Enter and focusing a hidden event do their job.
• Today is marked aria-current="date".
• Events are <button>s with the full names above. Events with a pending change have aria-busy.
• Focus shows as a solid 2px outline-ring outline, which stays visible in forced-colors mode. A focused event rises above its neighbours.

The mini month in registry/calendar is a separate grid of date buttons: arrow keys move by a day or a week, and Page Up and Page Down by a month.

Checked in CICopy Anchor Link

vp run a11y runs axe-core in Chromium over every built-in view, the toolbar and mini month, and the demo's main screens, in light and dark, and fails on any serious or critical WCAG 2.2 A/AA violation. It exempts three rules, each only on specific elements:

• Label in name, for events and day cells: a chip shows an abbreviated subset of its name ("9:30 AM Standup"), and a day cell is named by its date and event count because its events are focused separately. Event names lead with the title, so speech input still matches it.
• Target size, inside the month and time grids, where an event's box is its time span (WCAG 2.5.8's "essential" exception).
• Hidden focusable elements, for Base UI's focus guards, which pass focus straight on.

A separate test checks the theme against WCAG AA in both color schemes: event text on every event color, the today marker, the now line, and the focus ring. If you override --ring, keep it at 3:1 or more against your background, even at 50% opacity. shadcn's default light ring is about 1.5:1 at 50%.

Reduced motionCopy Anchor Link

When the system asks for reduced motion (prefers-reduced-motion: reduce), the calendar theme:

• fades popovers, dialogs, and tooltips in and out without zooming or sliding;
• fades sheets without sliding them in;
• keeps transitions off the drag preview;
• crossfades view transitions in place instead of moving them.

The rules live in calendar-theme.css, because the registry views use shadcn's own popover, select, and tooltip, which you install from shadcn.

Right-to-leftCopy Anchor Link

Right-to-left takes two settings: dir="rtl" on an ancestor of the calendar, such as <html>, for the layout, and direction="rtl" on Root for the keys. Root doesn't read the page's dir, so set both:

<html dir="rtl" lang="ar">
  <body>
    <Calendar.Root {...rootProps} direction="rtl" locale="ar">
      <Calendar.ActiveView />
    </Calendar.Root>
  </body>
</html>

The month, week, day, and agenda views then mirror: days run from right to left, the hour gutter moves to the right, events put their accent edge on the right, continuation chevrons point the way the event continues, and the toolbar's arrows turn around. ← and → follow the layout, so ← moves to the next day, which an RTL grid shows on the left, and a picked-up event moves the same way. The views use logical CSS properties throughout (ms-*, border-s, start-*), so your own edits should too.

In your own viewsCopy Anchor Link

Custom views get the same keyboard support from three pieces:

• getSpatialNavigation on the view's strategy says where each key moves focus. Reuse monthSpatialNavigation, yearSpatialNavigation, timeGridSpatialNavigation, or listSpatialNavigation, or write your own.
• useCalendarKeyboard(options) returns onKeyDown and onBlur handlers. Spread them on the element around the view.
• useRovingFocus(focus) returns the props for one focusable day ({ kind: "day", date }), slot, or event ({ kind: "event", date, eventId }), including its tabIndex.

useCalendarInteraction() returns the keyboard gesture in progress, for drawing a create's draft or tinting the cells it covers.