Documentation

<link rel="stylesheet" href="simple-calendar-js.css" />
<script src="simple-calendar-js.js"></script>

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

// Create a container in your HTML
<div id="calendar"></div>

// Initialize the calendar
const calendar = new SimpleCalendarJs('#calendar', {
  defaultView: 'month',
  weekStartsOn: 1, // 0 = Sunday, 1 = Monday
  locale: 'en-US',
  use24Hour: false,
  fetchEvents: async (start, end) => {
    // Fetch events from your API
    const response = await fetch(`/api/events?start=${start}&end=${end}`);
    return response.json();
  },
  onEventClick: (event) => {
    console.log('Event clicked:', event);
  },
  onSlotClick: (date) => {
    console.log('Empty slot clicked:', date);
  }
});

const calendar = new SimpleCalendarJs('#calendar', {
  mode: 'date-picker',
  onDateSelect: (date) => {
    console.log('Selected date:', date);
  }
});

// Get the selected date
const selectedDate = calendar.getSelectedDate();

// Set a date programmatically
calendar.setSelectedDate(new Date(2024, 5, 15));

// Clear selection
calendar.clearSelection();

const calendar = new SimpleCalendarJs('#calendar', {
  mode: 'range-picker',
  onRangeSelect: (startDate, endDate) => {
    console.log('Selected range:', startDate, 'to', endDate);
  }
});

// Get the selected range
const range = calendar.getSelectedRange();
// Returns: { start: Date, end: Date } or null

// Set a range programmatically
calendar.setSelectedRange(
  new Date(2024, 5, 10),
  new Date(2024, 5, 20)
);

// Clear selection
calendar.clearSelection();

{
  id: 'unique-id',           // Required: Unique identifier
  title: 'Event Title',      // Required: Event name (can contain HTML if allowHtmlInEvents is enabled)
  start: Date,               // Required: Start date/time
  end: Date,                 // Required: End date/time
  allDay: false,             // Optional: All-day event flag
  color: '#4f46e5',          // Optional: Custom background color (hex)
  textColor: '#ffffff',      // Optional: Custom text color (hex) - overrides autoContrastText
  borderColor: '#3730a3',    // Optional: Custom border color (hex) - used when showEventBorder is true
  allowHtml: true,           // Optional: Override global allowHtmlInEvents setting for this event
  description: 'Details',    // Optional: Event description (also used for tooltip)
  tooltip: 'Custom tooltip', // Optional: Custom tooltip text (overrides description)
  tooltipAllowHtml: true     // Optional: Override global tooltipAllowHtml setting for this event
}

const calendar = new SimpleCalendarJs('#calendar', {
  fetchEvents: async (start, end) => {
    return [
      {
        id: '1',
        title: 'Team Meeting',
        start: new Date(2024, 0, 15, 9, 15),  // 9:15 AM
        end: new Date(2024, 0, 15, 10, 45),   // 10:45 AM
        color: '#4f46e5'
      },
      {
        id: '2',
        title: 'Lunch Break',
        start: new Date(2024, 0, 15, 12, 30), // 12:30 PM
        end: new Date(2024, 0, 15, 13, 30),   // 1:30 PM
        allDay: false,
        color: '#059669'
      }
    ];
  },
  onEventClick: (event) => {
    alert(`Clicked: ${event.title}`);
  },
  onSlotClick: (date) => {
    console.log('Create event at:', date);
  }
});

// Server returns (stored in UTC):
{
  "title": "Team Meeting",
  "start": "2024-03-15T14:00:00Z",  // 2:00 PM UTC
  "end": "2024-03-15T15:00:00Z"     // 3:00 PM UTC
}

// User in New York (EST, UTC-5):
// Calendar displays: 9:00 AM - 10:00 AM

// User in London (GMT, UTC+0):
// Calendar displays: 2:00 PM - 3:00 PM

// User in Tokyo (JST, UTC+9):
// Calendar displays: 11:00 PM - 12:00 AM

{
  "events": [
    {
      "id": 1,
      "title": "Global Team Standup",
      "start": "2024-03-15T14:00:00Z",
      "end": "2024-03-15T14:30:00Z",
      "description": "Daily standup - all timezones welcome"
    }
  ]
}

const events = [
  {
    id: 1,
    title: 'Team Meeting',
    start: new Date(2024, 2, 15, 10, 0),
    end: new Date(2024, 2, 15, 11, 0),
    tooltip: 'Weekly team sync\nDiscuss Q1 roadmap'  // Custom tooltip
  },
  {
    id: 2,
    title: 'Client Call',
    start: new Date(2024, 2, 15, 14, 0),
    end: new Date(2024, 2, 15, 15, 0),
    description: 'Requirements gathering\nPrepare demo'  // Used as tooltip
  },
  {
    id: 3,
    title: 'Code Review',
    start: new Date(2024, 2, 15, 16, 0),
    end: new Date(2024, 2, 15, 17, 0)
    // No tooltip/description - will show title
  }
];

{
  id: 1,
  title: 'Project Kickoff',
  start: new Date(2024, 2, 20, 9, 0),
  end: new Date(2024, 2, 20, 10, 30),
  tooltip: 'Project Kickoff Meeting\n\nAgenda:\n- Introductions\n- Timeline review\n- Q&A session\n\nLocation: Conference Room A'
}

{
  id: 1,
  title: 'Design Review',
  start: new Date(2024, 2, 20, 14, 0),
  end: new Date(2024, 2, 20, 15, 30),
  tooltip: '<b>Product Design Review</b><br><br><i>New feature mockups:</i><br>• Dashboard v2.0<br>• Mobile redesign<br><br><a href="https://figma.com/example">View in Figma</a>'
}

const calendar = new SimpleCalendarJs('#calendar', {
  showTooltips: true,           // Enable/disable tooltips (default: true)
  tooltipAllowHtml: true,       // Allow HTML in tooltips (default: true)
  tooltipBgColor: '#1f2937',    // Custom background color (default: null)
  tooltipTextColor: '#f9fafb',  // Custom text color (default: null)
  tooltipMaxWidth: 250,         // Maximum width in pixels (default: 250)
  tooltipDelay: 400,            // Hover delay in milliseconds (default: 400)
  fetchEvents: async (start, end) => { /* ... */ }
});

{
  id: 1,
  title: 'Secure Event',
  tooltip: '<script>alert("xss")</script>',  // This will be sanitized/removed
  tooltipAllowHtml: false  // Force plain text for this event only
}

{
  id: 1,
  title: 'Client Demo',
  start: new Date(2024, 2, 25, 10, 0),
  end: new Date(2024, 2, 25, 11, 0),
  tooltip: `
    <span style="color: #ef4444;"><b>⚡ HIGH PRIORITY</b></span><br><br>
    <b>Q4 Business Review</b><br>
    <i>Executive presentation</i><br><br>
    <b>Must prepare:</b><br>
    • Financial projections<br>
    • ROI analysis<br>
    • Growth charts<br><br>
    <a href="https://example.com/deck">View presentation deck</a>
  `,
  tooltipAllowHtml: true
}

const calendar = new SimpleCalendarJs('#calendar', {
  showTooltips: false,  // Disable all tooltips
  fetchEvents: async (start, end) => { /* ... */ }
});

:root {
  --cal-tooltip-bg: #1f2937;           /* Background color */
  --cal-tooltip-text: #f9fafb;         /* Text color */
  --cal-tooltip-border: #374151;       /* Border color */
  --cal-tooltip-max-width: 250px;      /* Maximum width */
  --cal-tooltip-padding: 8px 12px;     /* Inner padding */
  --cal-tooltip-radius: 6px;           /* Border radius */
  --cal-tooltip-font-size: 12px;       /* Font size */
  --cal-tooltip-offset: 8px;           /* Distance from event */
  --cal-tooltip-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);  /* Shadow */
}

const calendar = new SimpleCalendarJs('#calendar', {
  tooltipBgColor: '#dc2626',      // Red background
  tooltipTextColor: '#ffffff',    // White text
});

const calendar = new SimpleCalendarJs('#calendar', {
  enableDragDrop: true,  // Enable moving events
  enableResize: true,     // Enable resizing events

  onEventDrop: (event, oldStart, oldEnd, newStart, newEnd) => {
    // Detect if this is a move or resize
    const isMoved = oldStart.getTime() !== newStart.getTime();
    const isResized = oldEnd.getTime() !== newEnd.getTime() && !isMoved;

    if (isMoved) {
      console.log(`Event "${event.title}" moved to ${newStart}`);
    } else if (isResized) {
      console.log(`Event "${event.title}" resized to end at ${newEnd}`);
    }

    // Update your backend
    await fetch(`/api/events/${event.id}`, {
      method: 'PATCH',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        start: newStart.toISOString(),
        end: newEnd.toISOString(),
        allDay: event.allDay
      })
    });
  }
});

const calendar = new SimpleCalendarJs('#calendar', {
  monthTimedEventStyle: 'list',  // Default
  showTimeInItems: true           // Shows time next to dot
});

const calendar = new SimpleCalendarJs('#calendar', {
  monthTimedEventStyle: 'block'
});

// HTML with fixed height
<div id="calendar" style="height: 600px;"></div>

// Calendar automatically limits events to fit the available space
const calendar = new SimpleCalendarJs('#calendar', {
  defaultView: 'month'
});

// HTML with natural height
<div id="calendar" style="height: auto;"></div>

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

// All events displayed, rows adapt to content
const calendar = new SimpleCalendarJs('#calendar', {
  defaultView: 'month'
});

const calendar = new SimpleCalendarJs('#calendar', {
  autoContrastText: true,     // Enable automatic text color calculation
  contrastLevel: 'medium',    // Choose: 'high', 'medium', or 'low'
  fetchEvents: async (start, end) => {
    return [
      {
        id: 1,
        title: 'Team Meeting',
        start: new Date('2024-03-15T10:00:00'),
        color: '#ffeb3b'  // Yellow background → auto-calculated dark yellow text
      },
      {
        id: 2,
        title: 'Project Review',
        start: new Date('2024-03-16T14:00:00'),
        color: '#1a237e'  // Dark blue background → auto-calculated light blue text
      }
    ];
  }
});

{
  id: 1,
  title: 'Special Event',
  start: new Date('2024-03-15T10:00:00'),
  color: '#4caf50',      // Green background
  textColor: '#ffeb3b'   // Force yellow text (overrides auto-contrast)
}

const calendar = new SimpleCalendarJs('#calendar', {
  allowHtmlInEvents: true,  // Enable HTML rendering
  fetchEvents: async (start, end) => {
    return [
      {
        id: 1,
        title: '<b>Important</b> Meeting',
        start: new Date('2024-03-15T10:00:00')
      },
      {
        id: 2,
        title: 'Design <i>Review</i>',
        start: new Date('2024-03-16T14:00:00')
      }
    ];
  }
});

{
  id: 1,
  title: '<i class="fas fa-video"></i> Video Call',
  start: new Date('2024-03-15T10:00:00')
}

{
  id: 2,
  title: '<i class="fas fa-plane"></i> Flight to NYC',
  start: new Date('2024-03-16T14:00:00'),
  allDay: true
}

{
  id: 3,
  title: '<i class="fas fa-birthday-cake"></i> <b>Sarah</b> Birthday',
  start: new Date('2024-03-20T00:00:00'),
  allDay: true
}

const calendar = new SimpleCalendarJs('#calendar', {
  allowHtmlInEvents: false,  // Disabled globally
  fetchEvents: async (start, end) => {
    return [
      {
        id: 1,
        title: 'Regular Meeting',  // Plain text
        start: new Date('2024-03-15T10:00:00')
      },
      {
        id: 2,
        title: '<i class="fas fa-star"></i> <b>VIP</b> Client Call',
        start: new Date('2024-03-16T14:00:00'),
        allowHtml: true  // Enable HTML only for this event
      }
    ];
  }
});

const calendar = new SimpleCalendarJs('#calendar', {
  defaultView: 'list',              // Start in list view
  enabledViews: ['month', 'week', 'day', 'list'], // Include list in views
  listDaysForward: 30              // Show next 30 days (default)
});

// Show next 90 days in list view
new SimpleCalendarJs('#calendar', {
  defaultView: 'list',
  enabledViews: ['month', 'list'],  // Only month and list views
  listDaysForward: 90,
  fetchEvents: async (start, end) => {
    // Your event fetching logic
  }
});

const calendar = new SimpleCalendarJs('#calendar', { /* options */ });

// Switch to week view
calendar.setView('week');

// Navigate to next week
calendar.navigate(1);

// Jump to a specific date
calendar.goToDate(new Date(2024, 5, 15));

// Go to today
calendar.goToToday();

// Refresh calendar (clear cache and re-fetch)
calendar.refresh();

// Cleanup when done
calendar.destroy();

// Month view Feb 2026: Fetches Jan 28 - Mar 1 (full month grid)
calendar.setView('month');  // ✓ Fetch: Jan 28 - Mar 1

// Switch to week view (Feb 20-26): Already in cache, no fetch
calendar.setView('week');   // ✗ No fetch (instant)

// Switch to day view (Feb 22): Already in cache, no fetch
calendar.setView('day');    // ✗ No fetch (instant)

// Navigate next week (Feb 27 - Mar 5): Extends beyond cache
// Fetches March's full month grid (Mar 1 - Apr 5)
calendar.navigate(1);       // ✓ Fetch: Mar 1 - Apr 5

// Navigate next week (Mar 6-12): Already in March's cache
calendar.navigate(1);       // ✗ No fetch (instant)

// Navigate previous week (Feb 27 - Mar 5): Partially outside cache
// Fetches February's full month grid (Jan 28 - Mar 1)
calendar.navigate(-1);      // ✓ Fetch: Jan 28 - Mar 1

// After external event changes, refresh to clear cache
addEventToDatabase(newEvent);
calendar.refresh();         // ✓ Fetch (clears cache)

// Restore saved preferences or use defaults
const savedView = localStorage.getItem('calendarView') || 'month';
const savedDate = localStorage.getItem('calendarDate');

const calendar = new SimpleCalendarJs('#calendar', {
  defaultView: savedView,
  defaultDate: savedDate ? new Date(savedDate) : null,

  // Save view changes
  onViewChange: (view) => {
    localStorage.setItem('calendarView', view);
  },

  // Save navigation (current date)
  onNavigate: (startDate) => {
    localStorage.setItem('calendarDate', startDate.toISOString());
  }
});

// Same as localStorage but survives only for the current tab/session
const calendar = new SimpleCalendarJs('#calendar', {
  defaultView: sessionStorage.getItem('calendarView') || 'month',
  onViewChange: (view) => sessionStorage.setItem('calendarView', view),
  onNavigate: (start) => sessionStorage.setItem('calendarDate', start.toISOString())
});

// Read from URL
const params = new URLSearchParams(window.location.search);
const view = params.get('view') || 'month';
const date = params.get('date') ? new Date(params.get('date')) : null;

const calendar = new SimpleCalendarJs('#calendar', {
  defaultView: view,
  defaultDate: date,

  onViewChange: (newView) => {
    const url = new URL(window.location);
    url.searchParams.set('view', newView);
    window.history.pushState({}, '', url);
  },

  onNavigate: (startDate) => {
    const url = new URL(window.location);
    url.searchParams.set('date', startDate.toISOString().split('T')[0]);
    window.history.pushState({}, '', url);
  }
});

function MyCalendar() {
  const [view, setView] = useState(
    () => localStorage.getItem('calendarView') || 'month'
  );

  const [currentDate, setCurrentDate] = useState(
    () => {
      const saved = localStorage.getItem('calendarDate');
      return saved ? new Date(saved) : new Date();
    }
  );

  const handleViewChange = (newView) => {
    setView(newView);
    localStorage.setItem('calendarView', newView);
  };

  const handleNavigate = (startDate) => {
    setCurrentDate(startDate);
    localStorage.setItem('calendarDate', startDate.toISOString());
  };

  return (
    <SimpleCalendarJsReact
      defaultView={view}
      defaultDate={currentDate}
      onViewChange={handleViewChange}
      onNavigate={handleNavigate}
      fetchEvents={fetchEvents}
    />
  );
}

// composables/useCalendarPreferences.js
import { ref, watch } from 'vue';

export function useCalendarPreferences() {
  const view = ref(localStorage.getItem('calendarView') || 'month');
  const currentDate = ref(
    localStorage.getItem('calendarDate')
      ? new Date(localStorage.getItem('calendarDate'))
      : new Date()
  );

  watch(view, (newView) => {
    localStorage.setItem('calendarView', newView);
  });

  watch(currentDate, (newDate) => {
    localStorage.setItem('calendarDate', newDate.toISOString());
  });

  return { view, currentDate };
}

// In component
<script setup>
import { useCalendarPreferences } from './composables/useCalendarPreferences';
const { view, currentDate } = useCalendarPreferences();

const handleViewChange = (newView) => {
  view.value = newView;
};

const handleNavigate = (startDate) => {
  currentDate.value = startDate;
};
</script>

<template>
  <SimpleCalendarJsVue
    :defaultView="view"
    :defaultDate="currentDate"
    @viewChange="handleViewChange"
    @navigate="handleNavigate"
  />
</template>

// Load preferences from your API
const preferences = await fetch('/api/user/calendar-preferences').then(r => r.json());

const calendar = new SimpleCalendarJs('#calendar', {
  defaultView: preferences.view || 'month',
  defaultDate: preferences.lastViewedDate ? new Date(preferences.lastViewedDate) : null,

  onViewChange: async (view) => {
    // Debounce to avoid too many API calls
    clearTimeout(window.savePreferencesTimeout);
    window.savePreferencesTimeout = setTimeout(() => {
      fetch('/api/user/calendar-preferences', {
        method: 'PATCH',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ view })
      });
    }, 1000);
  }
});

// Enable dark mode
calendar._root.classList.add('uc-dark');

// Disable dark mode
calendar._root.classList.remove('uc-dark');

// Toggle dark mode
calendar._root.classList.toggle('uc-dark', isDark);

.uc-calendar {
  /* Primary color */
  --cal-primary: #10b981;           /* Green theme */
  --cal-primary-dark: #059669;
  --cal-primary-light: #d1fae5;

  /* Today indicator */
  --cal-today-bg: #d1fae5;
  --cal-today-text: #059669;
}

.uc-calendar.uc-dark {
  /* Dark mode colors */
  --cal-bg: #1f2937;
  --cal-bg-secondary: #111827;
  --cal-text: #f9fafb;
  --cal-border: #374151;

  /* Dark mode today/selected indicators */
  --cal-today-bg: #065f46;          /* Custom dark green */
  --cal-selected-bg: #047857;
}

/* Light mode - Yellow theme */
.uc-calendar {
  --cal-primary: #eab308;           /* yellow-500 */
  --cal-primary-dark: #ca8a04;      /* yellow-600 */
  --cal-primary-light: #fef9c3;     /* yellow-100 */
  --cal-today-bg: #fef9c3;
  --cal-today-text: #854d0e;
}

/* Dark mode - Yellow theme */
.uc-calendar.uc-dark {
  --cal-primary: #eab308;
  --cal-primary-dark: #facc15;
  --cal-primary-light: #713f12;
  --cal-today-bg: #713f12;          /* yellow-900 */
  --cal-selected-bg: #854d0e;       /* yellow-800 */
}

import SimpleCalendarJsReact from './simple-calendar-js-react.jsx';
import './simple-calendar-js.css';

import { useState } from 'react';
import SimpleCalendarJsReact from './simple-calendar-js-react.jsx';

function App() {
  const [isDark, setIsDark] = useState(false);

  const fetchEvents = async (start, end) => {
    const response = await fetch(`/api/events?start=${start}&end=${end}`);
    return response.json();
  };

  const handleEventClick = (event) => {
    console.log('Event clicked:', event);
  };

  return (
    <>
      <button onClick={() => setIsDark(!isDark)}>
        Toggle Theme
      </button>
      <SimpleCalendarJsReact
        defaultView="month"
        defaultDate={new Date(2024, 5, 15)}
        weekStartsOn={1}
        darkMode={isDark}
        fetchEvents={fetchEvents}
        onEventClick={handleEventClick}
        onSlotClick={(date) => console.log('Slot clicked:', date)}
        onViewChange={(view) => console.log('View changed:', view)}
        style={{ height: '600px' }}
      />
    </>
  );
}

import { useRef } from 'react';

function App() {
  const calRef = useRef();

  const handleNextWeek = () => {
    calRef.current.setView('week');
    calRef.current.navigate(1);
  };

  return (
    <>
      <button onClick={handleNextWeek}>Next Week</button>
      <SimpleCalendarJsReact ref={calRef} />
    </>
  );
}

import SimpleCalendarJsVue from './simple-calendar-js-vue.js';
import './simple-calendar-js.css';

<script setup>
import { ref } from 'vue';
import SimpleCalendarJsVue from './simple-calendar-js-vue.js';

const isDark = ref(false);

const fetchEvents = async (start, end) => {
  const response = await fetch(`/api/events?start=${start}&end=${end}`);
  return response.json();
};

const handleEventClick = (event) => {
  console.log('Event clicked:', event);
};
</script>

<template>
  <button @click="isDark = !isDark">Toggle Theme</button>
  <SimpleCalendarJsVue
    :defaultView="'month'"
    :defaultDate="new Date(2024, 5, 15)"
    :weekStartsOn="1"
    :darkMode="isDark"
    :fetchEvents="fetchEvents"
    @eventClick="handleEventClick"
    @slotClick="(date) => console.log('Slot clicked:', date)"
    @viewChange="(view) => console.log('View changed:', view)"
    :style="{ height: '600px' }"
  />
</template>

<script setup>
import { ref } from 'vue';

const calendarRef = ref();

const handleNextWeek = () => {
  calendarRef.value.setView('week');
  calendarRef.value.navigate(1);
};
</script>

<template>
  <button @click="handleNextWeek">Next Week</button>
  <SimpleCalendarJsVue ref="calendarRef" />
</template>

import { SimpleCalendarJsComponent } from './simple-calendar-js-angular.component';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [SimpleCalendarJsComponent],
  // ...
})

import { Component } from '@angular/core';
import { SimpleCalendarJsComponent } from './simple-calendar-js-angular.component';

@Component({
  selector: 'app-calendar-demo',
  standalone: true,
  imports: [SimpleCalendarJsComponent],
  template: `
    <button (click)="isDark = !isDark">Toggle Theme</button>
    <simple-calendar-js
      [defaultView]="'month'"
      [defaultDate]="new Date(2024, 5, 15)"
      [weekStartsOn]="1"
      [darkMode]="isDark"
      [fetchEvents]="fetchEvents"
      (eventClick)="handleEventClick($event)"
      (slotClick)="handleSlotClick($event)"
      (viewChange)="handleViewChange($event)"
      [customStyle]="{ height: '600px' }"
    ></simple-calendar-js>
  `
})
export class CalendarDemoComponent {
  isDark = false;

  fetchEvents = async (start: Date, end: Date) => {
    const response = await fetch(`/api/events?start=${start}&end=${end}`);
    return response.json();
  };

  handleEventClick(event: any) {
    console.log('Event clicked:', event);
  }

  handleSlotClick(date: Date) {
    console.log('Slot clicked:', date);
  }

  handleViewChange(view: string) {
    console.log('View changed:', view);
  }
}

import { Component, ViewChild } from '@angular/core';
import { SimpleCalendarJsComponent } from './simple-calendar-js-angular.component';

@Component({
  // ...
})
export class CalendarDemoComponent {
  @ViewChild(SimpleCalendarJsComponent) calendar!: SimpleCalendarJsComponent;

  handleNextWeek() {
    this.calendar.setView('week');
    this.calendar.navigate(1);
  }
}

.my-green-calendar {
  --cal-primary: #10b981;
  --cal-primary-dark: #059669;
  --cal-primary-light: #d1fae5;
}

.my-calendar {
  --cal-font-size: 14px;
  --cal-event-height: 26px;
}

/* Target all events */
.uc-calendar .uc-event {
  border-radius: 6px;
  font-weight: 600;
}

/* Target timed events in week/day view */
.uc-calendar .uc-timed-event {
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}