Hooks Reference

Comprehensive documentation of all hooks available in the Event Calendar component.

useEventCalendar

The primary hook for managing calendar state and events with built-in optimistic updates, error handling, and undo functionality.

useEventCalendar Signature

function useEventCalendar(options: EventCalendarHookProps): EventCalendarHookReturn

useEventCalendar Props

The EventCalendarHookProps interface accepts the following properties:

interface EventCalendarHookProps {
  // Initial events to populate the calendar
  initialEvents?: CalendarEventType[];
  
  // Configuration options specifically for the hook behavior
  config?: EventCalendarHookConfig;
  
  // Optional callbacks for event operations
  onEventAdd?: (event: Omit<CalendarEventType, 'id'>) => Promise<CalendarEventType>;
  onEventUpdate?: (event: CalendarEventType) => Promise<CalendarEventType>;
  onEventDelete?: (eventId: string) => Promise<void>;
  
  // Function to fetch events when date range changes
  onDateRangeChange?: (
    startDate: Date,
    endDate: Date,
    signal?: AbortSignal
  ) => Promise<CalendarEventType[]>;
}

interface EventCalendarHookConfig {
  events?: {
    allowUserRetryAfterFailure?: boolean;
    debounceTimeOnViewOrDateChange?: number;
  };
  calendarConfig?: EventCalendarConfigType;
}

useEventCalendar Return Value

Returns an object with the following properties:

interface EventCalendarHookReturn {
  // Current events in the calendar
  events: CalendarEventType[];
  
  // Loading state
  isLoading: boolean;
  
  // Event operation handlers
  addEvent: (event: Omit<CalendarEventType, 'id'>, isUndo?: boolean) => Promise<void>;
  updateEvent: (event: CalendarEventType, isUndo?: boolean) => Promise<void>;
  deleteEvent: (eventId: string, isUndo?: boolean) => Promise<void>;
  
  // View change handler
  onViewOrDateChange: (startDate: Date, endDate: Date) => Promise<void>;
}

useEventCalendar Example

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

const Calendar = () => {
  const {
    events,
    isLoading,
    addEvent,
    updateEvent,
    deleteEvent,
    onViewOrDateChange
  } = useEventCalendar({
    initialEvents: [],
    config: {
      events: {
        allowUserRetryAfterFailure: true,
        debounceTimeOnViewOrDateChange: 300
      },
      calendarConfig: {
        defaultView: 'month',
        use24HourFormatByDefault: true
      }
    },
    async onEventAdd(event) {
      const response = await fetch('/api/events', {
        method: 'POST',
        body: JSON.stringify(event)
      });
      const data = await response.json();
      return data; // Must return the created event with ID
    },
    async onEventUpdate(event) {
      await fetch(`/api/events/${event.id}`, {
        method: 'PUT',
        body: JSON.stringify(event)
      });
      return event; // Must return the updated event
    },
    async onEventDelete(eventId) {
      await fetch(`/api/events/${eventId}`, {
        method: 'DELETE'
      });
      // Void return is expected
    },
    async onDateRangeChange(startDate, endDate, signal) {
      const response = await fetch(
        `/api/events?start=${startDate.toISOString()}&end=${endDate.toISOString()}`,
        { signal }
      );
      return await response.json(); // Must return array of events
    }
  });

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

useCalendarNavigation

Hook for managing calendar navigation and view state.

useCalendarNavigation Signature

function useCalendarNavigation(options: UseCalendarNavigationProps): UseCalendarNavigationResult

useCalendarNavigation Props

interface UseCalendarNavigationProps {
  config: {
    defaultView: CalendarViewType;
    use24HourFormatByDefault: boolean;
  };
  translations: EventCalendarTranslations;
}

useCalendarNavigation Return Value

interface UseCalendarNavigationResult {
  currentDate: Date;
  currentView: CalendarViewType;
  viewOptions: ViewOption[];
  visibleDates: Date[];
  setCurrentDate: (date: Date) => void;
  setCurrentView: (view: CalendarViewType) => void;
  handlePrevious: () => void;
  handleNext: () => void;
  handleToday: () => void;
  use24HourFormat: boolean;
  setUse24HourFormat: (use24Hour: boolean) => void;
}

useCalendarNavigation Example

import { useCalendarNavigation } from '@/components/event-calendar/hooks/useCalendarNavigation';
import { enUS } from '@/components/event-calendar/locales/en';

const CalendarNavigation = () => {
  const {
    currentView,
    currentDate,
    setCurrentView,
    setCurrentDate,
    handleNext,
    handlePrevious,
    handleToday,
    viewOptions
  } = useCalendarNavigation({
    config: {
      defaultView: 'month',
      use24HourFormatByDefault: true
    },
    translations: enUS
  });

  return (
    <div>
      <button onClick={handlePrevious}>Previous</button>
      <button onClick={handleToday}>Today</button>
      <button onClick={handleNext}>Next</button>
      <select
        value={currentView}
        onChange={(e) => setCurrentView(e.target.value as any)}
      >
        {viewOptions.map(option => (
          <option key={option.value} value={option.value}>
            {option.label}
          </option>
        ))}
      </select>
    </div>
  );
};

useDateRange

Hook for managing date range selections based on the current view and date.

useDateRange Signature

function useDateRange(
  currentDate: Date,
  currentView: CalendarViewType
): { startDate: Date; endDate: Date };

useDateRange Example

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

const DateRangeDisplay = () => {
  const currentDate = new Date();
  const currentView = 'month';
  const { startDate, endDate } = useDateRange(currentDate, currentView);

  return (
    <div>
      <p>Showing events from {startDate.toLocaleDateString()} to {endDate.toLocaleDateString()}</p>
    </div>
  );
};

useCurrentTimeLine

Hook for managing the current time indicator in week and day views.

useCurrentTimeLine Signature

function useCurrentTimeLine(): {
  currentTime: Date;
  currentTimePosition: number;
};

useCurrentTimeLine Example

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

const TimelineIndicator = () => {
  const { currentTime, currentTimePosition } = useCurrentTimeLine();
  
  return (
    <div 
      className="timeline-indicator"
      style={{ top: `${currentTimePosition}px` }}
    >
      {currentTime.toLocaleTimeString()}
    </div>
  );
};