UnflowUI
ComponentsHooks

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

ParamTypeDefaultDescription
initialDateDate | nulltodayDate 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
weekStartsOn0 | 1 | 2 | 3 | 4 | 5 | 61 (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

FieldTypeDescription
focusedDateDateThe date holding the roving tabindex, at the start of the day
setFocusedDate(date: Date) => voidUpdates 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

KeyBehavior
ArrowLeft / ArrowRightPrevious / next day, crossing into the adjacent month
ArrowUp / ArrowDownSame weekday in the previous / next week
Home / EndFirst / last day of the focused week (weekStartsOn)
PageUp / PageDownSame day in the previous / next month
Shift + PageUp / PageDownSame day in the previous / next year
Enter / SpaceLeft to each day's <button>
TabNot 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-pressed or aria-selected in 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.