useIlamyCalendarContext

A React hook for accessing calendar context and controlling calendar state programmatically. It returns the IlamyCalendarApi object.

The API is unified: the same shape is returned whether or not the calendar has resources. On a calendar without resources, resources is simply an empty array and getEventsForResource filters by the events’ own resourceId / resourceIds. There is no separate resource-calendar return type.

Basic Usage

The useIlamyCalendarContext hook provides access to the calendar’s internal state and methods. It must be used within components that are descendants of the IlamyCalendar component.

Basic Usage

import { useIlamyCalendarContext } from '@ilamy/calendar';

// Method 1: Via headerComponent prop
function CustomHeader() {
  const { currentDate, nextPeriod, prevPeriod } = useIlamyCalendarContext();

  return (
    <div>
      <button onClick={prevPeriod}>Previous</button>
      <span>{currentDate.format('MMMM YYYY')}</span>
      <button onClick={nextPeriod}>Next</button>
    </div>
  );
}

<IlamyCalendar
  events={events}
  headerComponent={<CustomHeader />}
/>

// Method 2: Via renderEvent prop
function CustomEvent(event) {
  const { deleteEvent, updateEvent } = useIlamyCalendarContext();

  return (
    <div className="custom-event">
      <span>{event.title}</span>
      <button onClick={() => deleteEvent(event.id)}>Delete</button>
    </div>
  );
}

<IlamyCalendar
  events={events}
  renderEvent={CustomEvent}
/>

Return Values (IlamyCalendarApi)

The hook returns an object with the following properties and methods:

Property	Type	Description
currentDate	Dayjs	The currently displayed date/month in the calendar view
view	CalendarView (string)	The current view name. In v2 CalendarView is string so plugins can register extra views
events	CalendarEvent[]	Expanded events for the current view (recurring instances included when the recurrence plugin is registered)
rawEvents	CalendarEvent[]	The unexpanded source events as passed in. Use this to find a base recurring series by uid
resources	Resource[]	Resources on the calendar. Empty array when none are set
orientation	'horizontal' | 'vertical'	The axis the views lay out along. Defaults to 'horizontal'; relevant for resource calendars
isEventFormOpen	boolean	Whether the event form modal is currently open
selectedEvent	CalendarEvent | null	The currently selected event, if any
selectedDate	Dayjs | null	The currently selected date, if any
firstDayOfWeek	number	The first day of the week (0 = Sunday)
setCurrentDate	(date: Dayjs) => void	Navigate to a specific date/month
selectDate	(date: Dayjs) => void	Select a specific date
setView	(view: CalendarView, date?: Dayjs) => void	Change the current view. Pass date to also move there in the same update, firing a single onDateChange with the new view’s range
nextPeriod	() => void	Navigate to the next period
prevPeriod	() => void	Navigate to the previous period
today	() => void	Navigate to today’s date
addEvent	(event: CalendarEvent) => void	Add a new event to the calendar
updateEvent	(id: string | number, updates: Partial<CalendarEvent>) => void	Update an existing event
deleteEvent	(id: string | number) => void	Delete an event from the calendar
openEventForm	(eventData?: OpenEventFormInput) => void	Open the event form modal with optional pre-populated data
closeEventForm	() => void	Close the event form modal
onEventClick	(event: CalendarEvent) => void	Run the calendar’s event-click flow for an event
getEventsForResource	(resourceId: string | number) => CalendarEvent[]	Events for a resource. Always defined; filters by resourceId / resourceIds
getEventsForDateRange	(start: Dayjs, end: Dayjs) => CalendarEvent[]	Events overlapping a date range
t	TranslatorFunction	Translate a key with the active translations
timeFormat	TimeFormat	'12-hour' or '24-hour'
timezone	string | undefined	The configured timezone, if any
currentLocale	string	The active dayjs locale
businessHours	BusinessHours | BusinessHours[] | undefined	The configured business hours
getViews	() => PluginView[]	All registered views (built-in plus plugin)

Scoped mutations (recurrence)

applyScopedEdit(event, updates, scope) and applyScopedDelete(event, scope) apply an edit/delete with a scope (this / this-and-following / all) routed to the owning plugin. The scope value is produced by the recurrence plugin’s mutation-scope dialog and is passed back automatically by the host’s built-in scoped-mutation flow, so most apps never call these directly.

Renamed in v2

The old updateRecurringEvent and deleteRecurringEvent are replaced by applyScopedEdit / applyScopedDelete. findParentRecurringEvent was removed — find the base series via rawEvents instead:

const { rawEvents } = useIlamyCalendarContext();
const baseEvent = rawEvents.find(
  (e) => e.uid === instance.uid && e.rrule !== undefined
);

The API also exposes lower-level plugin-routing helpers — getEventManager, renderSlot, collect, and renderCurrentTimeIndicator — used internally by plugins; most consumers don’t need them.

Resources

resources and getEventsForResource are always available. Set the resources prop on IlamyCalendar to render a resource calendar.

Resource Usage

Via headerComponent

import { useIlamyCalendarContext } from '@ilamy/calendar';

function CustomHeader() {
  const { currentDate, nextPeriod, prevPeriod, resources } = useIlamyCalendarContext();

  return (
    <div>
      <button onClick={prevPeriod}>Previous</button>
      <span>{currentDate.format('MMMM YYYY')}</span>
      <button onClick={nextPeriod}>Next</button>
      <div>Resources: {resources.length}</div>
    </div>
  );
}

<IlamyCalendar
  resources={resources}
  events={events}
  headerComponent={<CustomHeader />}
/>

Resource Utilization Display

Show Resource Booking Stats

function ResourceStats({ resourceId }) {
  const { getEventsForResource, currentDate } = useIlamyCalendarContext();

  const events = getEventsForResource(resourceId);
  const todayEvents = events.filter(event =>
    event.start.isSame(currentDate, 'day')
  );

  return (
    <div className="resource-stats">
      <div>Total Events: {events.length}</div>
      <div>Today: {todayEvents.length}</div>
    </div>
  );
}

<IlamyCalendar
  resources={resources}
  events={events}
  renderResource={(resource) => (
    <div>
      <span>{resource.title}</span>
      <ResourceStats resourceId={resource.id} />
    </div>
  )}
/>

Quick Event Creation

Quick Event Creation per Resource

function ResourceActions({ resource }) {
  const { addEvent, currentDate } = useIlamyCalendarContext();

  const createQuickEvent = () => {
    const newEvent = {
      id: `event-${Date.now()}`,
      title: 'Quick Booking',
      start: currentDate.hour(9).minute(0),
      end: currentDate.hour(10).minute(0),
      uid: `event-${Date.now()}@company.com`,
      resourceId: resource.id,
    };
    addEvent(newEvent);
  };

  return (
    <div className="resource-actions">
      <span>{resource.title}</span>
      <button onClick={createQuickEvent}>Quick Book</button>
    </div>
  );
}

<IlamyCalendar
  resources={resources}
  events={events}
  renderResource={(resource) => <ResourceActions resource={resource} />}
/>

Error Handling

The hook will throw an error if used outside of the calendar context. Since IlamyCalendar does not accept children, you must use this hook in descendant components that are rendered through props like headerComponent, renderEvent, or renderResource.

Context Usage

// ❌ This will throw an error
function BadComponent() {
  // This component is not inside a calendar context
  const { currentDate } = useIlamyCalendarContext(); // Error!
  return <div>{currentDate.format()}</div>;
}

// ❌ This won't work - neither calendar accepts children
function App() {
  return (
    <IlamyCalendar events={events}>
      <GoodComponent /> {/* This won't render */}
    </IlamyCalendar>
  );
}