Theming

Overview

forceCalendar uses CSS custom properties (CSS variables) for theming. All variables use the --fc- prefix. Because components use Shadow DOM, theme variables must be set on the host element or inherited from a parent.

forcecal-main {
  --fc-primary-color: #1a73e8;
  --fc-background: #ffffff;
  --fc-text-color: #202124;
  --fc-font-family: 'Inter', sans-serif;
}

StyleUtils

The StyleUtils class provides programmatic access to the theming system.

import { StyleUtils } from '@forcecalendar/interface';

setCSSVariables(variables, element)

Set multiple CSS variables on an element. element defaults to document.documentElement.

StyleUtils.setCSSVariables({
  '--fc-primary-color': '#1a73e8',
  '--fc-background': '#1e1e1e',
  '--fc-text-color': '#e0e0e0',
}, calendarEl);

getCSSVariable(name, element)

Read a CSS variable value. element defaults to document.documentElement.

const primary = StyleUtils.getCSSVariable('--fc-primary-color', calendarEl);

Color Utilities

StyleUtils.darken('#4285f4', 0.2);     // Darken by 20%
StyleUtils.lighten('#4285f4', 0.2);    // Lighten by 20%
StyleUtils.getContrastColor('#4285f4'); // Returns '#ffffff' or '#000000'
StyleUtils.hexToRgba('#4285f4', 0.5);  // 'rgba(66, 133, 244, 0.5)'

sanitizeColor(color, fallback)

Validates and sanitizes a CSS color value to prevent CSS injection. Accepts hex colors, var(--*) references, rgb()/rgba() with numeric components, and a whitelist of safe color keywords. Invalid input returns the fallback value, which defaults to 'var(--fc-primary-color)'.

StyleUtils.sanitizeColor('#4285f4');                    // '#4285f4'
StyleUtils.sanitizeColor('url(evil)');                  // 'var(--fc-primary-color)' (rejected)
StyleUtils.sanitizeColor('red; background: url(evil)'); // 'var(--fc-primary-color)' (rejected)
StyleUtils.sanitizeColor('bad-value', '#000000');       // '#000000' (custom fallback)

CSS Variable Reference

Colors

Variable	Default	Description
`--fc-primary-color`	`#2563EB`	Primary accent color
`--fc-primary-hover`	`#1D4ED8`	Primary hover state
`--fc-primary-light`	`#EFF6FF`	Light primary for backgrounds
`--fc-background`	`#FFFFFF`	Main background
`--fc-background-alt`	`#FAFAFA`	Alternate background
`--fc-background-hover`	`#F3F4F6`	Hover background
`--fc-background-active`	`#E5E7EB`	Active/pressed background
`--fc-text-color`	`#111827`	Primary text color
`--fc-text-secondary`	`#6B7280`	Secondary text
`--fc-text-light`	`#9CA3AF`	Light/muted text
`--fc-border-color`	`#E5E7EB`	Border color
`--fc-border-color-hover`	`#D1D5DB`	Border hover color
`--fc-accent-color`	`#F59E0B`	Accent color
`--fc-danger-color`	`#EF4444`	Danger/error color
`--fc-success-color`	`#10B981`	Success color

Typography

Variable	Default	Description
`--fc-font-family`	`Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif`	Font family
`--fc-font-size-xs`	`11px`	Extra small text
`--fc-font-size-sm`	`12px`	Small text
`--fc-font-size-base`	`13px`	Base text
`--fc-font-size-lg`	`15px`	Large text
`--fc-font-size-xl`	`18px`	Extra large
`--fc-font-size-2xl`	`24px`	Double extra large
`--fc-font-weight-normal`	`400`	Normal weight
`--fc-font-weight-medium`	`500`	Medium weight
`--fc-font-weight-semibold`	`600`	Semibold weight
`--fc-font-weight-bold`	`700`	Bold weight
`--fc-line-height`	`1.4`	Line height

Spacing

Variable	Default	Description
`--fc-spacing-xs`	`2px`	Extra small
`--fc-spacing-sm`	`6px`	Small
`--fc-spacing-md`	`10px`	Medium
`--fc-spacing-lg`	`14px`	Large
`--fc-spacing-xl`	`20px`	Extra large
`--fc-spacing-2xl`	`28px`	Double extra large

Borders

Variable	Default	Description
`--fc-border-width`	`1px`	Border width
`--fc-border-radius-sm`	`3px`	Small radius
`--fc-border-radius`	`5px`	Standard radius
`--fc-border-radius-lg`	`8px`	Large radius
`--fc-border-radius-full`	`9999px`	Fully rounded

Shadows

Variable	Default	Description
`--fc-shadow-sm`	`0 1px 1px rgba(0,0,0,0.05)`	Small shadow
`--fc-shadow`	`0 1px 3px rgba(0,0,0,0.1), 0 1px 2px rgba(0,0,0,0.06)`	Standard shadow
`--fc-shadow-md`	`0 4px 6px -1px rgba(0, 0, 0, 0.1)`	Medium shadow
`--fc-shadow-lg`	`0 10px 15px -3px rgba(0, 0, 0, 0.1)`	Large shadow

Transitions

Variable	Default	Description
`--fc-transition-fast`	`100ms ease-out`	Fast transition
`--fc-transition`	`150ms ease-out`	Standard transition
`--fc-transition-slow`	`250ms ease-out`	Slow transition

Z-Index

Variable	Default	Description
`--fc-z-dropdown`	`1000`	Dropdowns
`--fc-z-modal`	`2000`	Modals
`--fc-z-tooltip`	`3000`	Tooltips

Dark Mode Example

forcecal-main.dark {
  --fc-background: #1e1e1e;
  --fc-background-alt: #2d2d2d;
  --fc-background-hover: #3d3d3d;
  --fc-background-active: #1a3a5c;
  --fc-text-color: #e0e0e0;
  --fc-text-secondary: #a0a0a0;
  --fc-text-light: #666666;
  --fc-border-color: #404040;
  --fc-border-color-hover: #555555;
  --fc-primary-light: #1a3a5c;
  --fc-shadow-sm: 0 1px 2px rgba(0,0,0,0.3);
  --fc-shadow-md: 0 2px 4px rgba(0,0,0,0.4);
}

Responsive Design

@media (max-width: 768px) {
  forcecal-main {
    --fc-font-size-base: 12px;
    --fc-spacing-md: 8px;
    --fc-spacing-lg: 12px;
  }
}

Style Functions

StyleUtils also provides functions for generating base styles used by components:

Function	Description
`getBaseStyles()`	Core layout and typography styles
`getButtonStyles()`	Button component styles
`getGridStyles()`	Month/week/day grid styles
`getAnimations()`	Keyframe animation definitions
`mediaQuery(breakpoint, styles)`	Wrap `styles` in a `min-width` media query for the named breakpoint

On this page