Skip to content

Configuration

Jump to bottom
superdingo101 edited this page Apr 1, 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)
header_text_color string See Description Custom header text hex color. If not set, will default to header_color-aware contrasting color to ensure legibility.
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 0 Start hour for week-standard view (0-23)
week_end_hour integer 23 End hour for week-standard view (0-23)
lock_schedule_hours Boolean false If true, schedule view will be locked to week_start_hour and week_end_hour even if events fall outside that time window.
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
color_scheme string auto Adjust dark mode settings. Valid options are auto (default, matches browser/HA setting), light, and dark. The header dark-mode toggle can override this setting.
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_opacity int 0 Background opacity. 0 is identical to background_transparent: false. 100 is identical to background_transparent: true. Works identically to background image when setting up HA dashboard for images.
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.
event_time_font_size int 9 Size, in px, of the event time font size. Applied to all views.
combine_calendars boolean false Option to combine identical events across multiple displayed calendars into a single, visually zebra-striped, group-managed event.
combine_style string bars Sets the style of combine_calendars. Valid options include bars (default), stripes (legacy), and dots.
combine_background string neutral Sets the background of a combined event when combine_style is set to bars or dots. Valid options include neutral (default), primary, or any valid hex color code. This is ignored when combine_style is set to stripes.
combine_calendars_width int 12 Customization of the visual striping width if combine_calendars is enabled.
hide_calendars boolean false Option to hide the calendars listed in the header.
hide_controls boolean false Option to hide the controls in the header.
hide_dark_mode_toggle boolean false Option to hide the dark-mode control in the header.
show_all_events_month boolean false Option to show all events in the month view only. Overrides compact_height option.
show_all_details_month boolean 'false' Option to show all event details in month view. Effectively sets show_all_events_month: true which also override compact_height option. Styling for month view in this case is the exact same as in the week view.
show_event_location boolean false Option to show the event location in the Week and Schedule views.
event_location_font_size int 9 Font size of displayed event location in Week and Schedule views.
event_calendar_friendly_name boolean false Option to show full calendar name instead of calendar icon. Overrides hide_event_calendar_bubble if true.

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