ilamy Calendarilamy Calendar

Calendar

A comprehensive React calendar component with month, week, and day views.

Basic Usage

The Calendar component is the main component for displaying calendar views. It supports various props for customization and event handling. Events should follow the CalendarEvent interface. 

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

const events = [
  {
    id: '1',
    title: 'Team Meeting',
    start: new Date('2024-01-15T10:00:00'),
    end: new Date('2024-01-15T11:00:00'),
    description: 'Weekly team sync',
    backgroundColor: '#3b82f6'
    color: 'black'
  },
  {
    id: '2',
    title: 'Project Deadline',
    start: new Date('2024-01-20T23:59:59'),
    end: new Date('2024-01-20T23:59:59'),
    allDay: true,
    backgroundColor: '#ef4444'
    color: 'black'
  }
];

function MyCalendar() {
  return (
    <IlamyCalendar events={events} />
  );
}

Props

Basic Props

NameTypeDefaultDescription
events
CalendarEvent[][]

Array of events to display in the calendar

firstDayOfWeek
'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday''sunday'

The first day of the week to display

dayMaxEvents
number4

Maximum number of events to display in a day cell

renderEvent
(event: CalendarEvent) => ReactNode—

Custom function to render individual events

locale
string'en'

Locale for date formatting (e.g., "en", "fr", "de")

timezone
stringWhatever your local timezone is

Timezone for date handling (e.g., "UTC", "America/New_York")

stickyViewHeader
booleantrue

Whether to stick the view header to the top

viewHeaderClassName
string''

Custom class name for the view header

headerComponent
ReactNodenull

Custom header component to render above the calendar

disableCellClick
booleanfalse

Disable cell click interactions

disableEventClick
booleanfalse

Disable event click interactions

disableDragAndDrop
booleanfalse

Disable drag-and-drop functionality for events

Event Handlers

NameTypeDefaultDescription
onEventClick
(event: CalendarEvent) => void—

Called when an event is clicked

onCellClick
(date: Date) => void—

Called when a date cell is clicked

onViewChange
(view: 'month' | 'week' | 'day' | 'year') => void—

Called when the calendar view changes

Examples

With Event Handlers

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

function MyCalendar() {
  const handleEventClick = (event) => {
    console.log('Event clicked:', event);
    // Open event details modal, navigate to event page, etc.
  };

  const handleDateClick = (date) => {
    console.log('Date clicked:', date);
    // Create new event, switch to day view, etc.
  };

  const handleViewChange = (view) => {
    console.log('View changed to:', view);
    // Update URL, track analytics, etc.
  };

  return (
    <IlamyCalendar
      events={events}
      firstDayOfWeek="monday"
      onEventClick={handleEventClick}
      onCellClick={handleDateClick}
      onViewChange={handleViewChange}
    />
  );
}

Internationalization

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

function InternationalCalendar() {
  return (
    <IlamyCalendar
      events={events}
      locale="fr" // French locale
      timezone="Europe/Paris" // Paris timezone
      firstDayOfWeek="monday"
      onEventClick={(event) => console.log('Événement cliqué:', event)}
      onCellClick={(date) => console.log('Date sélectionnée:', date)}
      onViewChange={(view) => console.log('Vue changée:', view)}
    />
  );
}

Custom Event Rendering

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

function CustomCalendar() {
  const renderEvent = (event) => (
    <div className="px-2 py-1 rounded bg-blue-100 text-blue-800">
      <div className="font-semibold">{event.title}</div>
      <div className="text-xs">{event.description}</div>
    </div>
  );

  return (
    <IlamyCalendar
      events={events}
      renderEvent={renderEvent}
      onEventClick={(event) => alert(`Clicked: ${event.title}`)}
      onCellClick={(date) => console.log('Selected date:', date)}
    />
  );
}

Types

CalendarEvent Interface

The main event object used throughout the calendar. All events passed to the calendar should conform to this interface. 

interface CalendarEvent {
  id: string;              // Unique identifier for the event
  title: string;           // Display title of the event
  start: Date;             // Start date and time
  end: Date;               // End date and time
  description?: string;    // Optional description text
  color?: string;          // Optional text color (hex, rgb, named colors, class names)
  backgroundColor?: string; // Optional background color (hex, rgb, named colors, class names)
  allDay?: boolean;        // Whether this is an all-day event
  data?: Record<string, any>; // Optional custom data for additional properties
}

Event Properties Explained

Required Properties

  • id - Must be unique across all events. Used for drag-and-drop and event updates.
  • title - The text displayed on the event in the calendar.
  • start - JavaScript Date object representing when the event begins.
  • end - JavaScript Date object representing when the event ends.

Optional Properties

  • description - Additional text shown in tooltips or custom event renderers.
  • color - Background color for the event. Supports hex (#ff0000), rgb(255,0,0), or named colors (red).
  • allDay - When true, the event spans the entire day and ignores time components.

Example Event Objects

// Regular timed event
const meeting = {
  id: 'meeting-1',
  title: 'Team Standup',
  start: new Date('2024-01-15T09:00:00'),
  end: new Date('2024-01-15T09:30:00'),
  description: 'Daily team sync meeting',
  color: '#3b82f6'
};

// All-day event
const holiday = {
  id: 'holiday-1',
  title: 'National Holiday',
  start: new Date('2024-01-01'),
  end: new Date('2024-01-01'),
  allDay: true,
  color: '#ef4444'
};

// Multi-day event
const conference = {
  id: 'conf-1',
  title: 'Tech Conference',
  start: new Date('2024-01-20T08:00:00'),
  end: new Date('2024-01-22T18:00:00'),
  description: 'Annual technology conference',
  color: '#10b981'
};
UsageResource Calendar