Configuration

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
hide_empty_days	boolean	false	Hide empty days in agenda view
agenda_compact_events	boolean	false	Tighter event formatting in agenda view

---

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
virtual_calendars	map	none	See below

---

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 to a configured Lovelace dashboard.
header_dashboard_path	string	null	Lovelace dashboard used with show_dashboard_nav_button.
show_week_numbers_month	boolean	false	Show ISO 8601 week numbers in month view.
hide_badge_names	list	'[]'	List of badges to hide from the header.
header_weather_sensor	entity	null	Home Assistant weather entity. Adds current weather to header, daily forecast to day headers. Built around pirateweather but will work with any weather integrations that provide similarly formatted data.
header_time_sensor	entity	null	Home Assistant entity to display the current time in the header.

---

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)'

header_weather_sensor

Home Assistant weather entity. Adds current weather to the header and daily forecast to day headers. Support was designed around the pirateweather integration but will work with any weather integration that provides similarly formatted data.

---

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.

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:
  # Style current day only
  - condition: today
    background: "#0082f6"
    background_opacity: 0.6
    border_color: "#0082f6"
    border_width: 5px

  # Days in the past
  - condition: past
    opacity: 0.45

  # Any day with an event from a calendar
  - condition: has_event
    calendar: calendar.holidays_in_united_states
    background: "##bbf7d0"
    background_opacity: 0.6

  # Title match with string matching
  - condition: has_event
    calendar: calendar.kid
    title_match: first day
    border_color: "#FF0000"
    border_width: 5px

  # Negative works with has_event
  - condition: "!has_event"
    calendar: calendar.work
    background: "#22afaa"
    background_opacity: 0.6

  # Saturday + Sunday (numeric form; 0=Sunday, 6=Saturday)
  - condition: day_of_week
    day_of_week: [0, 6]
    background: "#1f2937"
    background_opacity: 0.14
    border_color: "#475569"
    border_width: 1px

  # Make weekdays slightly different for contrast
  - condition: weekday
    background: "#0f172a"
    background_opacity: 0.04

  # Make weekends slightly different for contrast
  - condition: weekend
    background: "#0f172a"
    background_opacity: 0.04

  # Day-based styling
  - condition: day_of_week
    day_of_week: [saturday, sunday]
    background: "#1f2937"
    background_opacity: 0.14

  # And with a Spanish locale, localized tokens work too
  - condition: day_of_week
    day_of_week: [sábado, domingo]
    background: "#1f2937"
    background_opacity: 0.14

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

virtual_calendars

type: custom:skylight-calendar-card
title: Family Calendar
entities:
  - calendar.rob
  - calendar.suzie
virtual_calendars:
  - id: children
    name: Kids
    icon: mdi:human-child
    color: "#7c3aed"
    entities:
        - calendar.rob
        - calendar.suzie

Configurable by yaml only, virtual_calendars allows for the creation of a virtual calendar, visible only through this dashboard, that is displayed and acts as though it is a single calendar entity. Note that it takes the place of the calendar entities referenced, it is not additive. It can be modified through other actions such as event_styles.