FullEventCalendar

A comprehensive guide to installing, configuring, and using the FullEventCalendar component in your React application.

Calendar Overview

Installation

Prerequisites

Before you begin, ensure your project meets these requirements:

✅ Node.js 18.0 or later
✅ React and Next.js project setup
✅ shadcn/ui components installed
✅ Access to FullEventCalendar Repos

Setup Steps

Copy the Component

Copy the event-calendar folder from src/components into your project's components directory:

cp -r src/components/event-calendar your-project/src/components/
Install Dependencies

Install the required npm packages:

# Using npm npm install date-fns react-swipeable framer-motion @radix-ui/react-icons # Or using yarn yarn add date-fns react-swipeable framer-motion @radix-ui/react-icons # Or using bun bun add date-fns react-swipeable framer-motion @radix-ui/react-icons
Add shadcn/ui Components

Ensure you have the necessary shadcn/ui components installed:

# Install all required components at once (with npm) npx shadcn-ui@latest add card input scroll-area tooltip sonner popover command form textarea calendar carousel switch dialog dropdown-menu select alert-dialog # Or with yarn yarn shadcn-ui add card input scroll-area tooltip sonner popover command form textarea calendar carousel switch dialog dropdown-menu select alert-dialog # Or with bun bunx --bun shadcn@latest add card input scroll-area tooltip sonner popover command form textarea calendar carousel switch dialog dropdown-menu select alert-dialog
Add Skeleton Styling

Add the following styles to your global CSS file for the skeleton loading animation:

@keyframes shimmer { 0% { transform: translateX(-100%); } 100% { transform: translateX(100%); } } .skeleton-shimmer::after { content: ""; position: absolute; inset: 0; transform: translateX(-100%); animation: shimmer 2s infinite; background-image: linear-gradient( 90deg, rgba(255, 255, 255, 0) 0%, rgba(255, 255, 255, 0.2) 20%, rgba(255, 255, 255, 0.5) 60%, rgba(255, 255, 255, 0) 100% ); } .dark .skeleton-shimmer::after { background-image: linear-gradient( 90deg, rgba(0, 0, 0, 0) 0%, rgba(255, 255, 255, 0.1) 20%, rgba(255, 255, 255, 0.2) 60%, rgba(0, 0, 0, 0) 100% ); }

Basic Usage

The recommended way to use FullEventCalendar is with the useEventCalendar hook for state management:

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

const MyCalendar = () => {
  // Configuration options
  const config: EventCalendarConfigType = {
    defaultView: 'month',
    use24HourFormatByDefault: true,
    // View-specific settings
    monthView: {
      viewType: 'detailed',
      enableDoubleClickToShiftViewToWeekly: true,
    },
  };

  // Use the hook to handle state
  const {
    events,
    isLoading,
    addEvent,
    updateEvent,
    deleteEvent,
    onViewOrDateChange
  } = useEventCalendar({
    config: {
      calendarConfig: config,  // Note: config goes inside calendarConfig
      events: {
        allowUserRetryAfterFailure: true
      }
    },
    initialEvents: [],
    onEventAdd: async (event) => {
      // API call to add event
      const response = await fetch('/api/events', {
        method: 'POST',
        body: JSON.stringify(event),
      });
      const data = await response.json();
      return data; // Must return event with ID
    },
    onEventUpdate: async (event) => {
      // API call to update event
      await fetch(`/api/events/${event.id}`, {
        method: 'PUT',
        body: JSON.stringify(event),
      });
      return event; // Must return the updated event
    },
    onEventDelete: async (eventId) => {
      // API call to delete event
      await fetch(`/api/events/${eventId}`, {
        method: 'DELETE',
      });
    },
    onDateRangeChange: async (startDate, endDate, signal) => {
      // Fetch events for date range
      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={config}
    />
  );
};

export default MyCalendar;

Event Structure

Events in FullEventCalendar follow this structure:

interface CalendarEventType {
  id?: string; // Optional when creating, required when updating
  title: string;
  description?: string;
  startDate: Date;
  endDate: Date;
  startTime: string; // Format: "HH:MM"
  endTime: string; // Format: "HH:MM"
  color: string; // One of the predefined colors
  isRepeating: boolean;
  isRepeatingInterval?: 'daily' | 'weekly' | 'monthly';
}

Configuration Options

The calendar can be customized with various options:

const config: EventCalendarConfigType = {
  defaultView: 'month', // 'day', 'week', 'month', 'year'
  use24HourFormatByDefault: true,
  dayView: {
    viewType: 'regular', // or 'resource'
    hideHoverLine: false,
    hideTimeline: false,
    enableDoubleClickToAddEvent: true,
  },
  weekView: {
    viewType: 'regular', // or 'resource'
    hideHoverLine: false,
    hideTimeline: false,
    enableDoubleClickToShiftViewToDaily: true,
  },
  monthView: {
    showOnlyCurrentMonth: false,
    viewType: 'detailed', // or 'basic'
    enableDoubleClickToShiftViewToWeekly: true,
  },
  yearView: {
    enableDoubleClickToShiftViewToMonthly: true,
  },
  // Localization options available
};

Recommended Pattern: MyEventCalendar

For most applications, it's recommended to create a wrapper component (similar to the MyEventCalendar.tsx in this project) that implements the useEventCalendar hook.
This approach provides: