🌞 Solar Mask Card — Home Assistant custom card

A Lovelace custom card for Home Assistant that displays an interactive solar diagram — the sun's path across the sky overlaid on your custom horizon mask.

Designed as a pair to the Solar Mask integration.

About

The Solar Mask Card renders a classic azimuth/elevation solar diagram directly in your Lovelace dashboard. It shows:

• The horizon mask defined by your obstacles (buildings, trees, hills)
• The sun's trajectory for key reference days (solstices, equinox, today)
• The sun's current position in real time

At a glance, you can see exactly when your zone enters and exits shadow at any time of year.

Features

• 📊 SVG-based diagram — crisp at any screen resolution, no canvas artifacts
• 🗓️ 5 reference curves — summer solstice, equinox, winter solstice, and today's trajectory
• 🟠 Real-time sun dot — updates every 5 minutes, color-coded (orange = visible, grey = masked)
• 🏔️ Horizon mask area — filled orange area showing your obstacles
• 📋 Info bar — lever du soleil, élévation actuelle, coucher du soleil
• 🌗 Adaptive theme — uses Home Assistant CSS variables, works with light and dark themes
• ⚙️ Simple configuration — two entity IDs and an optional title

Requirements

• Solar Mask integration installed and configured
• Home Assistant 2023.1 or newer

Installation

Via HACS (recommended)

1. In HACS, go to Frontend → ⋮ → Custom repositories
2. Add https://github.com/38decibel/Solar-Mask-Card with type Dashboard
3. Search for Solar Mask Card and install
4. Reload your browser

Manual

1. Download solar-mask-card.js from the Releases page
2. Copy it to /config/www/solar-mask-card.js
3. Add the resource in Home Assistant:
   • Go to Settings → Dashboards → ⋮ → Resources → + Add resource
   • URL: /local/solar-mask-card.js
   • Type: JavaScript module
4. Reload your browser

Configuration

Add the card to any dashboard using the Manual card editor:

type: custom:solar-mask-card
entity: sensor.pool_solar_diagram
sun_entity: sensor.pool_sun_effective_elevation
title: "Solar diagram — Pool"
height: 340

Options

Option	Required	Default	Description
entity	✅	—	sensor.<zone>_solar_diagram from the Solar Mask integration
sun_entity	❌	—	sensor.<zone>_sun_effective_elevation — enables the live sun dot and info bar
title	❌	Entity friendly name	Card title displayed at the top
height	❌	320	Chart height in pixels

The info bar (sunrise / current elevation / sunset) is displayed automatically when sun_entity is provided. The corresponding sun_start and sun_end entities are resolved automatically from the sun_entity name.

Diagram Legend

Element	Description
🟠 Orange filled area	Horizon (mask) — your obstacles
Yellow dashed line	Summer solstice trajectory (21 June)
Orange dashed line	Equinox trajectory (20 March)
Blue dashed line	Winter solstice trajectory (21 December)
Green solid line	Today's sun trajectory
Orange dot	Current sun position (visible)
Grey dot	Current sun position (behind mask)

How It Works

The card reads pre-computed data published as attributes by the Solar Mask integration on the sensor.<zone>_solar_diagram entity. No computation happens in the browser — the card is a pure renderer.

Data attributes consumed:

Attribute	Content
mask	List of {x: azimuth, y: elevation} points for the horizon mask
path_solstice_ete	Sun path points for 21 June
path_equinoxe_mars	Sun path points for 20 March
path_solstice_hiver	Sun path points for 21 December
path_aujourdhui	Sun path points for today

The live sun dot is read from sensor.<zone>_sun_effective_elevation attributes (sun_azimuth, sun_elevation) and state (effective_elevation).

Sun paths are recomputed by the integration once per day (at midnight). The current position updates every 5 minutes.

Examples

Pool dashboard

type: custom:solar-mask-card
entity: sensor.pool_solar_diagram
sun_entity: sensor.pool_sun_effective_elevation
title: "Pool — Solar diagram"
height: 360

Terrace, compact view

type: custom:solar-mask-card
entity: sensor.terrace_solar_diagram
sun_entity: sensor.terrace_sun_effective_elevation
title: "Terrace"
height: 260

Multiple zones side by side (horizontal stack)

type: horizontal-stack
cards:
  - type: custom:solar-mask-card
    entity: sensor.pool_solar_diagram
    sun_entity: sensor.pool_sun_effective_elevation
    title: Pool
    height: 280

  - type: custom:solar-mask-card
    entity: sensor.terrace_solar_diagram
    sun_entity: sensor.terrace_sun_effective_elevation
    title: Terrace
    height: 280

Companion Integration

This card is designed to work exclusively with the Solar Mask Home Assistant integration:

👉 github.com/38decibel/solar-mask

The integration handles all astronomical computations and publishes the data. The card handles the visualization. Neither works without the other.

License

MIT License — see LICENSE for details.