1---
2name: maps
3description: Make deterministic Remotion map animations with MapLibre GL JS and Turf. Use for animated routes, flyovers, map markers, labels, and camera movement.
4metadata:
5  tags: map, map animation, maplibre, turf, geojson, route animation
6---
7 
8Use MapLibre GL JS for rendering maps in Remotion. Use Turf for geospatial operations such as great-circle routes, distances, slicing lines, and positions along routes.
9 
10## Core rules
11 
12- Prefer `@turf/turf` for geospatial work. Do not hand-roll distance, great-circle, route slicing, or coordinate interpolation unless the user explicitly needs a custom non-geodesic effect.
13- Use GeoJSON sources and MapLibre layers for lines, markers, and labels. Avoid DOM `Marker` elements unless the user specifically asks for HTML markers.
14- Disable non-deterministic map behavior: `interactive: false`, `fadeDuration: 0`.
15- Use `delayRender()` / `continueRender()` around map loading and per-frame map updates.
16- Before continuing the initial render, add sources/layers, apply the frame-0 camera with `jumpTo()`, then wait for `idle`.
17- Do not add a `mapInstance.remove()` cleanup function; it can interfere with Remotion's render lifecycle.
18- Use standard MapLibre style JSON URLs and layer/source APIs.
19- Do not install `@types/maplibre-gl`; MapLibre ships its own types.
20 
21Coordinates in MapLibre, Turf, and GeoJSON are `[longitude, latitude]`.
22 
23```ts
24const zurich: [number, number] = [8.5417, 47.3769];
25const newYork: [number, number] = [-74.006, 40.7128];
26```
27 
28## Prerequisites
29 
30Install MapLibre and Turf with the project's package manager.
31 
32```bash
33npm i maplibre-gl @turf/turf
34```
35 
36```bash
37bun i maplibre-gl @turf/turf
38```
39 
40```bash
41yarn add maplibre-gl @turf/turf
42```
43 
44```bash
45pnpm i maplibre-gl @turf/turf
46```
47 
48Import the MapLibre CSS once in the component or an app-level stylesheet:
49 
50```ts
51import 'maplibre-gl/dist/maplibre-gl.css';
52```
53 
54## Basic map example
55 
56```tsx
57import {useEffect, useRef, useState} from 'react';
58import {AbsoluteFill, useDelayRender, useVideoConfig} from 'remotion';
59import maplibregl from 'maplibre-gl';
60import 'maplibre-gl/dist/maplibre-gl.css';
61 
62const zurich: [number, number] = [8.5417, 47.3769];
63 
64export const MyComposition = () => {
65	const containerRef = useRef<HTMLDivElement>(null);
66	const {delayRender, continueRender} = useDelayRender();
67	const {width, height} = useVideoConfig();
68	const [loadingHandle] = useState(() => delayRender('Loading map'));
69 
70	useEffect(() => {
71		if (!containerRef.current) {
72			return;
73		}
74 
75		const mapInstance = new maplibregl.Map({
76			container: containerRef.current,
77			style: 'https://demotiles.maplibre.org/style.json',
78			center: zurich,
79			zoom: 7,
80			interactive: false,
81			attributionControl: false,
82			fadeDuration: 0,
83			canvasContextAttributes: {
84				preserveDrawingBuffer: true,
85			},
86		});
87 
88		mapInstance.on('load', () => {
89			mapInstance.jumpTo({center: zurich, zoom: 7});
90			mapInstance.once('idle', () => {
91				continueRender(loadingHandle);
92			});
93		});
94	}, [continueRender, loadingHandle]);
95 
96	return (
97		<AbsoluteFill>
98			<div ref={containerRef} style={{width, height, position: 'absolute'}} />
99		</AbsoluteFill>
100	);
101};
102```
103 
104Animated examples should keep the loaded map in React state and skip per-frame updates until that state is set.
105 
106## Animated flight route example
107 
108This example shows the recommended pattern for route animations:
109 
110- Turf creates the route and markers.
111- Turf slices the route for line reveal animation.
112- The camera has a separate route from the target route.
113- MapLibre's `calculateCameraOptionsFromTo()` is used for camera movement.
114- Frame 0 is prepared before `continueRender()`.
115 
116```tsx
117import * as turf from '@turf/turf';
118import {useEffect, useRef, useState} from 'react';
119import {
120	AbsoluteFill,
121	Easing,
122	interpolate,
123	useCurrentFrame,
124	useDelayRender,
125	useVideoConfig,
126} from 'remotion';
127import maplibregl, {type GeoJSONSource, type Map} from 'maplibre-gl';
128import 'maplibre-gl/dist/maplibre-gl.css';
129 
130const zurich: [number, number] = [8.5417, 47.3769];
131const newYork: [number, number] = [-74.006, 40.7128];
132 
133const greatCircleLine = (from: [number, number], to: [number, number]) => {
134	const route = turf.greatCircle(from, to, {npoints: 100});
135 
136	if (route.geometry.type === 'LineString') {
137		return turf.lineString(route.geometry.coordinates);
138	}
139 
140	// Great-circle routes crossing the antimeridian can become MultiLineString.
141	// Keep the example valid by choosing the longest segment.
142	const longestSegment = route.geometry.coordinates.reduce((longest, segment) => {
143		return segment.length > longest.length ? segment : longest;
144	});
145 
146	return turf.lineString(longestSegment);
147};
148 
149const targetRoute = greatCircleLine(zurich, newYork);
150const targetRouteDistance = turf.length(targetRoute);
151 
152const cameraRoute = greatCircleLine(zurich, newYork);
153const cameraRouteDistance = turf.length(cameraRoute);
154 
155const cityMarkers = turf.featureCollection([
156	turf.point(zurich, {name: 'Zurich'}),
157	turf.point(newYork, {name: 'New York'}),
158]);
159 
160const clampProgress = (progress: number) => Math.min(1, Math.max(0, progress));
161 
162const distanceAlong = (totalDistance: number, progress: number) => {
163	// Keep the route non-empty at progress 0; Turf can error on zero-length slices.
164	return Math.max(0.001, totalDistance * clampProgress(progress));
165};
166 
167const getPartialTargetRoute = (progress: number) => {
168	return turf.lineSliceAlong(
169		targetRoute,
170		0,
171		distanceAlong(targetRouteDistance, progress),
172	);
173};
174 
175const getCameraOptions = (
176	map: Map,
177	progress: number,
178	cameraAltitudeMeters: number,
179	cameraLatitudeOffset: number,
180) => {
181	const target = turf.along(
182		targetRoute,
183		distanceAlong(targetRouteDistance, progress),
184	).geometry.coordinates;
185	const camera = turf.along(
186		cameraRoute,
187		distanceAlong(cameraRouteDistance, progress),
188	).geometry.coordinates;
189 
190	return map.calculateCameraOptionsFromTo(
191		new maplibregl.LngLat(camera[0], camera[1] - cameraLatitudeOffset),
192		cameraAltitudeMeters,
193		new maplibregl.LngLat(target[0], target[1]),
194	);
195};
196 
197export const MyComposition = () => {
198	const containerRef = useRef<HTMLDivElement>(null);
199	const frame = useCurrentFrame();
200	const {delayRender, continueRender} = useDelayRender();
201	const {durationInFrames, height, width} = useVideoConfig();
202	const [map, setMap] = useState<Map | null>(null);
203	const [loadingHandle] = useState(() => delayRender('Loading MapLibre map'));
204 
205	useEffect(() => {
206		if (!containerRef.current) {
207			return;
208		}
209 
210		const mapInstance = new maplibregl.Map({
211			container: containerRef.current,
212			style: 'https://demotiles.maplibre.org/style.json',
213			center: zurich,
214			zoom: 7,
215			interactive: false,
216			attributionControl: false,
217			fadeDuration: 0,
218			canvasContextAttributes: {
219				preserveDrawingBuffer: true,
220			},
221		});
222 
223		mapInstance.on('load', () => {
224			mapInstance.addSource('trace', {
225				type: 'geojson',
226				data: getPartialTargetRoute(0),
227			});
228 
229			mapInstance.addLayer({
230				id: 'trace-line',
231				type: 'line',
232				source: 'trace',
233				layout: {
234					'line-cap': 'round',
235					'line-join': 'round',
236				},
237				paint: {
238					'line-color': '#111111',
239					'line-width': 7,
240				},
241			});
242 
243			mapInstance.addSource('city-markers', {
244				type: 'geojson',
245				data: cityMarkers,
246			});
247 
248			mapInstance.addLayer({
249				id: 'city-marker-dots',
250				type: 'circle',
251				source: 'city-markers',
252				paint: {
253					'circle-color': '#f03b20',
254					'circle-radius': 12,
255					'circle-stroke-color': '#ffffff',
256					'circle-stroke-width': 4,
257				},
258			});
259 
260			mapInstance.addLayer({
261				id: 'city-marker-labels',
262				type: 'symbol',
263				source: 'city-markers',
264				layout: {
265					'text-allow-overlap': true,
266					'text-anchor': 'top',
267					'text-field': ['get', 'name'],
268					'text-offset': [0, 0.9],
269					'text-size': 28,
270				},
271				paint: {
272					'text-color': '#111111',
273					'text-halo-color': '#ffffff',
274					'text-halo-width': 3,
275				},
276			});
277 
278			mapInstance.jumpTo(getCameraOptions(mapInstance, 0, 180000, 1.1));
279			mapInstance.once('idle', () => {
280				setMap(mapInstance);
281				continueRender(loadingHandle);
282			});
283		});
284	}, [continueRender, loadingHandle]);
285 
286	useEffect(() => {
287		if (!map) {
288			return;
289		}
290 
291		const handle = delayRender('Rendering MapLibre frame');
292		const timelineProgress = interpolate(frame, [0, durationInFrames - 1], [0, 1], {
293			extrapolateLeft: 'clamp',
294			extrapolateRight: 'clamp',
295		});
296		const travelProgress = interpolate(timelineProgress, [0.2, 0.82], [0, 1], {
297			extrapolateLeft: 'clamp',
298			extrapolateRight: 'clamp',
299			easing: Easing.inOut(Easing.cubic),
300		});
301		const cameraAltitudeMeters = interpolate(
302			timelineProgress,
303			[0, 0.28, 0.74, 1],
304			[180000, 2200000, 2200000, 180000],
305			{
306				extrapolateLeft: 'clamp',
307				extrapolateRight: 'clamp',
308				easing: Easing.inOut(Easing.cubic),
309			},
310		);
311		const cameraLatitudeOffset = interpolate(
312			timelineProgress,
313			[0, 0.28, 0.74, 1],
314			[1.1, 8, 8, 1.1],
315			{
316				extrapolateLeft: 'clamp',
317				extrapolateRight: 'clamp',
318				easing: Easing.inOut(Easing.cubic),
319			},
320		);
321		const trace = map.getSource('trace') as GeoJSONSource | undefined;
322 
323		trace?.setData(getPartialTargetRoute(travelProgress));
324		map.jumpTo(
325			getCameraOptions(
326				map,
327				travelProgress,
328				cameraAltitudeMeters,
329				cameraLatitudeOffset,
330			),
331		);
332 
333		map.once('idle', () => continueRender(handle));
334		// Force an idle event even if the camera parameters are unchanged from the previous frame.
335		map.triggerRepaint();
336	}, [continueRender, delayRender, durationInFrames, frame, map]);
337 
338	return (
339		<AbsoluteFill style={{backgroundColor: '#e8eef3'}}>
340			<div ref={containerRef} style={{height, position: 'absolute', width}} />
341		</AbsoluteFill>
342	);
343};
344```
345 
346## Camera guidance
347 
348Use MapLibre's camera helper for camera movement:
349 
350```ts
351map.calculateCameraOptionsFromTo(cameraLngLat, cameraAltitudeMeters, targetLngLat);
352```
353 
354A good pattern is to keep two concepts separate:
355 
356- `targetRoute`: where the animated line is and where the camera looks.
357- `cameraRoute`: where the camera moves.
358 
359Then use Turf to read positions from both routes for the same progress value:
360 
361```ts
362const target = turf.along(targetRoute, targetDistance * progress).geometry.coordinates;
363const camera = turf.along(cameraRoute, cameraDistance * progress).geometry.coordinates;
364 
365map.jumpTo(
366	map.calculateCameraOptionsFromTo(
367		new maplibregl.LngLat(camera[0], camera[1]),
368		cameraAltitudeMeters,
369		new maplibregl.LngLat(target[0], target[1]),
370	),
371);
372```
373 
374For zoom-out / travel / zoom-in animations, animate travel progress separately from camera altitude. Camera altitude is measured in meters. This avoids heavy custom camera math.
375 
376## Lines
377 
378Use GeoJSON sources for lines. Unless the user asks, do not add glow effects or extra decorative points.
379 
380For geodesic flight routes, use Turf:
381 
382```ts
383const line = greatCircleLine(start, end);
384const distance = turf.length(line);
385const partialLine = turf.lineSliceAlong(
386	line,
387	0,
388	// Keep the route non-empty at progress 0.
389	Math.max(0.001, distance * progress),
390);
391```
392 
393For a visually straight line on the map, use a simple GeoJSON `LineString` between the two points instead of `greatCircle()`.
394 
395## Markers and labels
396 
397Use map-native GeoJSON layers for markers and labels:
398 
399```tsx
400mapInstance.addSource('markers', {
401	type: 'geojson',
402	data: turf.featureCollection([
403		turf.point([-118.2437, 34.0522], {name: 'Los Angeles'}),
404	]),
405});
406 
407mapInstance.addLayer({
408	id: 'marker-dots',
409	type: 'circle',
410	source: 'markers',
411	paint: {
412		'circle-color': '#f03b20',
413		'circle-radius': 12,
414		'circle-stroke-color': '#ffffff',
415		'circle-stroke-width': 4,
416	},
417});
418 
419mapInstance.addLayer({
420	id: 'marker-labels',
421	type: 'symbol',
422	source: 'markers',
423	layout: {
424		'text-allow-overlap': true,
425		'text-anchor': 'top',
426		'text-field': ['get', 'name'],
427		'text-offset': [0, 0.9],
428		'text-size': 28,
429	},
430	paint: {
431		'text-color': '#111111',
432		'text-halo-color': '#ffffff',
433		'text-halo-width': 3,
434	},
435});
436```
437 
438Make marker sizes and label font sizes large enough for the composition resolution.
439 
440## Styles
441 
442Default to the stock MapLibre demo style:
443 
444```ts
445style: 'https://demotiles.maplibre.org/style.json'
446```
447 
448If the user requests another style, use any valid MapLibre style JSON URL.
449 
450## Rendering
451 
452For WebGL map renders, prefer single concurrency and ANGLE:
453 
454```bash
455bunx remotion render [composition-id] out/video.mp4 --gl=angle --concurrency=1
456```
457 
458Use the equivalent package runner for the project. In npm projects, use `npx`; in Bun projects, use `bunx`.
459