RegistryInstall CalendarCN with the shadcn CLI

Guides

Loading Events

Fetch events for the dates on screen as people navigate, and show a loading bar while they arrive.

The calendar doesn't fetch anything itself. onVisibleRangeChange tells you which dates are on screen, every time they change, so you can load the events for them. While you do, loading draws a thin bar under the day headers. In the preview, a pretend server answers after 800ms. Navigate, switch views or scroll sideways, and watch the log: a range seen before comes from the cache, with no bar.

Usage

Keep the events in state, fetch them in onVisibleRangeChange, and pass loading while a request is in flight:

import { CalendarProvider } from "@/components/calendar-provider";
import { WeekView } from "@/components/week-view";
import type { CalendarEvent, VisibleRange } from "@/components/calendar-types";

export function Schedule() {
  const [events, setEvents] = React.useState<CalendarEvent[]>([]);
  const [loading, setLoading] = React.useState(false);
  const latestRequest = React.useRef(0);

  const loadRange = React.useCallback(async (range: VisibleRange) => {
    const request = ++latestRequest.current;
    setLoading(true);
    const next = await getEvents(range.start, range.end); // your API
    // People may have moved on while this was loading
    if (request !== latestRequest.current) return;
    setEvents(next);
    setLoading(false);
  }, []);

  return (
    <CalendarProvider
      events={events}
      onEventsChange={setEvents}
      onVisibleRangeChange={loadRange}
      loading={loading}
    >
      <WeekView />
    </CalendarProvider>
  );
}

With a data library such as TanStack Query, keep the range in state, use it as the query key, and pass isFetching as loading. Save drags, resizes and edits in onEventUpdate, and update the query's cache so they stick.

const [range, setRange] = React.useState<VisibleRange | null>(null);
const { data: events = [], isFetching } = useQuery({
  queryKey: ["events", range?.start.toISOString(), range?.end.toISOString()],
  queryFn: range ? () => getEvents(range.start, range.end) : skipToken,
  placeholderData: keepPreviousData,
});

<CalendarProvider
  events={events}
  onVisibleRangeChange={setRange}
  onEventUpdate={saveEvent}
  loading={isFetching}
>
  <WeekView />
</CalendarProvider>;

The Calendar block takes every CalendarProvider prop and passes it through, so onVisibleRangeChange and loading work on it the same way:

<Calendar
  events={events}
  onEventsChange={setEvents}
  onVisibleRangeChange={loadRange}
  loading={loading}
/>

The range

start is midnight at the beginning of the first visible day, and end is midnight after the last one, so end is exclusive. Both are in the viewer's time zone. With timeZone on the provider, they are the instants those midnights fall on in that zone.

ViewRangeExample, week of Thursday Jun 4 2026
DayThe day on screenJun 4 → Jun 5
WeeknumberOfDays days from the first column, 7 by defaultMay 31 → Jun 7
MonthThe whole six-week grid, days from the months before and after includedMay 31 → Jul 12
AgendaThe 30 days it lists, from its first dayJun 4 → Jul 4
YearThe whole year, January 1 to the next January 1Jan 1 2026 → Jan 1 2027

When weekends are hidden, day and week view report the weekdays they draw: a week runs from Monday to Friday, so the range ends on Saturday's midnight. Month view's range starts and ends on the first and last weekday it shows. The agenda's range keeps its weekend days; it only leaves them out of its list.

An event belongs in the range when it starts before end and ends after start:

const inRange = (event: CalendarEvent, range: VisibleRange) =>
  event.start < range.end &&
  (event.isAllDay ? event.end >= range.start : event.end > range.start);

All-day events

An all-day event's end is the start of its last day, so a one-day event has start equal to end. Compare its end with >=, or it drops off the first day of the range.

Read the range anywhere inside the provider with useCalendar().visibleRange, and the loading state with useCalendar().loading, for example to show a spinner in your own toolbar.

When it fires

  • Once after the view mounts.
  • When the dates change: previous and next, today, goToDate, a view switch, a new numberOfDays, and month view's vertical scroll.
  • During a sideways scroll in day and week view, once the scroll snaps to a day, not for every day it passes. For the days on screen mid-scroll, read visibleDays.
  • Never twice in a row for the same range. Re-renders, edits and selection don't fire it, and neither does a view switch that's undone because the mounted view doesn't follow it.

A range can come back: going to next week and back reports this week again. Cache by range, as the preview does, or by day, so a range seen before skips the network.

Loading bar

loading draws a 2px indeterminate bar along the bottom of the day headers in Day View, Week View and Month View, and along the top of Agenda View and Year View. It doesn't block anything: people can keep dragging, creating and navigating while events load. With reduced motion turned on, the bar holds still instead of sliding. The view is marked aria-busy while loading.

The bar is CalendarLoadingBar in components/calendar-loading-bar.tsx, and its animation is a .calendar-loading-bar class. Both come with Calendar Core, so every view you install has it.

API Reference

The provider props and the range type. See Calendar Core for the rest of the provider.

PropTypeDefault
onVisibleRangeChange
Called with the dates the view draws: once after it mounts, then each time they change. Never twice in a row for the same range.
(range: VisibleRange) => void–
loading
Shows a thin progress bar under the day headers of every view. The calendar stays usable.
booleanfalse

VisibleRange

FieldType
start
Midnight that starts the first visible day.
Date
end
Midnight after the last visible day (exclusive).
Date

On this page