Map Heat Overlay
A density overlay fading in over the basemap, with the hot cores arriving last.
PrimitiveMaps & deviceAdvanced
$ npx remotion-ui@latest add map-heat-overlayPass it the map from MapCanvas's onMapReady and a point collection, and it
adds a heatmap layer that fades up. Intensity climbs with the fade rather than
sitting at its final value, so the hot cores arrive last and the density reads
as accumulating instead of being there from the first frame at low alpha.
Like every MapLibre primitive here, the paint holds the frame open with its own
delayRender. Layers are added a commit after the map reports ready, and
without the hold the overlay drops out of whichever frame the browser captures
first — reliably the first sample of a still run, which then shows a bare
basemap and looks like a broken component.
Two settings decide whether this reads as data or as a smear. radius is in
screen pixels, so it ramps with zoom — otherwise the same overlay means
different things at different camera heights. And it wants to stay small:
roughly 12–24 for a few hundred points. Too large and every point merges into
one saturated blob with no density left to read.
The first colour stop must be transparent. A heatmap ramp is painted across the whole layer, so an opaque density-zero colour floods the entire viewport rather than showing the hot spots.
beforeLayerId slides the overlay under a basemap layer, which is how you keep
place labels legible through the heat.
The paint holds the frame open with its own delayRender: layers are added a commit after the map reports ready, and without the hold the overlay drops out of the first captured frame and the still shows a bare basemap. Intensity climbs with the fade so hot cores arrive last. The first colour stop must be transparent — a heatmap ramp paints across the whole layer, so an opaque density-zero colour floods the viewport.
Agent notes
Install first, then import the copied source component locally. AI guide →
@/remotion/primitives/map-heat-overlay- Use when: map scenes, routes, markers, and spatial storytelling.
- Customize: map, points, weightProperty, radius, plus copied source for timing, layout, colors, and typography.
- Rule: do not import this component from the
remotion-uinpm package; it is copied into your project.
Usage
import { MapCanvas } from "@/remotion/primitives/map-canvas";
import { MapHeatOverlay } from "@/remotion/primitives/map-heat-overlay";
const [map, setMap] = useState<Map | null>(null);
<AbsoluteFill>
<MapCanvas center={[2.2, 49.6]} zoom={4} onMapReady={setMap} />
<MapHeatOverlay map={map} points={points} radius={18} />
</AbsoluteFill>API Reference
| Prop | Type | Default | Description |
|---|---|---|---|
| map | Map | null | - | The map to paint on, from MapCanvas's onMapReady. |
| points | FeatureCollection<Point> | - | Points to weigh. |
| weightProperty | string | "weight" | Feature property holding each point's weight. |
| radius | number | 18 | Kernel radius in screen pixels at radiusZoom. Roughly 12–24 for a few hundred points. |
| radiusZoom | number | 3 | The zoom the radius is authored at; it ramps from there. |
| intensity | number | 0.85 | Peak opacity once the overlay has faded up. |
| colors | string[] | 5-stop cool-to-hot ramp | Density ramp, low first. The first stop must be transparent. |
| beforeLayerId | string | - | Layer to sit under, so place labels stay legible through the heat. |
| sourceId | string | "heat-points" | Source and layer id prefix, for more than one overlay on a map. |
| revealProgress | number | - | Drive the fade yourself, 0–1. Omit for the built-in frame ramp. |