Calendar Props Reference

Comprehensive documentation of all props available for the EventCalendar component.

EventCalendarProps

The EventCalendar component accepts the following props:

interface EventCalendarProps {
  // Calendar configuration
  config?: EventCalendarConfigType;
  
  // Event data
  events: CalendarEventType[];
  
  // Loading state
  isLoading?: boolean;
  
  // Event operation handlers
  onEventAdd: (event: Omit<CalendarEventType, 'id'>) => Promise<void>;
  onEventUpdate: (event: CalendarEventType) => Promise<void>;
  onEventDelete: (eventId: string) => Promise<void>;
  
  // Date range change handler
  onDateRangeChange?: (startDate: Date, endDate: Date, signal?: AbortSignal) => Promise<void>;
}

Props Description

config

Type: EventCalendarConfigType
Required: No
Default: See Configuration Options

Configuration options for the calendar, including view preferences, time format, and localization.

const config = {
  defaultView: 'month',
  use24HourFormatByDefault: true,
  monthView: {
    viewType: 'detailed'
  }
};

events

Type: CalendarEventType[]
Required: Yes

Array of events to display in the calendar.

const events = [
  {
    id: '1',
    title: 'Team Meeting',
    startDate: new Date(2024, 0, 15),
    endDate: new Date(2024, 0, 15),
    startTime: '10:00',
    endTime: '11:00',
    color: 'blue',
    isRepeating: false
  }
];

isLoading

Type: boolean
Required: No
Default: false

When true, displays skeleton loading UI while fetching events.

onEventAdd

Type: (event: Omit<CalendarEventType, 'id'>) => Promise<void>
Required: Yes

Handler function called when a new event is created.

const handleEventAdd = async (event) => {
  try {
    await api.createEvent(event);
  } catch (error) {
    console.error('Failed to add event:', error);
    throw error; // Important: throw to trigger error handling in the UI
  }
};

onEventUpdate

Type: (event: CalendarEventType) => Promise<void>
Required: Yes

Handler function called when an existing event is updated.

const handleEventUpdate = async (event) => {
  try {
    await api.updateEvent(event.id, event);
  } catch (error) {
    console.error('Failed to update event:', error);
    throw error; // Important: throw to trigger error handling in the UI
  }
};

onEventDelete

Type: (eventId: string) => Promise<void>
Required: Yes

Handler function called when an event is deleted.

const handleEventDelete = async (eventId) => {
  try {
    await api.deleteEvent(eventId);
  } catch (error) {
    console.error('Failed to delete event:', error);
    throw error; // Important: throw to trigger error handling in the UI
  }
};

onDateRangeChange

Type: (startDate: Date, endDate: Date, signal?: AbortSignal) => Promise<void>
Required: No

Handler function called when the visible date range changes (e.g., when navigating between months or changing views).

const handleDateRangeChange = async (startDate, endDate, signal) => {
  try {
    const fetchedEvents = await api.getEvents(
      startDate.toISOString(),
      endDate.toISOString(),
      { signal }
    );
    // You'll typically update your event state here
  } catch (error) {
    if (error.name === 'AbortError') {
      // Request was aborted, which is normal when navigating quickly
      return;
    }
    console.error('Failed to fetch events:', error);
    throw error;
  }
};

Basic Usage Example

import { EventCalendar } from '@/components/event-calendar';
import { useEventCalendar } from '@/components/event-calendar/hooks/useEventCalendar';

const Calendar = () => {
  const {
    events,
    isLoading,
    addEvent,
    updateEvent,
    deleteEvent,
    onViewOrDateChange
  } = useEventCalendar({
    initialEvents: [],
    onEventAdd: async (event) => {
      // API implementation...
      return createdEvent; // Must return the created event with ID
    },
    onEventUpdate: async (event) => {
      // API implementation...
      return event; // Must return the updated event
    },
    onEventDelete: async (eventId) => {
      // API implementation...
    },
    onDateRangeChange: async (startDate, endDate, signal) => {
      // API implementation...
      return fetchedEvents; // Must return the fetched events
    }
  });

  return (
    <EventCalendar
      events={events}
      isLoading={isLoading}
      onEventAdd={addEvent}
      onEventUpdate={updateEvent}
      onEventDelete={deleteEvent}
      onDateRangeChange={onViewOrDateChange}
      config={{
        defaultView: 'month',
        use24HourFormatByDefault: true
      }}
    />
  );
};