Viewport

The viewport controls the camera position — where the map is looking and from what angle.

Properties

• center — [lng, lat] — map center as longitude, latitude (default: [0, 20])
• zoom — number — zoom level 0–24 (default: 1.5)
• pitch — number — camera tilt in degrees 0–85 (default: 0)
• bearing — number — camera rotation in degrees -180–180, 0 = north (default: 0)
• bounds — [west, south, east, north] — fit map to bounding box (overrides center/zoom)
• projection — "mercator" | "globe" — map projection (default: "mercator")

Center and Zoom

The most common viewport: point the map at a location with a zoom level.

{
  "center": [-73.98, 40.75],
  "zoom": 13
}

Zoom levels:

• 0–2 — world view
• 3–6 — country/region
• 7–10 — city
• 11–14 — neighborhood
• 15–18 — street level
• 19–24 — building detail

Pitch and Bearing

Add a 3D perspective with pitch (tilt) and bearing (rotation).

{
  "center": [139.69, 35.68],
  "zoom": 15,
  "pitch": 60,
  "bearing": 45
}

This shows Tokyo tilted at 60 degrees, rotated 45 degrees from north.

Bounds

Instead of center/zoom, you can specify a bounding box. The map will automatically fit to show the entire area with padding.

{
  "bounds": [-74.26, 40.49, -73.70, 40.92]
}

This fits the map to show all of New York City. The format is [west, south, east, north].

When bounds is set, it takes priority over center and zoom.

Projection

Switch between flat Mercator and 3D globe projection.

{
  "center": [0, 20],
  "zoom": 1.5,
  "projection": "globe"
}

• "mercator" — default flat projection, standard for most maps
• "globe" — 3D spherical view, great for world-scale visualizations

Transitions

When the spec changes, viewport updates animate smoothly:

• center/zoom/pitch/bearing — uses flyTo() for a smooth camera animation
• bounds — uses fitBounds() with 40px padding

The initial render sets the viewport instantly (no animation).