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);
  // Dynamically calculate darker and lighter variants
}

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

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;
  }
}

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;
  }
}

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

The theming system gives you complete control while maintaining consistency and accessibility.