Skip to content

Configuration

Jump to bottom
superdingo101 edited this page Mar 6, 2026 · 58 revisions

Configuration

Minimal working config

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

Common options

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

Option Type Default Description
title string 'Family Calendar' Card title displayed in header
entities list Required List of calendar entity IDs
calendar_names map auto Custom name map for each calendar entry
default_view string null Initial view mode on load: 'month', 'week-compact', or 'week-standard'
header_color string 'var(--primary-color)' Custom header background (solid color or gradient)
first_day_of_week integer 0 First day of week (0 = Sunday, 1 = Monday, etc.)
week_days list [0,1,2,3,4,5,6] Days to show in week views (0=Sun, 6=Sat)
rolling_days_week_compact integer null Compact week view: show today + N days (alternative to week_days)
rolling_days_schedule integer null Schedule view: show today + N days (alternative to week_days)
rolling_weeks integer null Show this week + N weeks in month view
week_start_hour integer 8 Start hour for week-standard view (0-23)
week_end_hour integer 21 End hour for week-standard view (0-23)
height_scale float 1.0 Height scaling factor (0.5-2.0, affects schedule view)
compact_height boolean false Fit monthly/schedule views to available screen height without scrolling
compact_header boolean false Single-row header with inline badges
hide_event_calendar_bubble boolean false Hide the calendar initial bubble shown inside events
hide_times_for_calendars list [] Calendar entities whose start/end times should be hidden in schedule view
show_current_time_bar boolean false Show a red current-time indicator line in schedule view
default_dark_mode boolean false Start the card in dark mode on load (legacy alias: dark_mode)
max_events integer 0 Maximum number of events to load. Defaults to 0 which is interpreted as unlimited. Note client side performance may be impacted when set to 0.
enable_event_management boolean true Enable event creation features
readonly_calendars list [] Calendar entities that should not allow modifications
colors map auto Custom colors for each calendar entity
language string en Language for strings
locale string en-US Optional locale; falls back to language/Home Assistant settings
background_transparent boolean false Set calendar background to transparent
background_image_url string [] Online URLs or HA local media path
background_image_size string cover Any valid css for background-size, incl: cover (default); contain; auto; 100% 100%; 120px auto
background_image_position string center Any valid background-position value, incl: center (default); top, bottom, left, right; top left, center right; 50% 25%; 20px 40px
background_image_repeat string no-repeat Any valid background_image_repeat value, incl: no-repeat (default); repeat; repeat-x; repeat-y; space; round
use_24hr_schedule Boolean false Use 24 hr notation in schedule view
event_font_size int 11 Size, in px, of the event font size. Applied to all views.
event_font_colors map white Font color applied to each calendar. Defaults to white.
combine_calendars boolean false Option to combine identical events across multiple displayed calendars into a single, visually zebra-striped, group-managed event.
combine_calendars_width int 12 Customization of the visual striping width if combine_calendars is enabled.

Full Width

To get your calendar to appear full width, you have a few options.

  1. Create a new dashboard
  2. Select the pencil icon to edit the dashboard
  3. Select the edit icon next to your view tab

image

  1. Select the dashboard type

Panel

Panel is the simplest to configure, and the most limiting. It will create a full-page, full-width single card of your choosing. This can be perfect for this calendar dashboard and was the view originally intended to be used. However, it can be limiting as no other information can be shown alongside.

Sections

With some clever page layouts, you can stretch the calendar across the entire width, or create narrower columns to fit the calendar width you desire.

Try adding the following to the card config if using Sections to get full width:

grid_options:
  columns: [12*column_span]
  rows: 10
Sample Sections Configuration

image

Raw yaml to create this view:

views:
- type: sections
  cards: []
  sections:
    - type: grid
      cards:
        - type: custom:clock-weather-card
          entity: weather.openweathermap
          sun_entity: sun.sun
          temperature_sensor: sensor.outside_temperature_3
          weather_icon_type: line
          animated_icon: true
          forecast_days: 4
          time_format: 24
          date_pattern: MMMM dd, yyyy
          hide_today_section: false
          hide_forecast_section: false
        - type: entities
          title: Lights
          icon: mdi:lightbulb-on
          entities:
            - type: custom:fold-entity-row
              head: light.family_room_lights
            - type: custom:fold-entity-row
              head:
                entity: light.family_room_lights
                type: section
                label: Family Room
              entities:
                - entity: light.inovelli_family_room_light
                  name: Kitchen Table Light
                - entity: light.inovelli_entryway_light
                  name: Entryway Light
                - entity: switch.outside_lights
                - entity: light.wled_tv_2
                  name: TV Backlights
                - entity: light.wled_couch_2
                  name: Couch Backlights
            - type: custom:fold-entity-row
              head:
                type: section
                label: Kitchen
              entities:
                - entity: input_boolean.kitchen_lights_group
                  name: Kitchen Lights
                - entity: light.kitchen_light_7
                  name: Play Room Light
                - entity: light.family_room_lights_switch
                  name: Christmas Tree
            - type: custom:fold-entity-row
              head:
                type: section
                label: Outside
              entities:
                - entity: switch.wemo_mini
                  name: Backyard Lights
                - entity: switch.outside_christmas_lights_switch
                  name: Outside Christmas Lights
                - entity: switch.patio_switch
                - entity: light.front_lights
            - type: custom:fold-entity-row
              head:
                type: section
                label: Kid's Room
              entities:
                - entity: light.inovelli_kid_s_room_light
                  name: Kid's Room Light
      column_span: 1
    - type: grid
      cards:
        - type: custom:skylight-calendar-card
          title: ''
          entities:
            - calendar.redacted
            - calendar.redacted
            - calendar.redacted
            - calendar.holidays_in_united_states
          calendar_names:
            calendar.redacted: Family
            calendar.redacted: Kid 1
            calendar.redacted: Kid 2
            calendar.holidays_in_united_states: Holidays
          rolling_weeks: 3
          rolling_days_week_compact: 6
          rolling_days_schedule: 6
          show_week_numbers: false
          first_day_of_week: 0
          week_start_hour: 8
          week_end_hour: 21
          default_view: week-standard
          compact_header: true
          compact_height: true
          max_events: 1000
          language: en
          hide_event_calendar_bubble: true
          readonly_calendars:
            - calendar.holidays_in_united_states
          hide_times_for_calendars:
            - calendar.redacted
          show_current_time_bar: true
          use_24hr_schedule: false
          event_font_size: 11
          event_font_colors:
            calendar.redacted: '#ffffff'
            calendar.redacted: '#fef3c7'
            calendar.redacted: '#111827'
          grid_options:
            columns: 36
            rows: 10
      column_span: 3
  max_columns: 4

Combined Calendar Behavior

Combining Duplicate Events Across Calendars: What It Does

When multiple calendars contain the same event, enabling:

combine_calendars: true

will:

  • Merge duplicates into one event bubble
  • Apply zebra striping with each calendar's color
  • Show multiple calendar icons in Week view
  • Show multiple calendar badges in the event modal
  • Allow selective editing/deleting per calendar copy

Visual Behavior

Normal Event

  • Solid background color
  • Single calendar badge

Combined Event

  • Diagonal zebra stripe gradient
  • Multiple calendar icons (week view)
  • Multiple calendar badges (modal view)
  • Stripe width controlled by: combine_calendars_width

How Duplicate Detection Works

Events must match exactly on:

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

Whitespace and formatting are normalized.

If any field differs, events will not combine.

Features in detail: appearance and colors

Color-coded events

Each calendar entity can have its own color:

colors:
  calendar.personal: '#FF6B6B'    # Red for personal events
  calendar.work: '#4ECDC4'        # Teal for work events
  calendar.family: '#45B7D1'      # Blue for family events
  calendar.kids: '#FFA07A'        # Orange for kids' activities

Customizing header color

The header defaults to var(--primary-color), or you can set a custom color/gradient.

Solid colors:

header_color: '#1e40af'
header_color: '#059669'
header_color: '#dc2626'

Gradients:

header_color: 'linear-gradient(135deg, #1e3a8a 0%, #3b82f6 100%)'
header_color: 'linear-gradient(135deg, #065f46 0%, #10b981 100%)'
header_color: 'linear-gradient(135deg, #ea580c 0%, #dc2626 100%)'
header_color: 'linear-gradient(135deg, #0f766e 0%, #14b8a6 100%)'
header_color: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)'

Theme variables:

header_color: 'var(--secondary-color)'
header_color: 'var(--accent-color)'
header_color: 'var(--card-background-color)'
header_color: 'var(--primary-color)'

Event bubble text customization (multiple calendars)

Use event_font_size to set event text size globally across all views and calendars. Use event_font_colors to set text color per calendar entity (defaults to white when not provided).  

type: custom:skylight-calendar-card
title: Family Calendar
entities:
- calendar.family
- calendar.work
- calendar.school
colors:
  calendar.family: "#ef4444"
  calendar.work: "#3b82f6"
  calendar.school: "#10b981"
event_font_size: 13
event_font_colors:
  calendar.family: "#ffffff"
  calendar.work: "#fef3c7"
  calendar.school: "#111827"

Background customization (transparent or image)

You can make the calendar background transparent, or set a background image URL that applies across month, week, and schedule views:

type: custom:skylight-calendar-card
entities:
  - calendar.family
background_transparent: true
# or use an image instead:
# background_image_url: https://example.com/your-photo.jpg
# background_image_size: cover
# background_image_position: center
# background_image_repeat: no-repeat

background_image_url supports:

  • Online images (for example https://...)
  • Home Assistant local media paths (for example /media/local/family/photo.jpg)
  • Home Assistant media-source local URIs (for example media-source://media_source/local/family/photo.jpg)

Calendar badge icons/photos

  Use calendar_badge_icons to customize each calendar's badge circle with either an MDI icon (mdi:*) or an image URL (including /media/local/...).  

type: custom:skylight-calendar-card
title: Family Calendar
entities:
  - calendar.family
  - calendar.work
calendar_badge_icons:
  calendar.family: mdi:home-heart
  calendar.work: /media/local/work-avatar.jpg
Recommended image format for calendar_badge_icons

Because badge images are rendered inside a small circular container and forced to fill it with object-fit: cover, the best source image is:

  • Aspect ratio: 1:1 (square)
  • Minimum size: at least 64×64 px
  • Ideal size: 128×128 px (or 256×256 for higher-density displays)
  • Subject framing: keep the main subject centered, since edge content may be cropped in the circle.

Why:

  • The main badge icon is 24x24 px in normal layout.
  • In compact inline mode it is even smaller at 20x20 px.
  • Images are stretched to badge bounds and cropped via object-fit: cover, so non-square images will lose content around edges.

Wiki

Getting Started

Usage

Support

Project

Clone this wiki locally