Skip to content

Configuration

Jump to bottom
superdingo101 edited this page Apr 19, 2026 · 58 revisions

Configuration

Minimal Configuration

type: custom:skylight-calendar-card
title: Family Calendar
entities:
  - calendar.family

Common Configuration Example

type: custom:skylight-calendar-card
title: Family Calendar
entities:
  - calendar.personal
  - calendar.work
  - calendar.family
  - calendar.holidays_in_united_states

default_view: week-standard
week_start_hour: 8
week_end_hour: 21
first_day_of_week: 0

compact_header: true
compact_height: true

calendar_names:
  calendar.holidays_in_united_states: Holidays

readonly_calendars:
  - calendar.holidays_in_united_states

colors:
  calendar.personal: '#FF6B6B'
  calendar.work: '#4ECDC4'
  calendar.family: '#45B7D1'

Configuration Options

Core Options

Option Type Default Description
title string 'Family Calendar' Card title
entities list Required Calendar entity IDs
calendar_names map auto Friendly names
default_view string null month, week-compact, week-standard, agenda

Date & Time Behavior

Option Type Default Description
first_day_of_week integer 0 0 = Sunday
week_days list [0,1,2,3,4,5,6] Days shown in week views
rolling_days_week_compact integer null Show today + N days
rolling_days_schedule integer null Schedule rolling window
rolling_weeks integer null Show this week + N weeks
week_start_hour integer 0 Start hour
week_end_hour integer 23 End hour
lock_schedule_hours boolean false Lock schedule hours
use_24hr_schedule boolean false 24-hour format

Layout & Sizing

Option Type Default Description
height_scale float 1.0 Schedule scaling
compact_height boolean false Fit to screen
compact_header boolean false Single-row header
max_events integer 0 0 = unlimited

Event Display

Option Type Default Description
hide_event_calendar_bubble boolean false Hide calendar icon
event_calendar_friendly_name boolean false Show full calendar name
event_title_prefix string none Prefix event titles
show_event_location boolean false Show location
use_short_location boolean false Shorten location
event_location_font_size integer 9 Location font size
hide_times_for_calendars list [] Hide times for calendars
show_current_time_bar boolean false Show current time indicator
event_styles map none See below

Calendar Behavior

Option Type Default Description
enable_event_management boolean true Allow event editing
readonly_calendars list [] Disable editing for calendars
combine_calendars boolean false Merge duplicate events
combine_style string bars bars, dots, stripes
combine_background string neutral Background style
combine_calendars_width integer 12 Stripe width

Header & Controls

Option Type Default Description
hide_calendars boolean false Hide calendar buttons
hide_controls boolean false Hide navigation controls
hide_dark_mode_toggle boolean false Hide dark mode toggle
hide_calendar_names boolean false Show icons only
hide_year boolean false Remove year from header
show_dashboard_nav_button boolean false An optional navigation button on the far-left of the header to let users jump to a configured Lovelace dashboard.
header_dashboard_path string null Lovelace dashboard (ex: /family-dashboard) used with show_dashboard_nav_button.

Appearance

Option Type Default Description
color_scheme string auto auto, light, dark
colors map auto Per-calendar colors
event_font_size integer 11 Event text size
event_font_colors map white Per-calendar font colors
event_time_font_size integer 9 Time font size

Background & Media

Option Type Default Description
background_transparent boolean false Transparent background
background_opacity integer 0 0–100 opacity
background_image_url string [] Background image
background_image_size string cover CSS background-size
background_image_position string center CSS position
background_image_repeat string no-repeat CSS repeat
day_styles map none See below

Localization

Option Type Default Description
language string en UI language
locale string en-US Regional formatting

Layout & Full Width

Full Width Options

Use one of the following dashboard layouts:

  • Panel → simplest, full-width single card
  • Sections → flexible layouts with multiple cards

Panel

  • Full-width
  • One card only

Sections

  • Supports columns and layouts
  • Can stretch calendar across full width

Tip for Sections:

grid_options:
  columns: [12*column_span]
  rows: 10

Combined Calendar Behavior

Enable Combined Events

combine_calendars: true

What It Does

  • Merges duplicate events
  • Applies visual striping
  • Shows multiple calendar indicators
  • Allows per-calendar editing

Duplicate Matching Rules

Events must match exactly on:

  • Start time
  • End time
  • Summary
  • Description
  • Location

Whitespace and formatting are normalized.

Appearance & Styling

Calendar Colors

colors:
  calendar.personal: '#FF6B6B'
  calendar.work: '#4ECDC4'
  calendar.family: '#45B7D1'
  calendar.kids: '#FFA07A'

Header Styling

Supports solid colors, gradients, and theme variables:

header_color: '#1e40af'
header_color: 'linear-gradient(135deg, #1e3a8a 0%, #3b82f6 100%)'
header_color: 'var(--primary-color)'

Background Customization

background_transparent: true
background_image_url: https://example.com/image.jpg
background_image_size: cover
background_image_position: center
background_image_repeat: no-repeat

Supports:

  • Online images (https://...)
  • /media/local/...
  • media-source://...

Event Text Styling

event_font_size: 13

event_font_colors:
  calendar.family: "#ffffff"
  calendar.work: "#fef3c7"
  calendar.school: "#111827"

Calendar Badge Icons

calendar_badge_icons:
  calendar.family: mdi:home-heart
  calendar.work: /media/local/work-avatar.jpg

Recommended Image Format

  • Aspect ratio: 1:1 (square)
  • Minimum: 64×64 px
  • Ideal: 128×128 px or higher
  • Keep subject centered (edges may be cropped)

event_styles

Example: Match all events on calendar.mike that have "game" in the title except those with "soccer" in the title.

image 
event_styles:
  - id: important
    priority: 20
    match:
      and:
        - title: game
        - calendar: calendar.mike
        - not:
          - title: soccer
    style:
      background_color: "#8B0000"
      event_font_color: "#5FFFFF"
      event_font_size: 13
      event_time_font_size: 13
      event_location_font_size: 10
      show_event_location: true
      use_short_location: true
      hide_time: false
      hide_event_calendar_bubble: false
      event_title_prefix: "badge"

Field match keys

  • title
  • summary (alias of title)
  • calendar (matches either entity_id or calendar friendly name)
  • location
  • description
  • all_day (boolean-style matching)

Logical operators

  • all: every child condition must match
  • and: same behavior as all
  • any: at least one child condition must match
  • not: negates a condition (supports object or array forms)

String matching modes (for text fields)

Default: substring (case-insensitive)

  • exact:<text>
  • contains:<text> or substring:<text>
  • regex:<pattern>
  • /pattern/flags regex literal format
  • Object form also works:
    • { exact: "..." }
    • { substring: "..." }
    • { contains: "..." }
    • { regex: "..." }

all_day value handling

  • Accepts boolean (true / false)
  • Also accepts "true" / "false" strings

Styling

  • background_color: "#8B0000"
  • event_font_color: "#FFFFFF"
  • event_font_size: 13
  • event_time_font_size: 10
  • event_location_font_size: 10
  • show_event_location: true
  • use_short_location: true
  • hide_time: false
  • hide_event_calendar_bubble: false
  • event_title_prefix: "badge"
    • event_title_prefix options: badge, icon, friendly

Priority

If multiple styles match, the one with the lowest priority value wins.

day_styles

Conditionally highlight a day in all views.

day_styles:
  - condition: today
    background: "#0082f6"
    background_opacity: 0.6
    border_color: "#0082f6"
    border_width: 5px
  - condition: past
    opacity: 0.45
  - condition: has_event
    calendar: calendar.holidays_in_united_states
    background: "##bbf7d0"
    background_opacity: 0.6
  - condition: has_event
    calendar: calendar.kid
    title_match: first day
    border_color: "#FF0000"
    border_width: 5px

title_match

title_match is only used when condition: has_event.

How it works

For each day, the card:

  1. Finds events on that day.
  2. Filters to events matching calendar.
  3. If title_match is provided, it checks the event title (event.summary) using the same text matcher as other rules.
  • Plain string = case-insensitive substring match
  • exact:... = exact match
  • contains:... / substring:... = substring match
  • regex:... or /.../flags = regex match

Wiki

Getting Started

Usage

Support

Project

Clone this wiki locally