Usage
Builds the day grid for one month: every date to show, including the previous and next months' days that fill the first and last weeks, grouped into weeks, plus localized weekday header names that start on weekStartsOn. It is the layout Calendar uses, for a custom month view such as a compact availability grid or a mini calendar. It returns data only: rendering, selection, keyboard navigation and the grid's accessibility semantics are the caller's.
ts
Best practices
| Guidance | Practices |
|---|---|
| Do | Render dayNames as the header row so the header follows weekStartsOn and the locale together with the grid. |
| Do | Style days with isOutside differently, for example dimmed, so the filler days read as part of the next or previous month. |
| Don't | Use it to build a date picker that people choose from; use Calendar, which adds selection, keyboard navigation and grid semantics. |
Parameters
| Param | Type | Description |
|---|---|---|
optionsrequired | The month to lay out and how. | |
options.yearrequired | number | Year of the month to lay out, as options.calendar numbers it. |
options.monthrequired | number | The month's position in its year under options.calendar, 1-based. In the Gregorian calendar 1 is January and 12 is December; other calendars number months as Temporal.PlainDate does, so a Hebrew leap year runs from 1 to 13. |
options.weekStartsOn | (default: 0) | First day of the week, from 0 (Sunday) to 6 (Saturday). It sets the first column of both the grid and dayNames. |
options.hasVariableRowCount | boolean (default: false) | Use only as many week rows as the month needs instead of a fixed 6-row grid. That is 4 to 6 for a Gregorian month, and 1 or 2 for the short thirteenth month of the Coptic and Ethiopic calendars. |
options.calendar | (default: 'gregory') | The calendar system that numbers year, month and each day's dayNumber. Every day keeps its Gregorian date and iso. The hook never reads the InternationalizationProvider calendar. Calendars other than gregory, iso8601, buddhist, roc and japanese need Temporal; without it the hook uses Gregorian numbers and warns once in development. |
Returns
| Field | Type | Description |
|---|---|---|
| days | [] | Every cell of the grid in order, including the days from the previous and next months that fill the first and last weeks. Each day has date (a PlainDate), iso (YYYY-MM-DD), isOutside (true for a day outside the month) and dayNumber (its day of the calendar month). |
| weeks | [][] | The same days grouped into rows of seven. |
| dayNames | string[] | Weekday header names for the current locale (from InternationalizationProvider), starting at weekStartsOn. Abbreviated where every name fits the column, otherwise the locale's narrow names. |
| totalCells | number | Number of cells in the grid: 42 for the fixed grid, otherwise rows times seven. |
Examples
Common configurations, variations, and states.A compact custom month view: a seven-column table built from the weeks and dayNames that useCalendarDays returns, with only as many rows as the month needs. Days from the previous and next months are dimmed, and a Week starts on control (Sunday or Monday) reorders both the header and the grid.
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