useCalendarNavigation
Keyboard navigation for a calendar grid, driven by the focused date so it crosses months, years and dual calendars.
Overview
useCalendarNavigation handles the keyboard inside a calendar grid, following the WAI-ARIA date picker dialog pattern. Navigation is driven by the focused date rather than a grid index, so it works the same for months of different lengths, two calendars side by side and moves that cross into another month.
It is built for DatePicker: the calendar inside DatePickerDropdown uses it. Use it directly only when you build a custom calendar, for example a booking grid or a different month layout, and want the same keyboard behaviour.
Import
import { useCalendarNavigation } from '@unflowio/ui/hooks/useCalendarNavigation';Parameters
| Param | Type | Default | Description |
|---|---|---|---|
initialDate | Date | null | today | Date focus starts on, e.g. the selected value |
ensureVisible | (date: Date) => void | — | Called before focus moves to a date. Change the displayed month(s) here so the date is rendered when the hook focuses it |
weekStartsOn | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 1 (Monday) | First day of the week for Home/End. 0 is Sunday |
The generic T (e.g. useCalendarNavigation<HTMLDivElement>) types the container element.
Return value
| Field | Type | Description |
|---|---|---|
focusedDate | Date | The date holding the roving tabindex, at the start of the day |
setFocusedDate | (date: Date) => void | Updates the focused date without moving DOM focus, e.g. after a click or when the month buttons change the view |
containerProps | { ref, onKeyDown } | Spread on the element that wraps the calendar grid(s) |
Finding the day cells
After a keyboard move, the hook focuses the element inside the container with a matching data-date attribute in yyyy-MM-dd format. Render each day as a <button> with that attribute, and give only the focused date tabIndex={0}:
<button data-date={format(day, 'yyyy-MM-dd')} tabIndex={isSameDay(day, focusedDate) ? 0 : -1}>
{day.getDate()}
</button>Usage
import { addMonths, eachDayOfInterval, endOfMonth, format, isSameDay, isSameMonth, startOfMonth } from 'date-fns';
import { useState } from 'react';
import { useCalendarNavigation } from '@unflowio/ui/hooks/useCalendarNavigation';
export function MonthGrid({ value, onChange }: { value: Date | null; onChange: (date: Date) => void }) {
const [month, setMonth] = useState(() => startOfMonth(value ?? new Date()));
const { focusedDate, setFocusedDate, containerProps } = useCalendarNavigation<HTMLDivElement>({
initialDate: value,
ensureVisible: (date) => {
if (!isSameMonth(date, month)) {
setMonth(startOfMonth(date));
}
},
});
const days = eachDayOfInterval({ start: month, end: endOfMonth(month) });
return (
<div role="group" aria-label={format(month, 'MMMM yyyy')} {...containerProps}>
<button onClick={() => setMonth(addMonths(month, -1))}>Previous month</button>
<button onClick={() => setMonth(addMonths(month, 1))}>Next month</button>
<div className="grid grid-cols-7">
{days.map((day) => (
<button
key={day.toISOString()}
data-date={format(day, 'yyyy-MM-dd')}
tabIndex={isSameDay(day, focusedDate) ? 0 : -1}
aria-pressed={!!value && isSameDay(day, value)}
onClick={() => {
setFocusedDate(day);
onChange(day);
}}
>
{day.getDate()}
</button>
))}
</div>
</div>
);
}Keyboard behavior
| Key | Behavior |
|---|---|
ArrowLeft / ArrowRight | Previous / next day, crossing into the adjacent month |
ArrowUp / ArrowDown | Same weekday in the previous / next week |
Home / End | First / last day of the focused week (weekStartsOn) |
PageUp / PageDown | Same day in the previous / next month |
Shift + PageUp / PageDown | Same day in the previous / next year |
Enter / Space | Left to each day's <button> |
Tab | Not handled, so focus leaves the grid |
Accessibility
- Only the focused date is in the tab order, so the calendar is a single tab stop.
- Selection is up to you: the hook only moves focus. Mark the selected day (e.g.
aria-pressedoraria-selectedin a grid) and give each day an accessible name that includes the full date if the visible label is just the day number. - Days outside the allowed range should stay focusable but disabled with
aria-disabled, so keyboard users can move past them.