Calendar
Calendar views that display data on a date grid — mini calendars, week strips, event calendars, heatmaps. Built on the headless calendar-core utilities: they own the date math and navigation state, rendering is entirely yours. For picking dates in forms, see Date Picker.
Examples
Mini calendar
Week strip
Events calendar
Month heatmap
Overview
@rogo-technologies/ui/calendar-core is the low-level foundation for custom calendar views. Grid metadata (key, isToday, isOutsideMonth, isWeekend) is designed for joining per-day data to cells — an events map, usage counts, activity flags — via the ISO day.key.
import {
getCalendarWeeks,
getWeekDays,
getWeekdayLabels,
useCalendarMonth,
} from "@rogo-technologies/ui/calendar-core";Usage
Month views
useCalendarMonth provides navigation state plus the visible month's week rows. Join your data by day.key and render whatever the cell needs.
const { month, weeks, goToPreviousMonth, goToNextMonth } = useCalendarMonth({
fixedWeeks: true,
});
<div className="grid grid-cols-7">
{weeks.flatMap((week) =>
week.days.map((day) => <MyDayCell key={day.key} day={day} data={dataByDay[day.key]} />)
)}
</div>;Week strips
getWeekDays is the row primitive — seven annotated days from any start date. Manage the visible week yourself with plain state.
const [weekStart, setWeekStart] = useState(() => startOfWeek(new Date(), { weekStartsOn: 1 }));
const days = getWeekDays(weekStart);Weekday headers
getWeekdayLabels returns localized column headers ordered to match the grid. Pass an explicit locale when the view is server-rendered so markup is identical on both sides.
const weekdays = getWeekdayLabels({ locale: "en-US", format: "short" });API
Grid utilities
| Export | Description |
|---|---|
getCalendarWeeks(month, options?) | Week rows covering a month; each CalendarDay carries key, isToday, isOutsideMonth, isWeekend. |
getWeekDays(weekStart, options?) | A single seven-day row — the primitive for week-strip views. |
getWeekdayLabels(options?) | Localized column headers via Intl, ordered to match the grid. |
toDayKey(date) | ISO yyyy-MM-dd key — use it to join per-day data to cells. |
Weeks start on Monday by default (weekStartsOn: 1), matching Rogo product surfaces. Pass weekStartsOn: 0 for Sunday grids.
useCalendarMonth
Month navigation + grid state. Works uncontrolled (defaultMonth) or controlled (month + onMonthChange), clamps the visible month and navigation to minMonth / maxMonth.
| Option | Type | Default | Description |
|---|---|---|---|
month | Date | — | Controlled visible month. |
defaultMonth | Date | today | Initial month when uncontrolled. |
onMonthChange | (month: Date) => void | — | Fires on navigation (with the clamped month). |
minMonth / maxMonth | Date | — | Inclusive navigation bounds. |
weekStartsOn | 0–6 | 1 (Monday) | First day of week rows. |
fixedWeeks | boolean | false | Always six rows, so grid height never jumps. |
Returns { month, weeks, goToMonth, goToPreviousMonth, goToNextMonth, goToToday, canGoToPreviousMonth, canGoToNextMonth }.
Guidelines
Do
- Build data-dense inline calendar views (heatmaps, event grids) on
calendar-coreand join data viaday.key - Use
fixedWeeksfor inline month views so the layout doesn't jump between five- and six-week months - Pass a fixed
todayand explicitlocalein server-rendered views so prerendered markup matches the client
Don't
- Don't hand-roll month/week grid math in feature code — use
getCalendarWeeks/getWeekDays - Don't rebuild date selection on top of
calendar-core— use Date Picker for forms - Don't derive React keys from array indexes in date grids —
day.keyis stable across navigation