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.

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.

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

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

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

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.

// ❌ 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>
  );
}