Unlocking Mapbox GL JS's Hidden Field of View Control

Andrew Sepic — Tue, 10 Feb 2026 14:49:30 +0000

Ever wished you could make your Mapbox map look more like a telephoto lens or a dramatic wide-angle shot? Turns out, there's an undocumented way to control the camera's field of view (FOV) in Mapbox GL JS—but with a big caveat: this is not a public API.

⚠️ Developer Warning: What I'm about to show you involves accessing private internal properties. Use this only for experiments, prototypes, and creative projects. Don't rely on this in production—it could break in any future Mapbox version without notice.

The Problem: Fixed Field of View

By default, Mapbox GL JS uses a fixed vertical field of view of approximately 36.87 degrees (0.643 radians). This gives maps a consistent, neutral perspective. But what if you want to:

Create a telephoto effect (narrow FOV) for architectural visualization
Achieve a dramatic wide-angle view (large FOV) for immersive experiences
Dynamically adjust the visual perspective based on user interaction

The official Mapbox API doesn't expose FOV control—but the internal Transform class does.

What is the Transform Class?

Digging through the Mapbox GL JS source code, I discovered the Transform class—the mathematical heart of Mapbox's rendering system. This 2,800+ line beast handles:

Camera positioning and orientation
Projection matrix calculations
Coordinate system transformations (lat/lng ↔ screen pixels ↔ mercator)
Zoom level calculations
Field of view management

The Transform instance lives at map.transform and contains a private _fov property that controls the vertical field of view.

The (Unofficial) Solution

Here's how you can control field of view with a custom function called setFOV.

function setFOV(map, fov) {
  // Directly access the internal Transform instance
  map.transform._fov = fov;

  // Force recalculation of projection matrices
  map.transform._calcMatrices();

  // Trigger a map repaint
  map.triggerRepaint();
}

// Initialize your map
const map = new mapboxgl.Map({
  container: 'map-container',
  center: [-71.06288, 42.36834],
  zoom: 16.85,
  pitch: 75.67,
  bearing: 141.60
});

map.on('load', () => {
  // Apply a custom FOV (in radians)
  setFOV(map, 0.8); // Wide angle
  // setFOV(map, 0.4); // Telephoto
});

FOV Values Explained

Radians	FOV effect
0.1 - 0.5 radians (~5-28°): Telephoto effect, compressed perspective
0.643 radians (~36.87°): Default Mapbox FOV
0.8 - 1.5 radians (~45-86°): Wide angle, dramatic perspective

How It Works Under the Hood

When you modify _fov, three things need to happen:

Update the property: map.transform._fov = newValue
Recalculate matrices: map.transform._calcMatrices() recomputes all the projection math including:
- projMatrix - world to clip coordinates
- pixelMatrix - world to screen pixels
- cameraToCenterDistance - camera distance based on FOV
Trigger repaint: map.triggerRepaint() forces a redraw with new matrices

The _calcMatrices() method is where the magic happens. From the source:

this.cameraToCenterDistance = 0.5 / Math.tan(this._fov * 0.5) * 
  this.height * this._pixelsPerMercatorPixel;

This calculates how far the camera should be from the map center based on the FOV, ensuring the perspective projection renders correctly.

Interactive Field of View Controller

Want to let users adjust FOV dynamically? Here's a complete example with a slider you can check on on Codepen.

Why Isn't This a Public API?

You might wonder why Mapbox doesn't officially expose FOV control. A few reasons:

Complexity: Changing FOV affects tile loading, symbol placement, and many other rendering systems
Performance: Non-standard FOV values can impact rendering performance
Consistency: A fixed FOV ensures consistent user experience across applications
Maintenance: Supporting arbitrary FOV would increase API surface area and testing burden

The Risks

Before you rush to implement this, understand the risks:

⚠️ Breaking changes: Internal APIs can change without warning in minor/patch releases
⚠️ Unsupported behavior: You may encounter rendering artifacts or unexpected behavior
⚠️ No guarantees: Mapbox won't provide support for issues arising from this technique
⚠️ Version locked: You'll need to test across Mapbox versions if you update

Alternative: The FreeCamera API

For production use cases involving advanced camera control, check out Mapbox's official FreeCamera API. While it doesn't expose FOV directly, it provides:

Full camera position control
Orientation adjustments
Supported and stable API
Works with all Mapbox features

Conclusion

Exploring internal APIs like Transform is a fantastic way to understand how sophisticated mapping libraries work under the hood. The FOV control technique shown here opens creative possibilities for enthusiasts and experimental projects.

Just remember: with great power comes great responsibility. Use internal APIs wisely, always have a fallback, and consider this a learning exercise rather than a production strategy.

Tested with Mapbox GL JS v3.18.1. Your mileage may vary with other versions.

Additional Resources

Build quickly with npm create @mapbox/web-app

Andrew Sepic — Fri, 12 Dec 2025 15:45:44 +0000

The Mapbox Developer Relations team recently released a new developer tool to help web developers quickly scaffold Mapbox GL JS into their favorite frontend frameworks. You can now go from zero to hero with a map in your app in about 10 seconds. 🚀

To get started, ensure you have npm installed and run the command in your terminal.

$ npm create @mapbox/web-app

(Requires Node.js v20+.)

Why this is helpful

If you work with Mapbox GL JS in modern JavaScript frameworks, you'll know that spinning up a map in your app can take more time and effort than you'd like. This tool abstracts away project configuration, dependency management and lets developers get a simple map running very quickly. This allows you to test ideas & features fast, without having to clone a local repo or project as a starting point.

`npm create @mapbox/web-app`

The npm create @mapbox/web-app package is a CLI tool that uses Vite templates to quickly build a project into the following frameworks:

Vanilla JS (with & without a bundler)
React
Vue
Svelte
Angular

You can also also add interactive search to your map by adding Mapbox Search JS via the install prompts.

The CLI tooling asks 4 questions:

Which framework do you want to use?
Choose a project name..
Access Token - Insert your public Mapbox access token and the tooling will pass this into the appropriate local .env file. Get yours from your developer console
Add Search JS (or not)

After answering those questions you'll have a full-screen Mapbox GL JS map loading in the browser within seconds, ready for you to customize. 🔥

Next Steps

Now that you have a full screen map loaded, where do you want to go next? If you are a new developer using Mapbox, you can expand this simple application by following one of these tutorials:

The tutorials above demonstrate state management best practices for these frameworks, how to track & display map state into the application UI and how to trigger map events from the UI.

If you are an experienced developer and are familiar with Mapbox products, you can browse our tutorials for inspiration or search them for your use case.

More Information on Github

You can find more information about this CLI tool and report issues on Github.

Forem: Andrew Sepic