Customizing Calendar Themes

SimpleCalendarJS is built with customization at its core. Using CSS custom properties and a flexible theming system, you can match any design system in minutes.

Whether you need a subtle brand color update or a complete visual overhaul, the calendar adapts to your needs without fighting you.

Understanding CSS variables

SimpleCalendarJS exposes 60+ CSS custom properties that control every aspect of the calendar's appearance. Here are the most important ones:

:root {
  /* Primary Colors */
  --cal-primary: #facc15;
  --cal-primary-dark: #eab308;
  --cal-primary-light: #fef08a;

  /* Background Colors */
  --cal-bg: #ffffff;
  --cal-header-bg: #f5f5f4;
  --cal-today-bg: #fef3c7;
  --cal-selected-bg: #fef08a;

  /* Text Colors */
  --cal-text: #1c1917;
  --cal-text-secondary: #78716c;
  --cal-header-text: #292524;

  /* Border & Spacing */
  --cal-border: #e7e5e4;
  --cal-border-radius: 12px;
  --cal-spacing: 16px;

  /* Typography */
  --cal-font-family: system-ui, sans-serif;
  --cal-font-size: 14px;
  --cal-header-font-size: 16px;
}

You can override any of these in your own CSS to customize the calendar. Changes apply instantly without touching JavaScript.

Dark mode implementation

Dark mode is built-in. Just add the .uc-dark class to your calendar container:

<div id="calendar" class="uc-dark"></div>

Or toggle it dynamically with JavaScript:

const calendar = document.querySelector('#calendar');
calendar.classList.toggle('uc-dark');

The .uc-dark class automatically switches to a dark color palette with proper contrast ratios.

Complete theme examples

Here are three complete themes you can use as starting points:

Green theme

.uc-calendar {
  --cal-primary: #10b981;
  --cal-primary-dark: #059669;
  --cal-primary-light: #6ee7b7;
  --cal-today-bg: #d1fae5;
  --cal-selected-bg: #a7f3d0;
  --cal-hover-bg: #ecfdf5;
}

Blue theme

.uc-calendar {
  --cal-primary: #3b82f6;
  --cal-primary-dark: #2563eb;
  --cal-primary-light: #93c5fd;
  --cal-today-bg: #dbeafe;
  --cal-selected-bg: #bfdbfe;
  --cal-hover-bg: #eff6ff;
}

Purple theme

.uc-calendar {
  --cal-primary: #8b5cf6;
  --cal-primary-dark: #7c3aed;
  --cal-primary-light: #c4b5fd;
  --cal-today-bg: #ede9fe;
  --cal-selected-bg: #ddd6fe;
  --cal-hover-bg: #f5f3ff;
}

Dynamic theming with JavaScript

For advanced use cases, you can change themes programmatically at runtime:

function applyTheme(primaryColor) {
  const calendar = document.querySelector('#calendar');
  calendar.style.setProperty('--cal-primary', primaryColor);
  calendar.style.setProperty('--cal-primary-dark', darken(primaryColor, 10));
  calendar.style.setProperty('--cal-primary-light', lighten(primaryColor, 20));
}

// Usage
applyTheme('#ff6b6b');  // Red theme
applyTheme('#4ecdc4');  // Teal theme
applyTheme('#f7b731');  // Orange theme

SimpleCalendarJS includes built-in color utilities for generating harmonious color variations:

import { lighten, darken, hexToRgb } from 'simple-calendar-js/utils';

// Lighten a color by 20%
const lightBlue = lighten('#3b82f6', 20);  // #93c5fd

// Darken a color by 15%
const darkBlue = darken('#3b82f6', 15);    // #2563eb

// Convert hex to RGB for gradients
const rgb = hexToRgb('#3b82f6');           // { r: 59, g: 130, b: 246 }

Built-in color presets

SimpleCalendarJS ships with 8 carefully crafted color presets:

Indigo

#6366f1

Blue

#3b82f6

Green

#10b981

Orange

#f59e0b

Red

#ef4444

Pink

#ec4899

Purple

#8b5cf6

Cyan

#06b6d4

Best practices for theming

Test in both light and dark modes - Ensure proper contrast and readability
Use semantic color names - Primary, secondary, accent rather than specific hues
Maintain WCAG AA contrast ratios - At least 4.5:1 for text, 3:1 for UI elements
Keep animations consistent - Match your app's motion design system
Test with real data - Dense calendars reveal spacing and readability issues
Document your theme - Make it easy for your team to maintain consistency

Advanced customization

Beyond CSS variables, you can target specific calendar elements for granular control:

.uc-calendar {
  /* Customize toolbar */
  .uc-toolbar {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    padding: 20px;
  }

  /* Style event cells */
  .uc-event {
    border-radius: 8px;
    font-weight: 600;
    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
  }

  /* Highlight weekends */
  .uc-weekend {
    background-color: #fafafa;
  }

  /* Custom scrollbar */
  .uc-calendar-body::-webkit-scrollbar {
    width: 8px;
  }

  .uc-calendar-body::-webkit-scrollbar-thumb {
    background: var(--cal-primary);
    border-radius: 4px;
  }
}

Responsive theming

Adjust spacing, typography, and layout based on screen size:

/* Mobile */
@media (max-width: 768px) {
  .uc-calendar {
    --cal-font-size: 12px;
    --cal-spacing: 8px;
    --cal-border-radius: 8px;
  }
}

/* Tablet */
@media (min-width: 769px) and (max-width: 1024px) {
  .uc-calendar {
    --cal-font-size: 13px;
    --cal-spacing: 12px;
  }
}

/* Desktop */
@media (min-width: 1025px) {
  .uc-calendar {
    --cal-font-size: 14px;
    --cal-spacing: 16px;
    --cal-border-radius: 12px;
  }
}

Experiment with theming

Try different color schemes and customizations in the interactive sandbox.

Try the Sandbox Full Documentation