Weather Radar Card

A Home Assistant rain radar card using tiled radar imagery from RainViewer, NOAA/NWS, and DWD (Deutscher Wetterdienst).

[![GitHub Release][releases-shield]][releases] [![License][license-shield]](LICENSE) !Maintenance

Description

This card displays animated weather radar loops within Home Assistant. It supports multiple radar data sources and map styles, and can be zoomed and panned seamlessly. Markers, hazard overlays (US wildfires + NWS watches & warnings), real-time lightning, a forecast nowcast (DWD), opt-in motion-compensated playback (rain drifts between frames instead of teleporting), adjustable playback speed with optional per-user persistence, full sections-grid resize support, and 11 languages.

!Weather Radar card

Video demo

Full-screen capture with every feature enabled — radar with motion compensation, lightning, wind streamlines, hazard overlays, playback controls:

• carto_api_key config option — free CARTO API key (no account needed — carto.com/basemaps/apikey) removes the watermark. Set it in the editor's Map section or via YAML; leaving it unset keeps the previous (watermarked but working) tiles.
• Two new no-key map styles: Grey and GreyDark — Esri Light/Dark Grey Canvas basemaps, for anyone who'd rather not sign up for a CARTO key at all.

What's new in 3.8

• Themeable progress-bar colors — progress_bar_background_color, progress_bar_active_color, and progress_bar_now_color override the timeline's built-in light/dark palette via YAML, to match your dashboard theme. (3.8.0-beta1)
• Timestamps follow Home Assistant's own Time format setting — the radar timeline and NWS alert times defer to your HA profile's 12h/24h preference (Settings → General) instead of guessing from the browser locale. (3.8.0-beta1)
• Wildfire popup area and discovery date now follow your HA unit system and locale — hectares for metric users instead of always showing NIFC's raw acres, and locale-aware date ordering. (3.8.0-beta1)
• Forecast-heavy configs no longer load the farthest-future frame before "now" — for a config like past_minutes: 0, forecast_minutes: 60, the initial load now always starts at "now" and fans outward, instead of loading highest-index-first. (3.8.0-beta2)
• Fixed a periodic-refresh race that could corrupt playback position — the timeline drifting backward on loop, or skip-back jumping to "Latest" instead of the previous frame. (3.8.0-beta3)

Roadmap

Active threads, no specific version commitment — with 3.9 shipped, these target 3.10 or later. See docs/todo.md for the full backlog with status per item.

• Real-time per-user layer visibility control panel — UI for toggling individual overlays in real time. Persistence framework already shipped (3.6.5); first consumer shipped (playback speed in 3.7.0-alpha1); the on-map panel itself is the remaining piece. Full design in docs/layer-control-design.md.
• Additional wind sources — Open-Meteo for global coverage, ICON pressure levels for upper-air wind, regional finer-than-ICON-D2 sources (AROME, MEPS, HRRR). Tiers and trade-offs documented in docs/todo.md.

Documentation

| Topic | What's there | | --- | --- | | Configuration | Full options table, Map Style choices, Animation knobs, Double-tap action, sections-grid behaviour | | Data Sources | RainViewer / NOAA / DWD specifics, per-source caps, NOAA & DWD notes, DWD forecast leading-edge note | | Hazard & Layer Overlays | US wildfire perimeters, NWS watches & warnings, lightning (Blitzortung), and global wind — usage, knobs, safety disclaimers | | Markers | The markers[] schema, track-resolution rules, default home marker, migration from the legacy single-marker fields | | Examples | Sample YAMLs for common setups (basic, dense DWD loop, NOAA, OSM, mobile-only, person tracking, hazard overlays) | | Animation architecture | Internal: layer z-stack, two-slot crossfade, opacity ownership, dynamic tile size, pause behaviour, invariants | | Wildfire feature design | Internal: NIFC WFIGS feed, render decisions, InciWeb gating, refresh cadence | | NWS alerts feature design | Internal: api.weather.gov polling, zone resolution + caching, severity sort, popup chrome | | Wind feature design | Internal: bulk WCS fetch + adaptive scaling, coalescing cache, zoom-aware streamlines, layering | | Motion compensation feature design | Internal: pyramidal Lucas-Kanade optical flow, distance-from-white channel, inline-Blob worker pattern, crossfade-time translate | | Backlog / TODO | Open and shipped features | | Contributing | Local dev setup including the Docker HA testbed (npm run ha:up) |

Install

HACS

The card is part of the default HACS store. To install the latest stable, search for "Weather Radar Card" in HACS → Frontend → Explore & Add Repositories. Toggle Show beta versions in HACS to opt into prereleases.

Manual

Download the files from the latest release and place them in www/community/weather-radar-card in your HA config directory:

└── configuration.yaml
└── www
    └── community
        └── weather-radar-card
            └── weather-radar-card.js
            └── home-circle-dark.svg
            └── home-circle-light.svg
            └── pause.png
            └── play.png
            └── preview.jpg
            └── radar-colour-bar-dwd.png
            └── radar-colour-bar-nws.png
            └── radar-colour-bar-universalblue.png
            └── recenter.png
            └── skip-back.png
            └── skip-next.png

Upgrading from v2? Delete leaflet.js, leaflet.css, leaflet.toolbar.min.js, and leaflet.toolbar.min.css from www/community/weather-radar-card/ — they are bundled into weather-radar-card.js in v3 and the old files are no longer used.

Then add the following to your Lovelace resources:

resources:
  - url: /local/community/weather-radar-card/weather-radar-card.js
    type: module

Minimal config

type: 'custom:weather-radar-card'

That's it. The card defaults to RainViewer, your HA instance's location, and a zone.home marker. From there, the GUI editor exposes every knob — see Configuration for the full reference and Examples for common starting points.

For touchscreen dashboards, YAML can enlarge the timeline scrub target upward over the lower map while preserving its slim visual track and original bottom-bar height:

show_progress_bar: true
progress_bar_touch_height: 44

Sizing

How tall the card renders depends on where it lives:

• Masonry / panel views, or a sections cell with rows: auto — the card uses the height: config option (default 400px). This is the normal case.
• A sections-grid cell with a fixed row count (you've dragged the resize handle, or rows: is a number) — the grid cell owns the height. The card fills the cell and the height: option is ignored; resize it with the cell's drag handle instead. The editor disables the height box in this case so it's clear which control is in charge.

Changelog

See CHANGELOG.md for the complete history of changes.

[license-shield]: https://img.shields.io/github/license/jpettitt/weather-radar-card.svg?style=for-the-badge [releases-shield]: https://img.shields.io/github/release/jpettitt/weather-radar-card.svg?style=for-the-badge [releases]: https://github.com/jpettitt/weather-radar-card/releases