Basic Scheduler Calendar

A lightweight, performant React calendar component

Built with modern web technologies • Fully customizable • Production-ready

View Demo • Documentation • Report Bug • See the pro version

Features

Multiple Views

Switch seamlessly between Month, Week, and Day views

Theme Support

Built-in dark mode with customizable CSS variables

Mobile First

Responsive design with swipe navigation and touch-optimized interactions

High Performance

Virtualized rendering handles 10,000+ events smoothly

Event Overlap Detection

Smart collision detection displays overlapping events side-by-side

Custom Event Rendering

Full control over event appearance with render props

Quick Start

Installation

npm install calendarkit-basic

yarn add calendarkit-basic

pnpm add calendarkit-basic

Basic Usage

import { BasicScheduler } from "calendarkit-basic";
import { useState } from "react";

function MyCalendar() {
  const [events, setEvents] = useState([]);
  const [view, setView] = useState("week");
  const [date, setDate] = useState(new Date());

  return (
    <div style={{ height: "700px" }}>
      <BasicScheduler
        events={events}
        view={view}
        onViewChange={setView}
        date={date}
        onDateChange={setDate}
        onEventCreate={(event) => setEvents([...events, { ...event, id: crypto.randomUUID() }])}
        onEventUpdate={(updatedEvent) => {
          setEvents(events.map(e => e.id === updatedEvent.id ? updatedEvent : e));
        }}
        onEventDelete={(eventId) => {
          setEvents(events.filter(e => e.id !== eventId));
        }}
      />
    </div>
  );
}

Documentation

For complete documentation, including advanced usage, customization options, and API reference, visit:

Full Documentation

Core API

Scheduler Component

| Prop | Type | Required | Description | |------|------|----------|-------------| | events | CalendarEvent[] | Yes | Array of events to display | | view | 'month' \| 'week' \| 'day' | No | Current view mode (default: 'week') | | onViewChange | (view: ViewType) => void | No | Callback when view changes | | date | Date | No | Currently focused date | | onDateChange | (date: Date) => void | No | Callback when date changes | | calendars | Calendar[] | No | Calendar definitions for filtering | | onCalendarToggle | (id: string, active: boolean) => void | No | Callback for calendar visibility | | onEventCreate | (event: Partial<CalendarEvent>) => void | No | Callback when creating event | | onEventUpdate | (event: CalendarEvent) => void | No | Callback when updating event | | onEventDelete | (eventId: string) => void | No | Callback when deleting event | | onEventClick | (event: CalendarEvent) => void | No | Callback when clicking an event | | weekStartsOn | 0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 | No | First day of week (0=Sunday, 1=Monday, etc.) | | readOnly | boolean | No | Disable event creation/editing | | isLoading | boolean | No | Show loading overlay | | renderEvent | (props) => ReactNode | No | Custom event renderer | | renderEventForm | (props) => ReactNode | No | Custom event form | | theme | ThemeConfig | No | Theme customization |

Event Type

interface CalendarEvent {
  id: string;
  title: string;
  start: Date;
  end: Date;
  color?: string;
  calendarId?: string;
  description?: string;
  allDay?: boolean;
}

Calendar Type

interface Calendar {
  id: string;
  label: string;
  color: string;
  active: boolean;
}

New in v1.0.0

Event Overlap Detection

Events scheduled at the same time are automatically displayed side-by-side with smart collision detection.

// No configuration needed - works automatically!
<BasicScheduler events={overlappingEvents} />

Week Start Configuration

Configure which day the week starts on:

<BasicScheduler
  weekStartsOn={1} // Monday
  // 0 = Sunday (default)
  // 1 = Monday
  // 6 = Saturday
/>

Custom Event Renderer

Full control over how events are displayed:

<BasicScheduler
  renderEvent={({ event, view, onClick }) => (
    <div
      onClick={onClick}
      className="my-custom-event"
      style={{ backgroundColor: event.color }}
    >
      <strong>{event.title}</strong>
      {view !== 'month' && (
        <span>{format(event.start, 'h:mm a')}</span>
      )}
    </div>
  )}
/>

Loading States

Built-in skeleton components for loading states:

import { BasicScheduler, CalendarSkeleton } from "calendarkit-basic";

function MyCalendar() {
  const { events, isLoading } = useEvents();

  if (isLoading) {
    return <CalendarSkeleton />;
  }

  return <BasicScheduler events={events} />;
}

Available skeleton components:

• CalendarSkeleton - Full calendar skeleton
• MonthViewSkeleton - Month view only
• WeekViewSkeleton - Week view only
• DayViewSkeleton - Day view only

Empty State

Display a friendly message when there are no events:

import { BasicScheduler, EmptyState } from "calendarkit-basic";

function MyCalendar() {
  const { events } = useEvents();

  if (events.length === 0) {
    return (
      <EmptyState
        title="No events yet"
        description="Create your first event to get started"
        actionLabel="Create Event"
        onCreateEvent={() => openCreateModal()}
      />
    );
  }

  return <BasicScheduler events={events} />;
}

Theming

BasicScheduler uses CSS variables for easy theming. Customize by overriding these variables:

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 221.2 83.2% 53.3%;
  --primary-foreground: 210 40% 98%;
  --border: 214.3 31.8% 91.4%;
  /* ... and more */
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  /* ... dark theme overrides */
}

See full theming guide

Examples

With Multiple Calendars

const [calendars, setCalendars] = useState([
  { id: "work", label: "Work", color: "#3b82f6", active: true },
  { id: "personal", label: "Personal", color: "#10b981", active: true },
  { id: "birthdays", label: "Birthdays", color: "#f59e0b", active: false },
]);

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

Read-Only Mode

<BasicScheduler
  events={events}
  readOnly={true}
/>

Week Starting on Monday

<BasicScheduler
  events={events}
  weekStartsOn={1}
/>

With Loading State

<BasicScheduler
  events={events}
  isLoading={isFetching}
/>

More examples

What's Included

• Month View - Grid layout with event pills
• Week View - Hourly timeline with overlap detection
• Day View - Detailed single-day timeline
• Event CRUD - Create, read, update, delete operations
• Event View Modal - Read-only event details with edit/delete options
• Calendar Filters - Toggle multiple calendar visibility
• Mobile Support - Swipe navigation and bottom sheet
• Dark Mode - Built-in theme switching
• TypeScript - Full type definitions
• Virtualization - Handles thousands of events
• Custom Rendering - Bring your own event components
• Loading Skeletons - Built-in loading states
• Empty States - Friendly no-content messaging

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feat/name-of-feature)
3. Commit your Changes (git commit -m 'Add some name-of-feature')
4. Push to the Branch (git push origin feat/name-of-feature)
5. Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/Zesor/calendarkit-basic.git

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

Links

• Website: calendarkit.io
• Documentation: calendarkit.io/docs
• npm Package: npmjs.com/package/calendarkit-basic
• Issues: GitHub Issues

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you find this project helpful, please consider giving it a star on GitHub!

Built with love by the CalendarKit Team

Website • Docs • GitHub