v1.2.1 — Customization API, timezone & interaction fixes

A big one. This release rolls up 1.2.0 (the customization API) and 1.2.1 (bug fixes + allDayMaxRows), since 1.2.0 was never cut as its own GitHub release. Upgrading from v1.1.0 gets you everything below.

Every new prop is optional. With none of them set, the rendered markup and classes are unchanged from 1.1.0 — except where 1.2.1 fixed output that was previously wrong.

---

✨ Customization API (1.2.0)

Event renderers

• renderEvent, renderMonthEvent, renderAgendaEvent — each receives (event, { view, selected, badgeVariant, defaultContent }), so you can wrap or fully replace a chip and still fall back to the stock markup.

Header control

• hideHeader and headerSlot — bring your own toolbar.

Controlled selection

• selectedEventId + onSelectedEventChange. The library holds no selection state.
• Selected chips get a data-selected attribute.
• A selected chip rendered by a custom renderer switches from height to minHeight (plus z-10) so it can expand in place.

Sizing

• hourHeight (default 96), height, and autoHeight for the week/day grids.

Month density

• maxEventsPerDayCell (default 3) and onShowMore(date), which turns the "+N more" label into a real button.

Styling hooks

• classNames — root, header, dayCell, hourRow, eventBlock, timeline.
• dayCellClassName(date).

Open color system

• TEventColor is now TLegacyEventColor | (string & {}). The seven built-in names keep their Tailwind class maps; any other CSS color renders with the .bc-event-custom-color class and an inline --bc-event-color variable.

Event metadata

• IEvent<TMeta> gains an optional meta payload, carried through untouched.

New exports

• CalendarCustomizationContext, useCalendarCustomization, isLegacyColor, LEGACY_EVENT_COLORS, DEFAULT_CUSTOMIZATION
• Types: TEventRenderer, TEventRenderView, IEventRenderContext, ICalendarClassNames, ICalendarCustomization, TLegacyEventColor

Tests

• Test suite added (vitest + @testing-library/react + jsdom): npm run test.

Changed

• calculateMonthEventPositions and useEventPositioning take an optional trailing maxVisible argument (default 3) — existing calls are unaffected.

---

🐛 Fixes (1.2.1)

• Agenda day headings were off by one day in western timezones. Headings were built with new Date('yyyy-MM-dd'), which parses as UTC and rendered the previous day everywhere west of Greenwich. Now uses parseISO. This also fixes agenda groups appearing to spill into the neighbouring month.
• Stale current-time line. The timeline no longer renders on a week that doesn't contain today, or on a day view showing anything other than today.
• Month view events were unclickable below lg. At small breakpoints the month view renders event bullets, which had no click handler — events were unreachable. Bullets now carry the same role="button" / data-event-id wiring as badges and fire the details handler on click or Enter/Space. They additionally carry data-event-bullet so [data-event-id] queries can exclude them.
• Agenda heading casing. Switched to first-letter:uppercase instead of capitalize, which was uppercasing every word of a long date.
• Week all-day strip position. The strip now renders below the day-name header row (previously above it), and the header row is sticky.

➕ Added (1.2.1)

• allDayMaxRows — caps the week all-day strip at N badge rows; beyond that the strip scrolls internally instead of pushing the grid down. Leave it unset to keep the uncapped behaviour.
• The all-day strip gains a leading gutter label, driven by the existing allDay label key.

---

Install

npm install big-calendar-react@1.2.1

Full changelog: v1.1.0...v1.2.1

v1.1.0 — Locale-aware date & time formatting

Locale-aware date & time formatting

dateLocale is now the single option controlling how every date and time is rendered. The calendar
pulls the format patterns themselves from the date-fns locale (formatLong, i.e. CLDR data), so
passing a locale changes field order and clock convention — not just the translated words.

import { frCA } from 'date-fns/locale/fr-CA'

<BigCalendar view={view} onViewChange={setView} dateLocale={frCA} />

Surface	no locale	enUS	frCA	ja
Header range, details dialog, day-view "today" chip	Dec 1, 2026	Dec 1, 2026	1 déc. 2026	2026/12/01
Agenda day heading	Tuesday, December 1, 2026	Tuesday, December 1st, 2026	mardi 1 décembre 2026	2026年12月1日火曜日
Event times (week/month/agenda/day)	2:30 PM	2:30 PM	14:30	14:30
Day & week hour axis	02 PM	02 PM	14	14
Date + time rows in the details dialog	Dec 1, 2026 2:30 PM	Dec 1, 2026, 2:30 PM	1 déc. 2026, 14:30	2026/12/01 14:30

What changed

• New src/calendar/date-format.ts — locale-derived pattern helpers (datePattern,
  longDatePattern, timePattern, hourPattern, dateTimePattern, is24HourLocale) and their
  formatDate / formatLongDate / formatTime / formatHour / formatDateTime wrappers.
• Hour axis follows the locale's clock — a 24-hour locale labels it 14, a 12-hour locale
  02 PM, so the day/week axis always agrees with the event times printed beside it.
• Views updated to format through the locale — month (MonthEventBadge), week
  (EventBlock, CalendarTimeline, CalendarWeekView), day (CalendarDayView) and agenda
  (AgendaDayGroup, AgendaEventCard).
• Dialogs updated — AddEventDialog, EditEventDialog and EventDetailsDialog render dates
  and times in the active locale; the time fields drop the AM/PM control for a 24-hour locale.
• SingleDayPicker — the trigger label and popover are localized.
• README — new "Date & time formatting" section documenting the behavior, the comparison table
  above, and the known limitation below.

Notes

• Known limitation: the week grid always starts on Sunday. dateLocale does not yet move it, so
  locales that start the week on Monday (de, en-GB) or Saturday (ar) still get a Sunday-first
  grid. The month view's weekday header is a fixed Sun–Sat list, and moving one view without the
  other would leave the calendar disagreeing with itself.
• Omitting dateLocale is not the same as passing enUS. With no locale the calendar uses its
  built-in US-English patterns — hence the two English columns differing on the agenda heading (no
  ordinal) and the date+time row (no comma). Pass enUS explicitly for true CLDR US-English output.
• Passing a locale is required for correct non-English output: labels translates the calendar's
  own strings (buttons, headings), while dateLocale governs everything date-fns renders.

Full changelog: v1.0.1...v1.1.0

v1.0.1

• Widen react-day-picker peer dependency to ^9.0.0 || ^10.0.0 — verified against 10.0.1 (typecheck + lib build clean); keeps stricter package managers quiet when the host app runs rdp 10.
• Add prepare script so dist/ builds automatically when installing the package directly from git.

v1.0.0 — Initial release

big-calendar-react 1.0.0

Initial release — a 1:1 feature-parity React 19 port of big-calendar-vue3, designed for Laravel Inertia v3 React (framework-agnostic, no router coupling).

Features

• 5 views: day / week / month / year / agenda
• Event CRUD dialogs (add / edit / details) with zod validation
• User filtering, dark mode, working & visible hours, badge variants
• ~110-key i18n label system with dateLocale support (date-fns locales)
• Right-click command menus with per-view scoping
• Events-only integration mode (navigateOnDayClick / openDetailsOnEventClick)
• bc-* CSS hooks and data-view / data-date / data-event-id attributes for external targeting

Stack

React 19 (ref-as-prop, memo'd hot paths) · shadcn/ui on Base UI · Zustand · react-hook-form + zod · Tailwind CSS v4 · date-fns · react-day-picker v9

Attribution

Original design by lramos33/big-calendar (MIT). Vue 3 port: big-calendar-vue3.