Skip to content

Configuration

Jump to bottom
superdingo101 edited this page May 7, 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
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
event_color_mode string none Changes event color styling. See below
event_color_mode string none See below
event_neutral_background string none See below
event_tint_opacity string none See below
event_color_bar_width string 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.

image

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:
  # 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.

event_color_mode

The new feature is controlled primarily by event_color_mode, which supports three values:

  • classic: Existing behavior, the event background uses the calendar/event color.
  • left-neutral: Shows the calendar color as a left-side bar and uses a neutral event background.
  • left-tint: Shows the calendar color as a left-side bar and uses a tinted background derived from the calendar/event color.

Invalid or missing event_color_mode values normalize back to classic.

Related options

event_neutral_background: used only with left-neutral; defaults to #F8F3E9.

event_tint_opacity: used only with left-tint; uses the same 0–100 direction as other opacity-style settings in this card, where 0 is fully opaque tint and 100 is fully transparent tint. It defaults to 80.

event_color_bar_width: controls the left color-bar width for split event modes. If it is not set, it falls back to combine_calendars_width; if neither is set, both default to 18.

Rendering behavior

For single-color events:

left-neutral applies the neutral background and draws a left-side bar using the event/calendar color.

left-tint applies the computed tint background and draws the same left-side color bar.

classic keeps the original full event-color background behavior.

Combined-calendar events continue through the existing combined-event styling path rather than being overridden by these single-event split modes.

Wiki

Getting Started

Usage

Support

Project

Clone this wiki locally