Remotion Rule: Maps

What it is

Remotion Rule: Maps is a skill rule within the Remotion Agent Skill ecosystem. It provides instructions and patterns for creating animated map visualizations using Mapbox GL inside Remotion, the React-based programmatic video framework. The rule teaches AI coding agents how to render map flyovers, route animations, marker transitions, and geographic data visualizations as video frames.

This rule targets developers and AI agents building data-driven video content that includes geographic visualizations: travel videos, logistics dashboards, real estate tours, or news graphics with map context.

How it saves time or tokens

Without this skill rule, an AI agent would need to figure out the integration between Remotion's frame-based rendering model and Mapbox GL's JavaScript API from scratch. The rule encodes the correct patterns: how to interpolate camera positions across frames, how to render Mapbox tiles at specific zoom levels, and how to synchronize map animations with other video elements. This eliminates trial-and-error prompt cycles.

The rule also documents known pitfalls (tile loading timing, headless rendering constraints) that would otherwise consume debugging time and tokens.

How to use

1. Install Remotion and the Mapbox GL package: npm install remotion @remotion/player mapbox-gl. Get a Mapbox access token from mapbox.com.
2. Add the Remotion Maps rule to your AI agent's skill set (e.g., in Claude Code's .claude/rules/ or Cursor rules).
3. Prompt your AI agent to create a map animation. The rule guides the agent to use the correct Remotion + Mapbox integration patterns.

Example

import { useCurrentFrame, interpolate } from 'remotion';
import mapboxgl from 'mapbox-gl';
import { useEffect, useRef } from 'react';

export const MapFlyover: React.FC = () => {
  const frame = useCurrentFrame();
  const mapRef = useRef<mapboxgl.Map | null>(null);

  const lat = interpolate(frame, [0, 150], [37.7749, 40.7128]);
  const lng = interpolate(frame, [0, 150], [-122.4194, -74.0060]);
  const zoom = interpolate(frame, [0, 75, 150], [12, 5, 12]);

  useEffect(() => {
    if (mapRef.current) {
      mapRef.current.setCenter([lng, lat]);
      mapRef.current.setZoom(zoom);
    }
  }, [frame]);

  return <div id='map' style={{ width: 1920, height: 1080 }} />;
};

This component creates a camera flyover from San Francisco to New York, interpolating latitude, longitude, and zoom across 150 frames.

Related on TokRepo

• AI tools for video — Video generation and editing tools
• AI tools for design — Visual content creation tools

Common pitfalls

• Mapbox tiles load asynchronously. In Remotion's rendering pipeline, you must ensure tiles are fully loaded before capturing each frame. Use delayRender and continueRender to handle async tile loading.
• Mapbox GL requires a valid access token. Free tier includes limited map loads per month. High-frame-count videos can consume map loads quickly.
• Headless rendering (for video export) requires a WebGL context. Ensure your rendering environment supports GPU-accelerated WebGL or use software rendering fallbacks.