Usage
Manages visible month state and pagination for calendar components. It provides previous/next month stepping, localized month-year header strings, and pending focus tracking so keyboard arrow navigation seamlessly moves focus across month boundaries into the adjacent month. Use it directly when composing custom calendar headers, pager controls, or dual-month availability pickers.
ts
Best practices
| Guidance | Practices |
|---|---|
| Do | Wire navigateMonth(-1) and navigateMonth(1) to Previous/Next icon buttons to paginate months. |
| Do | Pass focusedDate and offset (e.g. 1 for horizontal arrow keys, 7 for vertical arrow keys) to navigateMonth so pendingFocus directs keyboard focus to the correct day cell after the month transition. |
| Don't | Hardcode month-year header strings manually; use monthYearLabel which automatically formats according to the active locale and calendar system. |
Parameters
| Param | Type | Description |
|---|---|---|
optionsrequired | Configuration for visible month, calendar system, and navigation callbacks. | |
options.initialValue | Initial ISO date string (YYYY-MM-DD) used to determine the starting focus month when uncontrolled. | |
options.focusDate | Controlled ISO date string (YYYY-MM-DD) determining which month is currently displayed. Used with onFocusDateChange as a controlled pair. | |
options.onFocusDateChange | (focusDate: ) => void | Callback invoked when user navigation changes the visible focus month. Used with focusDate as a controlled pair. |
options.numberOfMonths | 1 | 2 (default: 1) | Number of consecutive months to display simultaneously (1 or 2). Default is 1. |
options.calendar | (default: 'gregory') | Calendar system whose months the hook steps and formats (e.g. 'gregory', 'persian', 'hebrew'). Calendars other than gregory, iso8601, buddhist, roc and japanese need Temporal. The provider's calendar is never read. Default is 'gregory'. |
Returns
| Field | Type | Description |
|---|---|---|
| baseMonth | The Gregorian first day of the primary focus month. | |
| visibleMonths | [] | Array of Gregorian first-day PlainDate objects for each currently visible month. |
| visibleCalendarMonths | {year: number; month: number}[] | Array of year and month pairs for each visible month in the active calendar system, compatible with useCalendarDays options. |
| monthYearLabel | string | Formatted localized header label for the visible month or range of months (e.g. "June 2026"). |
| navigateMonth | (delta: number, focusedDate?: , offset?: number) => void | Steps the visible month forward (+1) or backward (-1). When focusedDate is passed, computes pendingFocus on the target date across the month boundary using offset (defaults to 7). |
| pendingFocus | | null | Target ISO date to focus following a month navigation step, or null when no cross-month keyboard focus is pending. |
| clearPendingFocus | () => void | Clears pendingFocus once the target day cell has received keyboard focus. |
Examples
Common configurations, variations, and states.Use with shadcn
Already using the shadcn registry workflow? Install the real Astryx package and a local public re-export. Component implementation source stays in Astryx.
This install URL expires with the draft preview.bash