1---
2name: maps
3description: Make map animations with Mapbox
4metadata:
5  tags: map, map animation, mapbox
6---
7 
8Maps can be added to a Remotion video with Mapbox.  
9The [Mapbox documentation](https://docs.mapbox.com/mapbox-gl-js/api/) has the API reference.
10 
11## Prerequisites
12 
13Mapbox and `@turf/turf` need to be installed.
14 
15Search the project for lockfiles and run the correct command depending on the package manager:
16 
17If `package-lock.json` is found, use the following command:
18 
19```bash
20npm i mapbox-gl @turf/turf @types/mapbox-gl
21```
22 
23If `bun.lock` is found, use the following command:
24 
25```bash
26bun i mapbox-gl @turf/turf @types/mapbox-gl
27```
28 
29If `yarn.lock` is found, use the following command:
30 
31```bash
32yarn add mapbox-gl @turf/turf @types/mapbox-gl
33```
34 
35If `pnpm-lock.yaml` is found, use the following command:
36 
37```bash
38pnpm i mapbox-gl @turf/turf @types/mapbox-gl
39```
40 
41The user needs to create a free Mapbox account and create an access token by visiting https://console.mapbox.com/account/access-tokens/.
42 
43The mapbox token needs to be added to the `.env` file:
44 
45```txt title=".env"
46REMOTION_MAPBOX_TOKEN==pk.your-mapbox-access-token
47```
48 
49## Adding a map
50 
51Here is a basic example of a map in Remotion.
52 
53```tsx
54import { useEffect, useMemo, useRef, useState } from "react";
55import { AbsoluteFill, useDelayRender, useVideoConfig } from "remotion";
56import mapboxgl, { Map } from "mapbox-gl";
57 
58export const lineCoordinates = [
59  [6.56158447265625, 46.059891147620725],
60  [6.5691375732421875, 46.05679376154153],
61  [6.5842437744140625, 46.05059898938315],
62  [6.594886779785156, 46.04702502069337],
63  [6.601066589355469, 46.0460718554722],
64  [6.6089630126953125, 46.0365370783104],
65  [6.6185760498046875, 46.018420689207964],
66];
67 
68mapboxgl.accessToken = process.env.REMOTION_MAPBOX_TOKEN as string;
69 
70export const MyComposition = () => {
71  const ref = useRef<HTMLDivElement>(null);
72  const { delayRender, continueRender } = useDelayRender();
73 
74  const { width, height } = useVideoConfig();
75  const [handle] = useState(() => delayRender("Loading map..."));
76  const [map, setMap] = useState<Map | null>(null);
77 
78  useEffect(() => {
79    const _map = new Map({
80      container: ref.current!,
81      zoom: 11.53,
82      center: [6.5615, 46.0598],
83      pitch: 65,
84      bearing: 0,
85      style: "⁠mapbox://styles/mapbox/standard",
86      interactive: false,
87      fadeDuration: 0,
88    });
89 
90    _map.on("style.load", () => {
91      // Hide all features from the Mapbox Standard style
92      const hideFeatures = [
93        "showRoadsAndTransit",
94        "showRoads",
95        "showTransit",
96        "showPedestrianRoads",
97        "showRoadLabels",
98        "showTransitLabels",
99        "showPlaceLabels",
100        "showPointOfInterestLabels",
101        "showPointsOfInterest",
102        "showAdminBoundaries",
103        "showLandmarkIcons",
104        "showLandmarkIconLabels",
105        "show3dObjects",
106        "show3dBuildings",
107        "show3dTrees",
108        "show3dLandmarks",
109        "show3dFacades",
110      ];
111      for (const feature of hideFeatures) {
112        _map.setConfigProperty("basemap", feature, false);
113      }
114 
115      _map.setConfigProperty("basemap", "colorTrunks", "rgba(0, 0, 0, 0)");
116 
117      _map.addSource("trace", {
118        type: "geojson",
119        data: {
120          type: "Feature",
121          properties: {},
122          geometry: {
123            type: "LineString",
124            coordinates: lineCoordinates,
125          },
126        },
127      });
128      _map.addLayer({
129        type: "line",
130        source: "trace",
131        id: "line",
132        paint: {
133          "line-color": "black",
134          "line-width": 5,
135        },
136        layout: {
137          "line-cap": "round",
138          "line-join": "round",
139        },
140      });
141    });
142 
143    _map.on("load", () => {
144      continueRender(handle);
145      setMap(_map);
146    });
147  }, [handle, lineCoordinates]);
148 
149  const style: React.CSSProperties = useMemo(
150    () => ({ width, height, position: "absolute" }),
151    [width, height],
152  );
153 
154  return <AbsoluteFill ref={ref} style={style} />;
155};
156```
157 
158The following is important in Remotion:
159 
160- Animations must be driven by `useCurrentFrame()` and animations that Mapbox brings itself should be disabled. For example, the `fadeDuration` prop should be set to `0`, `interactive` should be set to `false`, etc.
161- Loading the map should be delayed using `useDelayRender()` and the map should be set to `null` until it is loaded.
162- The element containing the ref MUST have an explicit width and height and `position: "absolute"`.
163- Do not add a `_map.remove();` cleanup function.
164 
165## Drawing lines
166 
167Unless I request it, do not add a glow effect to the lines.
168Unless I request it, do not add additional points to the lines.
169 
170## Map style
171 
172By default, use the `mapbox://styles/mapbox/standard` style.  
173Hide the labels from the base map style.
174 
175Unless I request otherwise, remove all features from the Mapbox Standard style.
176 
177```tsx
178// Hide all features from the Mapbox Standard style
179const hideFeatures = [
180  "showRoadsAndTransit",
181  "showRoads",
182  "showTransit",
183  "showPedestrianRoads",
184  "showRoadLabels",
185  "showTransitLabels",
186  "showPlaceLabels",
187  "showPointOfInterestLabels",
188  "showPointsOfInterest",
189  "showAdminBoundaries",
190  "showLandmarkIcons",
191  "showLandmarkIconLabels",
192  "show3dObjects",
193  "show3dBuildings",
194  "show3dTrees",
195  "show3dLandmarks",
196  "show3dFacades",
197];
198for (const feature of hideFeatures) {
199  _map.setConfigProperty("basemap", feature, false);
200}
201 
202_map.setConfigProperty("basemap", "colorMotorways", "transparent");
203_map.setConfigProperty("basemap", "colorRoads", "transparent");
204_map.setConfigProperty("basemap", "colorTrunks", "transparent");
205```
206 
207## Animating the camera
208 
209You can animate the camera along the line by adding a `useEffect` hook that updates the camera position based on the current frame.
210 
211Unless I ask for it, do not jump between camera angles.
212 
213```tsx
214import * as turf from "@turf/turf";
215import { interpolate } from "remotion";
216import { Easing } from "remotion";
217import { useCurrentFrame, useVideoConfig, useDelayRender } from "remotion";
218 
219const animationDuration = 20;
220const cameraAltitude = 4000;
221```
222 
223```tsx
224const frame = useCurrentFrame();
225const { fps } = useVideoConfig();
226const { delayRender, continueRender } = useDelayRender();
227 
228useEffect(() => {
229  if (!map) {
230    return;
231  }
232  const handle = delayRender("Moving point...");
233 
234  const routeDistance = turf.length(turf.lineString(lineCoordinates));
235 
236  const progress = interpolate(
237    frame / fps,
238    [0.00001, animationDuration],
239    [0, 1],
240    {
241      easing: Easing.inOut(Easing.sin),
242      extrapolateLeft: "clamp",
243      extrapolateRight: "clamp",
244    },
245  );
246 
247  const camera = map.getFreeCameraOptions();
248 
249  const alongRoute = turf.along(
250    turf.lineString(lineCoordinates),
251    routeDistance * progress,
252  ).geometry.coordinates;
253 
254  camera.lookAtPoint({
255    lng: alongRoute[0],
256    lat: alongRoute[1],
257  });
258 
259  map.setFreeCameraOptions(camera);
260  map.once("idle", () => continueRender(handle));
261}, [lineCoordinates, fps, frame, handle, map]);
262```
263 
264Notes:
265 
266IMPORTANT: Keep the camera by default so north is up.
267IMPORTANT: For multi-step animations, set all properties at all stages (zoom, position, line progress) to prevent jumps. Override initial values.
268 
269- The progress is clamped to a minimum value to avoid the line being empty, which can lead to turf errors
270- See [Timing](./timing.md) for more options for timing.
271- Consider the dimensions of the composition and make the lines thick enough and the label font size large enough to be legible for when the composition is scaled down.
272 
273## Animating lines
274 
275### Straight lines (linear interpolation)
276 
277To animate a line that appears straight on the map, use linear interpolation between coordinates. Do NOT use turf's `lineSliceAlong` or `along` functions, as they use geodesic (great circle) calculations which appear curved on a Mercator projection.
278 
279```tsx
280const frame = useCurrentFrame();
281const { durationInFrames } = useVideoConfig();
282 
283useEffect(() => {
284  if (!map) return;
285 
286  const animationHandle = delayRender("Animating line...");
287 
288  const progress = interpolate(frame, [0, durationInFrames - 1], [0, 1], {
289    extrapolateLeft: "clamp",
290    extrapolateRight: "clamp",
291    easing: Easing.inOut(Easing.cubic),
292  });
293 
294  // Linear interpolation for a straight line on the map
295  const start = lineCoordinates[0];
296  const end = lineCoordinates[1];
297  const currentLng = start[0] + (end[0] - start[0]) * progress;
298  const currentLat = start[1] + (end[1] - start[1]) * progress;
299 
300  const lineData: GeoJSON.Feature<GeoJSON.LineString> = {
301    type: "Feature",
302    properties: {},
303    geometry: {
304      type: "LineString",
305      coordinates: [start, [currentLng, currentLat]],
306    },
307  };
308 
309  const source = map.getSource("trace") as mapboxgl.GeoJSONSource;
310  if (source) {
311    source.setData(lineData);
312  }
313 
314  map.once("idle", () => continueRender(animationHandle));
315}, [frame, map, durationInFrames]);
316```
317 
318### Curved lines (geodesic/great circle)
319 
320To animate a line that follows the geodesic (great circle) path between two points, use turf's `lineSliceAlong`. This is useful for showing flight paths or the actual shortest distance on Earth.
321 
322```tsx
323import * as turf from "@turf/turf";
324 
325const routeLine = turf.lineString(lineCoordinates);
326const routeDistance = turf.length(routeLine);
327 
328const currentDistance = Math.max(0.001, routeDistance * progress);
329const slicedLine = turf.lineSliceAlong(routeLine, 0, currentDistance);
330 
331const source = map.getSource("route") as mapboxgl.GeoJSONSource;
332if (source) {
333  source.setData(slicedLine);
334}
335```
336 
337## Markers
338 
339Add labels, and markers where appropriate.
340 
341```tsx
342_map.addSource("markers", {
343  type: "geojson",
344  data: {
345    type: "FeatureCollection",
346    features: [
347      {
348        type: "Feature",
349        properties: { name: "Point 1" },
350        geometry: { type: "Point", coordinates: [-118.2437, 34.0522] },
351      },
352    ],
353  },
354});
355 
356_map.addLayer({
357  id: "city-markers",
358  type: "circle",
359  source: "markers",
360  paint: {
361    "circle-radius": 40,
362    "circle-color": "#FF4444",
363    "circle-stroke-width": 4,
364    "circle-stroke-color": "#FFFFFF",
365  },
366});
367 
368_map.addLayer({
369  id: "labels",
370  type: "symbol",
371  source: "markers",
372  layout: {
373    "text-field": ["get", "name"],
374    "text-font": ["DIN Pro Bold", "Arial Unicode MS Bold"],
375    "text-size": 50,
376    "text-offset": [0, 0.5],
377    "text-anchor": "top",
378  },
379  paint: {
380    "text-color": "#FFFFFF",
381    "text-halo-color": "#000000",
382    "text-halo-width": 2,
383  },
384});
385```
386 
387Make sure they are big enough. Check the composition dimensions and scale the labels accordingly.
388For a composition size of 1920x1080, the label font size should be at least 40px.
389 
390IMPORTANT: Keep the `text-offset` small enough so it is close to the marker. Consider the marker circle radius. For a circle radius of 40, this is a good offset:
391 
392```tsx
393"text-offset": [0, 0.5],
394```
395 
396## 3D buildings
397 
398To enable 3D buildings, use the following code:
399 
400```tsx
401_map.setConfigProperty("basemap", "show3dObjects", true);
402_map.setConfigProperty("basemap", "show3dLandmarks", true);
403_map.setConfigProperty("basemap", "show3dBuildings", true);
404```
405 
406## Rendering
407 
408When rendering a map animation, make sure to render with the following flags:
409 
410```
411npx remotion render --gl=angle --concurrency=1
412```
413