Getting Started with SimpleCalendarJS

Add a beautiful, fully-featured calendar to your web app in minutes. No dependencies. No framework required. Just clean, lightweight JavaScript.

This guide walks you through everything you need to get SimpleCalendarJS running in your project.

Installation

Install SimpleCalendarJS via npm:

npm install simple-calendar-js

Basic setup

Import the library and its CSS file into your project:

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

Create a container element in your HTML:

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

Initialize the calendar:

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

That's it! You now have a working calendar in your application.

Adding events

Events are loaded via the fetchEvents callback function:

const calendar = new SimpleCalendarJs('#calendar', {
  fetchEvents: async (start, end) => {
    return [
      {
        id: '1',
        title: 'Team Meeting',
        start: new Date(2026, 1, 15, 9, 0),
        end: new Date(2026, 1, 15, 10, 0),
        color: '#4f46e5'
      },
      {
        id: '2',
        title: 'Product Launch',
        start: new Date(2026, 1, 20),
        end: new Date(2026, 1, 20),
        allDay: true,
        color: '#059669'
      }
    ];
  }
});

Each event requires:

id - Unique identifier
title - Event name
start - Start date/time
end - End date/time
color (optional) - Custom event color

Handling user interactions

Respond to clicks and other calendar interactions:

const calendar = new SimpleCalendarJs('#calendar', {
  onEventClick: (event) => {
    console.log('Event clicked:', event.title);
    // Open modal, show details, etc.
  },
  onSlotClick: (date) => {
    console.log('Empty slot clicked:', date);
    // Create new event, open form, etc.
  },
  onViewChange: (view) => {
    console.log('View changed to:', view);
  }
});

Multiple calendar views

SimpleCalendarJS supports three main views:

Month - Full month grid display
Week - 7-day view with hourly time slots
Day - Single day view with full-hour resolution

Switch views programmatically or let users toggle between them:

// Programmatic view switching
calendar.setView('week');
calendar.setView('day');

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

Customization

Configure locale, time format, and display options:

const calendar = new SimpleCalendarJs('#calendar', {
  locale: 'en-US',          // Supports 34+ locales
  weekStartsOn: 1,          // 0 = Sunday, 1 = Monday
  use24Hour: false,         // 12-hour vs 24-hour format
  weekdayFormat: 'short',   // 'narrow', 'short', or 'long'
  showToolbar: true,        // Show/hide toolbar
  showTodayButton: true,    // Show "Today" button
  showViewSwitcher: true    // Show view toggle buttons
});

Apply custom styling with CSS variables:

.uc-calendar {
  --cal-primary: #10b981;
  --cal-primary-dark: #059669;
  --cal-today-bg: #d1fae5;
  --cal-font-size: 14px;
}

What's next?

Explore the full documentation for advanced features
Try different configurations in the interactive sandbox
Learn about dark mode, tooltips, and custom themes
Integrate with React, Vue, or Angular using official components

Ready to dive deeper?

Explore the full API, experiment in the sandbox, or check out the source code.

Full Documentation Try the Sandbox