FAQ

Frequently asked questions about ilamy Calendar.

General Questions

How do I install ilamy Calendar?

See the installation guide for detailed instructions.

Is ilamy Calendar free?

Yes, ilamy Calendar is open-source and free to use.

What React versions are supported?

ilamy Calendar supports React 19 and above.

Does ilamy Calendar support TypeScript?

Yes, ilamy Calendar is built with TypeScript and provides full type definitions.

Which CSS framework does ilamy Calendar use?

ilamy Calendar is built with Tailwind CSS v4 and ships no CSS. You need to configure Tailwind to scan the package using the @source directive.

Usage

How do I customize event colors?

You can set custom colors for events by adding a color property to your event objects:

const events = [
  {
    id: '1',
    title: 'Meeting',
    start: new Date(),
    end: new Date(),
    color: '#ff6b6b' // Custom color
  }
];

How do I add drag and drop functionality?

The calendar includes built-in drag and drop support that is enabled by default. To disable it, use the disableDragAndDrop prop:

<IlamyCalendar
  events={events}
  disableDragAndDrop={true}
  // ... other props
/>

Framework Integration

Can I use this with Next.js?

Yes! ilamy Calendar works perfectly with Next.js, Vite, Create React App, and any other React framework. Just make sure to install the required peer dependencies. When using with Next.js, you need to use client directives:

'use client';

import { IlamyCalendar } from '@ilamy/calendar';
import { useState } from 'react';

export default function CalendarPage() {
  const [events, setEvents] = useState([]);

  return (
    <IlamyCalendar
      events={events}
      // ... other props
    />
  );
}

Since 3.0.0 the calendar also hydrates cleanly when it is server-rendered: the drag-and-drop context takes a stable id derived with React’s useId, so the markup the server produces matches what the client expects. Before that, the ids were numbered from a module-level counter that carried between requests, and the second request onwards mismatched.

Can I use this with Astro?

Absolutely! This very website is built with Astro and demonstrates the calendar integration on the demo page. However, when using the calendar with Astro, you must use the client:only directive instead of other client directives like client:load because the calendar doesn’t work properly with other directives:

---
// In your .astro file
import { CalendarDemo } from '../components/calendar-demo';
---

<CalendarDemo client:only="react" />

<!-- NOT recommended for this calendar -->
<!-- <CalendarDemo client:load /> -->
<!-- <CalendarDemo client:idle /> -->

Features

Can I customize the appearance of the calendar?

Yes, you can customize the calendar extensively using Tailwind CSS classes, custom components, and theme configuration. See the customization guide for details.

Does it support multiple languages?

Yes, ilamy Calendar supports internationalization with locale-based formatting and custom translations. See the internationalization guide for details.

Can I export events to iCalendar format?

Yes, ilamy Calendar includes built-in iCalendar export functionality. See the iCalendar export guide for details.

Does it support recurring events?

Yes, ilamy Calendar fully supports recurring events with RRULE patterns. See the recurrence guide for details.

Can I use custom fonts?

Absolutely! The calendar inherits font styles from its parent container. You can use any web font or custom font family with Tailwind CSS font utilities.

Is the calendar responsive?

Yes. The calendar adapts to the width of its own container rather than the screen, so it fits a sidebar as well as a full page. The header, for example, stacks its controls on a narrow calendar, sets them in one row from 576px wide, and shows the segmented view switcher from 896px.

Internationalization

How do I handle timezone support?

Timezone is handled with the timezone prop. Changing it while the calendar is mounted moves the current date and every event onto the new zone’s clock, so no key or remount is needed:

const [timezone, setTimezone] = useState('America/New_York');

<IlamyCalendar timezone={timezone} events={events} />

Instants never move; only the clock they are shown on changes. Removing the prop returns the calendar to the browser’s zone.

How do I handle locale support?

Locale is handled with the locale prop. Changing it while the calendar is mounted applies the new locale’s month and weekday names and formats, so no key or remount is needed:

const [locale, setLocale] = useState('en');

<IlamyCalendar locale={locale} events={events} />

Load the dayjs locale first (import 'dayjs/locale/fr').

Why isn’t `@ilamy/calendar/plugins/recurrence` found after installing?

The plugin subpaths (/plugins/recurrence, /plugins/agenda, /plugins/drag-to-create) exist only in v2.0.0 and later. On 1.x, recurrence was built into the core and there were no plugin entry points, so the import fails even though the docs describe it. Upgrade to v2 following the migration guide, then register the plugin:

import { IlamyCalendar } from '@ilamy/calendar'
import { recurrencePlugin } from '@ilamy/calendar/plugins/recurrence'

<IlamyCalendar events={events} plugins={[recurrencePlugin()]} />

How do I make scoped edits to a recurring series from a custom event form?

Use applyScopedEdit and applyScopedDelete from useIlamyCalendarContext() (v2.0.0+). Pass the occurrence the user is editing, the changed fields, and a scope of 'this', 'following', or 'all' — the recurrence plugin handles the RFC 5545 mechanics (exception dates, modified instances, series splits), and the resulting changes are reported through onEventUpdate, onEventAdd, and onEventDelete so you can persist them, and once more, all together, through onEventsChange if you would rather save each action as one unit:

const { applyScopedEdit, getEventManager } = useIlamyCalendarContext();

// In your form's submit handler:
if (getEventManager(event)) {
  // Recurring — ask the user for a scope, then:
  applyScopedEdit(event, updates, scope); // 'this' | 'following' | 'all'
} else {
  updateEvent(event.id, updates);
}

See the useIlamyCalendarContext reference for details.

Why aren’t calendar styles showing up?

Make sure you’ve registered the calendar package in your Tailwind CSS configuration using the @source directive:

@source "../node_modules/@ilamy/calendar/dist";

See the usage guide for more details.

Why am I getting “isSameOrBefore is not a function” error?

This error occurs when you have Day.js installed as a dependency in your project and the required plugins are not loaded. Although Day.js is exported from this library, your Day.js instance will be used, which may cause errors if the required plugins are not loaded.

To fix this, you need to extend Day.js with the required plugins in your application:

import dayjs from 'dayjs';
import isSameOrAfter from 'dayjs/plugin/isSameOrAfter.js';
import isSameOrBefore from 'dayjs/plugin/isSameOrBefore.js';
import timezone from 'dayjs/plugin/timezone.js';
import utc from 'dayjs/plugin/utc.js';

dayjs.extend(isSameOrAfter);
dayjs.extend(isSameOrBefore);
dayjs.extend(timezone);
dayjs.extend(utc);

Add this configuration early in your application, preferably in your main entry file (e.g., main.tsx, index.tsx, or _app.tsx).

FAQ