Back

Documentation

Installation

After purchasing CalendarKit, you'll receive access to a private GitHub repository containing the full source code.

How it works:

  1. Complete your purchase on our website
  2. Provide your GitHub username during checkout
  3. Within minutes, you'll receive an invitation to our private repository
  4. Accept the invitation and clone the repository
  5. The source code is yours - customize it as needed

What you get:

  • • Full source code with TypeScript types
  • • Working Next.js demo application
  • • Complete documentation
  • • Lifetime access to the repository
  • • Future updates and bug fixes
# After purchase, you'll receive access to our private GitHub repository.
# Clone the repository using your GitHub account:

git clone https://github.com/calaboratehq/basic-scheduler.git
# or for Pro version:
git clone https://github.com/calaboratehq/pro-scheduler.git

# Install dependencies
cd basic-scheduler  # or pro-scheduler
npm install

# Run the development server
npm run dev

Basic Usage

The BasicScheduler component provides essential calendar functionality with month, week, and day views.

BasicScheduler Example
import { Scheduler } from '@/components/scheduler';
import { CalendarEvent, ViewType } from '@/components/scheduler/types';
import { useState } from 'react';

export default function MyCalendar() {
  const [events, setEvents] = useState<CalendarEvent[]>([]);
  const [view, setView] = useState<ViewType>('week');
  const [date, setDate] = useState(new Date());

  return (
    <Scheduler
      events={events}
      view={view}
      onViewChange={setView}
      date={date}
      onDateChange={setDate}
      onEventCreate={(event) => {
        setEvents([...events, { ...event, id: Date.now().toString() }]);
      }}
    />
  );
}

Pro UsagePro

The ProScheduler includes all Basic features plus drag & drop, agenda view, resource view, timezone support, dark mode, i18n, and recurring events.

ProScheduler Example
import { Scheduler } from '@/components/pro-scheduler';
import { CalendarEvent, ViewType, Resource } from '@/components/pro-scheduler/types';
import { useState } from 'react';

export default function MyCalendar() {
  const [events, setEvents] = useState<CalendarEvent[]>([]);
  const [view, setView] = useState<ViewType>('week');
  const [date, setDate] = useState(new Date());
  const [isDarkMode, setIsDarkMode] = useState(false);

  return (
    <Scheduler
      events={events}
      view={view}
      onViewChange={setView}
      date={date}
      onDateChange={setDate}
      isDarkMode={isDarkMode}
      onThemeToggle={() => setIsDarkMode(!isDarkMode)}
      onEventCreate={(event) => {
        setEvents([...events, { ...event, id: Date.now().toString() }]);
      }}
    />
  );
}

Events

Events are the core data structure in CalendarKit. Each event must have a unique ID, title, start, and end date.

CalendarEvent Interface
interface CalendarEvent {
  id: string;           // Unique identifier
  title: string;        // Event title
  start: Date;          // Start date/time
  end: Date;            // End date/time
  description?: string; // Optional description
  color?: string;       // Hex color (e.g., '#3b82f6')
  allDay?: boolean;     // Is all-day event
  calendarId?: string;  // Associated calendar ID
  resourceId?: string;  // For resource view (Pro only)
  guests?: string[];    // Email addresses (Pro only)
  attachments?: EventAttachment[]; // Files (Pro only)
  recurrence?: {        // Recurring rules (Pro only)
    freq: 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'YEARLY';
    interval?: number;
    count?: number;     // Number of occurrences
    until?: Date;       // End date
  };
}

Required Fields

  • id - Unique identifier for the event
  • title - Display name of the event
  • start - JavaScript Date object for start time
  • end - JavaScript Date object for end time

Calendars

Calendars allow users to organize and filter events by category. Each calendar has a color and can be toggled on/off.

Calendar Filtering
const calendars = [
  { id: 'work', label: 'Work', color: '#3b82f6', active: true },
  { id: 'personal', label: 'Personal', color: '#10b981', active: true },
  { id: 'family', label: 'Family', color: '#8b5cf6', active: false },
];

<BasicScheduler
  events={events}
  calendars={calendars}
  onCalendarToggle={(id, active) => {
    setCalendars(cals =>
      cals.map(c => c.id === id ? { ...c, active } : c)
    );
  }}
/>

Event Handlers

CalendarKit provides callback functions for all user interactions. Use these to sync with your backend or state management.

Event Handlers
<ProScheduler
  events={events}
  // Called when user clicks on an event
  onEventClick={(event) => {
    console.log('Event clicked:', event);
  }}
  // Called when user creates a new event
  onEventCreate={(event) => {
    setEvents([...events, { ...event, id: Date.now().toString() }]);
  }}
  // Called when user updates an existing event
  onEventUpdate={(updatedEvent) => {
    setEvents(events.map(e =>
      e.id === updatedEvent.id ? updatedEvent : e
    ));
  }}
  // Called when user deletes an event
  onEventDelete={(eventId) => {
    setEvents(events.filter(e => e.id !== eventId));
  }}
  // Called when user drags an event to a new time (Pro only)
  onEventDrop={(event, newStart, newEnd) => {
    setEvents(events.map(e =>
      e.id === event.id ? { ...e, start: newStart, end: newEnd } : e
    ));
  }}
/>

BasicScheduler Props

Complete reference of all props available in BasicScheduler.

BasicScheduler Props Interface
// BasicScheduler Props
interface BasicSchedulerProps {
  // Data
  events?: CalendarEvent[];
  calendars?: Calendar[];

  // View Control
  view?: 'month' | 'week' | 'day';
  onViewChange?: (view: ViewType) => void;
  date?: Date;
  onDateChange?: (date: Date) => void;

  // Event Handlers
  onEventClick?: (event: CalendarEvent) => void;
  onEventCreate?: (event: Partial<CalendarEvent>) => void;
  onEventUpdate?: (event: CalendarEvent) => void;
  onEventDelete?: (eventId: string) => void;
  onCalendarToggle?: (calendarId: string, active: boolean) => void;

  // Customization
  theme?: CalendarTheme;
  locale?: Locale;
  className?: string;
  readOnly?: boolean;
  isLoading?: boolean;

  // Custom Rendering
  renderEventForm?: (props: EventFormProps) => React.ReactNode;
}
PropTypeDefaultDescription
eventsCalendarEvent[][]Array of events to display
view'month' | 'week' | 'day''week'Current calendar view
dateDatenew Date()Currently focused date
calendarsCalendar[]undefinedCalendar categories for filtering
localeLocaleundefineddate-fns locale for date formatting
readOnlybooleanfalseDisable event creation/editing
isLoadingbooleanfalseShow loading state

BasicScheduler Views

Month View

Traditional calendar grid showing all days in the current month. Events are displayed as colored bars.

Week View

7-day view with hourly grid. Shows event duration visually. Virtualized for performance.

Day View

Single day view with detailed hourly breakdown. 15-minute time slots for precise scheduling.

ProScheduler PropsPro

ProScheduler extends BasicScheduler with additional features. All Basic props are available plus:

ProScheduler Props Interface
// ProScheduler Props (includes all BasicScheduler props)
interface ProSchedulerProps extends BasicSchedulerProps {
  // Additional Views
  view?: 'month' | 'week' | 'day' | 'agenda' | 'resource';
  resources?: Resource[];

  // Drag & Drop
  onEventDrop?: (event: CalendarEvent, start: Date, end: Date) => void;
  onEventResize?: (event: CalendarEvent, start: Date, end: Date) => void;

  // Timezone
  timezone?: string;
  onTimezoneChange?: (timezone: string) => void;

  // Theme
  isDarkMode?: boolean;
  onThemeToggle?: () => void;

  // i18n
  language?: 'en' | 'fr';
  onLanguageChange?: (lang: 'en' | 'fr') => void;
  translations?: Partial<CalendarTranslations>;

  // Pro Features
  eventTypes?: EventType[];
  hideViewSwitcher?: boolean;
}
PropTypeDescription
timezonestringIANA timezone (e.g., 'America/New_York')
isDarkModebooleanEnable dark theme
language'en' | 'fr'UI language for built-in translations
translationsCalendarTranslationsCustom translation overrides
resourcesResource[]Resources for resource view
onEventDropfunctionCallback when event is dragged
hideViewSwitcherbooleanHide the view toggle buttons

ProScheduler ViewsPro

All Basic Views

Month, Week, and Day views with drag & drop support.

Agenda View Pro

List view showing upcoming events in chronological order. Perfect for quick overview.

Resource View Pro

Display events by resource (rooms, people, equipment). Ideal for booking systems.

ThemingPro

Customize colors, fonts, and border radius. Includes built-in dark mode support.

Custom Theme Configuration
const customTheme = {
  colors: {
    primary: '#6366f1',      // Primary accent color
    secondary: '#ec4899',    // Secondary color
    background: '#ffffff',   // Background color
    foreground: '#0f172a',   // Text color
    border: '#e2e8f0',       // Border color
    muted: '#f1f5f9',        // Muted backgrounds
    accent: '#f1f5f9',       // Accent backgrounds
  },
  fontFamily: 'Inter, sans-serif',
  borderRadius: '0.75rem',
};

<ProScheduler
  events={events}
  theme={customTheme}
  isDarkMode={isDarkMode}
  onThemeToggle={() => setIsDarkMode(!isDarkMode)}
/>

InternationalizationPro

Built-in support for English and French. Add custom translations for any language.

i18n Configuration
import { fr, de, es } from 'date-fns/locale';

// Custom translations
const customTranslations = {
  today: 'Heute',
  month: 'Monat',
  week: 'Woche',
  day: 'Tag',
  createEvent: 'Ereignis erstellen',
  editEvent: 'Ereignis bearbeiten',
  delete: 'Löschen',
  save: 'Speichern',
  cancel: 'Abbrechen',
  // ... more translations
};

<ProScheduler
  events={events}
  language="fr"                    // Built-in: 'en' | 'fr'
  locale={fr}                      // date-fns locale for date formatting
  translations={customTranslations} // Override specific strings
  onLanguageChange={(lang) => setLanguage(lang)}
/>

Timezone SupportPro

Display events in any timezone. Users can switch timezones on the fly.

Timezone Configuration
<ProScheduler
  events={events}
  timezone="America/New_York"      // IANA timezone
  onTimezoneChange={(tz) => {
    setTimezone(tz);
    // Events will automatically adjust to new timezone
  }}
/>

// Supported timezones include:
// - America/New_York
// - America/Los_Angeles
// - Europe/London
// - Europe/Paris
// - Asia/Tokyo
// - And all IANA timezone identifiers

Resource ViewPro

Display events by resource - perfect for room booking, team scheduling, or equipment allocation.

Resource View Setup
const resources = [
  { id: 'room-a', label: 'Conference Room A', color: '#3b82f6' },
  { id: 'room-b', label: 'Conference Room B', color: '#10b981' },
  { id: 'john', label: 'John Doe', color: '#f59e0b', avatar: '/avatars/john.jpg' },
];

const events = [
  {
    id: '1',
    title: 'Client Meeting',
    start: new Date(2025, 0, 15, 10, 0),
    end: new Date(2025, 0, 15, 11, 0),
    resourceId: 'room-a',  // Link event to resource
  },
];

<ProScheduler
  events={events}
  resources={resources}
  view="resource"
/>

Recurring EventsPro

Create events that repeat daily, weekly, monthly, or yearly. Supports count-based and date-based end rules.

Recurring Event Examples
const recurringEvents = [
  {
    id: '1',
    title: 'Daily Standup',
    start: new Date(2025, 0, 6, 9, 0),
    end: new Date(2025, 0, 6, 9, 30),
    recurrence: {
      freq: 'DAILY',
      interval: 1,      // Every 1 day
      count: 30,        // Repeat 30 times
    },
  },
  {
    id: '2',
    title: 'Weekly Team Meeting',
    start: new Date(2025, 0, 6, 14, 0),
    end: new Date(2025, 0, 6, 15, 0),
    recurrence: {
      freq: 'WEEKLY',
      interval: 1,
      until: new Date(2025, 12, 31), // End date
    },
  },
  {
    id: '3',
    title: 'Monthly Report',
    start: new Date(2025, 0, 1, 10, 0),
    end: new Date(2025, 0, 1, 11, 0),
    recurrence: {
      freq: 'MONTHLY',
      interval: 1,
      count: 12,
    },
  },
];

Recurrence Options

  • freq - Frequency: DAILY, WEEKLY, MONTHLY, YEARLY
  • interval - Repeat every N periods (default: 1)
  • count - Total number of occurrences
  • until - End date for recurrence

Custom Event Form

Replace the built-in event form with your own custom component.

Custom Event Form
<ProScheduler
  events={events}
  renderEventForm={({ isOpen, onClose, event, initialDate, onSave, onDelete }) => (
    <MyCustomModal isOpen={isOpen} onClose={onClose}>
      <MyEventForm
        event={event}
        initialDate={initialDate}
        onSave={(data) => {
          onSave(data);
          onClose();
        }}
        onDelete={event?.id ? () => {
          onDelete?.(event.id);
          onClose();
        } : undefined}
      />
    </MyCustomModal>
  )}
/>

Need help? Contact support

Back to home