Getting Started with SimpleCalendarJS

Adding a calendar to a web app sounds like a 20-minute task. Then you hit the docs for a popular library, spend an hour wiring up plugins, fight CSS specificity wars, and ship 200 KB of JavaScript just to show a month grid. Most calendar libraries were designed for enterprise scheduling tools — they bring that complexity with them whether you need it or not.

SimpleCalendarJS is different. It ships one file, has zero dependencies, and works in any JavaScript environment. Here is how to go from nothing to a fully functional calendar in under 10 lines of code.

Installation

npm (recommended for bundled projects)

npm install simple-calendar-js

CDN (for quick prototypes or plain HTML projects)

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/simple-calendar-js/dist/simple-calendar-js.min.css">
<script src="https://cdn.jsdelivr.net/npm/simple-calendar-js/dist/simple-calendar-js.min.js"></script>

Both paths give you the same API. Pick whatever fits your build setup.

Zero to calendar in 10 lines

Add a container to your HTML:

<div id="calendar"></div>

Then initialise the calendar:

import SimpleCalendarJs from 'simple-calendar-js';
import 'simple-calendar-js/dist/simple-calendar-js.min.css';

const calendar = new SimpleCalendarJs('#calendar', {
  defaultView: 'month',
  locale: 'en-US',
});

That is it. You have a rendered, navigable month calendar. No render call, no plugin registration, no boilerplate config object with 40 required keys.

Adding events

Events are loaded through a fetchEvents callback. The function receives the visible date range (start, end) so you can query only what you need — useful when your event store is large or lives behind an API.

const calendar = new SimpleCalendarJs('#calendar', {
  defaultView: 'month',
  locale: 'en-US',

  fetchEvents: async (start, end) => {
    // Replace this with a real fetch() call to your backend
    const response = await fetch(`/api/events?from=${start.toISOString()}&to=${end.toISOString()}`);
    const data = await response.json();

    // Shape the response into the SimpleCalendarJS event format
    return data.map(event => ({
      id: event.id,
      title: event.title,
      start: new Date(event.startAt),
      end: new Date(event.endAt),
      color: event.color ?? '#4f46e5',
    }));
  },
});

The required fields for each event object are:

• id — unique string or number
• title — displayed label
• start — JavaScript Date
• end — JavaScript Date
• allDay (optional) — boolean, renders as a full-day block
• color (optional) — hex or CSS color string

Handling interactions

Calendar interactions are just callbacks. No event bus, no custom event listeners to manage yourself.

const calendar = new SimpleCalendarJs('#calendar', {
  defaultView: 'month',
  locale: 'en-US',

  // User clicked an existing event
  onEventClick: (event) => {
    openEventModal({ id: event.id, title: event.title });
  },

  // User clicked an empty time slot
  onSlotClick: (date) => {
    openCreateModal({ defaultDate: date });
  },
});

onEventClick gives you the full event object you returned from fetchEvents. onSlotClick gives you the Date of the clicked slot — hand it straight to your create form as a default value and your UX immediately feels polished.

Switching views

Month, week, and day views are built in. You can let users toggle between them via the built-in toolbar, or drive the view programmatically — useful when you want your own UI controls outside the calendar.

// Configure which views are available in the toolbar
const calendar = new SimpleCalendarJs('#calendar', {
  defaultView: 'month',
  enabledViews: ['month', 'week', 'day'],
});

// Switch view from your own button
document.getElementById('btn-week').addEventListener('click', () => {
  calendar.setView('week');
});

document.getElementById('btn-day').addEventListener('click', () => {
  calendar.setView('day');
});

The calendar re-fetches events for the new visible range automatically when the view changes.

Customisation in 3 lines of CSS

The entire visual layer is driven by CSS custom properties. Override them on the .uc-calendar class and every element that uses them updates instantly — no digging through minified stylesheets or adding !important everywhere.

.uc-calendar {
  --cal-primary: #10b981;       /* accent colour: today highlight, selected slots */
  --cal-primary-dark: #059669;  /* hover/active states */
  --cal-today-bg: #d1fae5;      /* background of the current day cell */
  --cal-font-size: 14px;        /* base font size across the whole calendar */
}

Pair this with a dark-mode media query and you have full light/dark theming in under 15 lines of CSS total.

What's next

• Full API documentation — all options, methods, and event schemas in one place
• Interactive sandbox — experiment with views, locales, and theming live in the browser
• Dark mode, tooltips, and recurring events are covered in the advanced guides

Summary

• Install with npm install simple-calendar-js or drop in the CDN tags — no other dependencies required
• Initialise with a selector and an options object; the calendar renders immediately
• Load events lazily via the fetchEvents async callback, scoped to the visible date range
• Wire up onEventClick and onSlotClick to connect the calendar to your existing UI (modals, forms, sidebars)
• Switch between month, week, and day views programmatically or via the built-in toolbar
• Theme the entire calendar by overriding a handful of CSS custom properties on .uc-calendar