# Weather Radar Card

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

[![hacs_badge](https://img.shields.io/badge/HACS-Default-orange.svg?style=for-the-badge)](https://github.com/hacs/integration)
[![GitHub Release][releases-shield]][releases]
[![License][license-shield]](LICENSE)
![Maintenance](https://img.shields.io/maintenance/yes/2026?style=for-the-badge)

## 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](https://github.com/jpettitt/weather-radar-card/blob/main/docs/configuration.md#motion-compensation) (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](weather-radar-card.gif)

### Video demo

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

[![Watch the demo on YouTube](https://img.youtube.com/vi/xfbZRElOi0o/maxresdefault.jpg)](https://youtu.be/xfbZRElOi0o)

## 4.0 preview

The next major version is a release candidate on the [`4.0` branch](https://github.com/jpettitt/weather-radar-card/blob/4.0/README-4.0.md). It adds Home Assistant's vector map under the radar, with place names drawn above the rain, view presets, and per-user layer toggles. It also needs a second file next to the card, which HACS installs. To try it, turn on **Show beta versions** for this card in HACS. [Upgrading to 4.0](https://github.com/jpettitt/weather-radar-card/blob/4.0/docs/upgrading-to-4.0.md) lists what changes. Bug fixes continue on 3.13.

## What's new in 3.13 (current stable)

DWD wind shows the model step nearest to now, cached forecast tiles outlast a long refresh interval, zooming out stops multiplying tile requests, and thirteen fixes from a whole-project review.

- **Wind shows the model step nearest to now** — AICON, the default outside the US, could show a slice almost 3 hours old; the overlays now pick the nearest step and refresh every half hour. ([3.13.0-beta1](https://github.com/jpettitt/weather-radar-card/releases/tag/v3.13.0-beta1))
- **Cached forecast tiles outlast a long refresh interval** — the reuse window follows `forecast_refresh_minutes` instead of a fixed 30 minutes, so a dashboard switch no longer discards tiles the card was just showing. Suggested by [@m42cel](https://github.com/m42cel). ([3.13.0-beta1](https://github.com/jpettitt/weather-radar-card/releases/tag/v3.13.0-beta1))
- **Zooming out no longer multiplies tile requests** — tiles follow the map's zoom instead of staying pinned to the highest level visited. ([3.13.0-beta1](https://github.com/jpettitt/weather-radar-card/releases/tag/v3.13.0-beta1))
- **Thirteen fixes from a whole-project review** — loops that froze after a tab switch, blank cards that never retried, tile retries outliving their tile, alert popups closing on every refresh, and more. ([3.13.0-beta1](https://github.com/jpettitt/weather-radar-card/releases/tag/v3.13.0-beta1))

## What's new in 3.12

US wind now shows the current hour in the right place, NOAA radar reaches Alaska, Hawaii, Puerto Rico and Guam, and radar loops reload from the browser, forecast included.

- **⚠️ Without a CARTO key, `map_style: Auto` now uses Home Assistant's map tiles** — CARTO serves blank tiles without a key. Add a free `carto_api_key` to keep CARTO's look. ([3.12.0-beta2](https://github.com/jpettitt/weather-radar-card/releases/tag/v3.12.0-beta2))
- **Radar loops reload from the browser, forecast included** — the tile cache now keeps DWD's forecast frames too, so a reload plays the stored loop and fetches only the newest frames. Every frame also says how old or how far ahead it is. ([3.12.0-beta1](https://github.com/jpettitt/weather-radar-card/releases/tag/v3.12.0-beta1))
- **NOAA radar in Alaska, Hawaii, Puerto Rico and Guam**, and steady 5- and 10-minute NOAA loops. ([3.12.0-beta2](https://github.com/jpettitt/weather-radar-card/releases/tag/v3.12.0-beta2))
- **US wind fixed** — it showed the forecast for about 15 hours ahead, a little too far north, and about 1.9× too strong. ([3.12.0-beta2](https://github.com/jpettitt/weather-radar-card/releases/tag/v3.12.0-beta2), [3.12.0](https://github.com/jpettitt/weather-radar-card/releases/tag/v3.12.0))
- **Wildfire popups** with location, personnel and cause, InciWeb links for many more fires, and a much lighter data feed. ([3.12.0-beta3](https://github.com/jpettitt/weather-radar-card/releases/tag/v3.12.0-beta3))

For the full release history see [CHANGELOG](https://github.com/jpettitt/weather-radar-card/blob/main/CHANGELOG.md).

## Roadmap

Active threads, no specific version commitment — with 3.13 shipped, these target a later release. See [docs/todo.md](https://github.com/jpettitt/weather-radar-card/blob/main/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](https://github.com/jpettitt/weather-radar-card/blob/main/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](https://github.com/jpettitt/weather-radar-card/blob/main/docs/todo.md).

## Documentation

| Topic | What's there |
| --- | --- |
| [Configuration](https://github.com/jpettitt/weather-radar-card/blob/main/docs/configuration.md) | Full options table, Map Style choices, Animation knobs, low power mode, Double-tap action, sections-grid behaviour |
| [Data Sources](https://github.com/jpettitt/weather-radar-card/blob/main/docs/data-sources.md) | RainViewer / NOAA / DWD specifics, per-source caps, tile caching, NOAA & DWD notes, DWD forecast leading-edge note |
| [Hazard & Layer Overlays](https://github.com/jpettitt/weather-radar-card/blob/main/docs/overlays.md) | US wildfire perimeters, NWS watches & warnings, lightning (Blitzortung), and global wind — usage, knobs, **safety disclaimers** |
| [Markers](https://github.com/jpettitt/weather-radar-card/blob/main/docs/markers.md) | The `markers[]` schema, track-resolution rules, default home marker, migration from the legacy single-marker fields |
| [Examples](https://github.com/jpettitt/weather-radar-card/blob/main/docs/examples.md) | Sample YAMLs for common setups (basic, dense DWD loop, NOAA, OSM, mobile-only, person tracking, hazard overlays) |
| [Animation architecture](https://github.com/jpettitt/weather-radar-card/blob/main/docs/animation.md) | Internal: layer z-stack, two-slot crossfade, opacity ownership, dynamic tile size, pause behaviour, invariants |
| [Wildfire feature design](https://github.com/jpettitt/weather-radar-card/blob/main/docs/wildfire-feature-design.md) | Internal: NIFC WFIGS feed, render decisions, InciWeb gating, refresh cadence |
| [NWS alerts feature design](https://github.com/jpettitt/weather-radar-card/blob/main/docs/nws-alerts-feature-design.md) | Internal: api.weather.gov polling, zone resolution + caching, severity sort, popup chrome |
| [Wind feature design](https://github.com/jpettitt/weather-radar-card/blob/main/docs/wind-feature-design.md) | Internal: bulk WCS fetch + adaptive scaling, coalescing cache, zoom-aware streamlines, layering |
| [Motion compensation feature design](https://github.com/jpettitt/weather-radar-card/blob/main/docs/motion-compensation-feature-design.md) | Internal: pyramidal Lucas-Kanade optical flow, distance-from-white channel, inline-Blob worker pattern, crossfade-time translate |
| [Backlog / TODO](https://github.com/jpettitt/weather-radar-card/blob/main/docs/todo.md) | Open and shipped features |
| [Contributing](https://github.com/jpettitt/weather-radar-card/blob/main/CONTRIBUTING.md) | 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](https://github.com/jpettitt/weather-radar-card/releases) and place them in `www/community/weather-radar-card` in your HA `config` directory:

```text
└── 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:

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

## Minimal config

```yaml
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](https://github.com/jpettitt/weather-radar-card/blob/main/docs/configuration.md) for the full reference and [Examples](https://github.com/jpettitt/weather-radar-card/blob/main/docs/examples.md) 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:

```yaml
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.

In other words: `rows: auto` → `height:` applies; `rows: <number>` → the cell's height applies. See [sections-grid behaviour](https://github.com/jpettitt/weather-radar-card/blob/main/docs/configuration.md#sections-grid-support) for details.

## Changelog

See [CHANGELOG.md](https://github.com/jpettitt/weather-radar-card/blob/main/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