Calendar

Examples

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

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.

Returns { month, weeks, goToMonth, goToPreviousMonth, goToNextMonth, goToToday, canGoToPreviousMonth, canGoToNextMonth }.

Guidelines

Do

• Build data-dense inline calendar views (heatmaps, event grids) on calendar-core and join data via day.key
• Use fixedWeeks for inline month views so the layout doesn't jump between five- and six-week months
• Pass a fixed today and explicit locale in 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, since day.key is stable across navigation