DEV Community: Mapbox

Rebuilding geojson.io: A Look at the 2026 Overhaul

Andrew Sepic — Mon, 10 Aug 2026 15:37:35 +0000

If you've worked with spatial data on the web, you've probably used geojson.io. Since Tom MacWright first built it in 2013, it's become one of those quietly indispensable tools in the mapping community — drop in a GeoJSON file, sketch a polygon, grab a quick bounding box, copy the coordinates back out. No GIS software, no setup, just a browser tab.

geojson.io screenshot from October 2, 2015 - courtesy of Wayback Machine

This year we shipped the biggest change in the app's 13 year history: a full overhaul of the editor, cut over to production on June 1, 2026. Below is how we approached this, what changed, why, and what's shipped since.

Why overhaul it

geojson.io's core had aged in place for a while. Under the hood, it had already been through one generation of map tech — originally built on Leaflet-based Mapbox.js library, then refactored to Mapbox GL JS and Mapbox GL Draw in 2022 — but the application itself never changed alongside it. The UI was built entirely with D3, using its selection and data-join API as a general application-construction tool rather than for what it's best known for: data visualization. D3 has no built-in component model or state management, so anything beyond simple DOM bindings meant hand-rolling patterns a modern framework gives you for free.

Rather than start from the ground up, we forked Placemark Play — an open-source geojson editor, also built by Tom MacWright, with an editing model designed from the start around multiselect and structured data editing — and adapted it into geojson.io's new foundation.

How we approached it

Rewriting a decade-old tool creates an obvious risk: breaking workflows people depend on in the name of modernization. So one guiding principle shaped the whole project — treat every piece of legacy functionality as a question, not a given. Is this still useful? If so, does it need to look the same, or can it be replicated in a different pattern that fits better with the new architecture? Some features carried over largely unchanged; others got rebuilt around Placemark's multiselect-first editing model because the old pattern didn't make sense once "selection" could mean more than one feature at a time. That same audit ran in both directions — Placemark Play came with plenty of its own functionality that didn't serve geojson.io's specific mission, so a fair amount of the fork was just as much about stripping code out as building on top of it.

We also didn't cut over all at once. The update launched quietly at a parallel /next path back in January 2026, running alongside the legacy app so real usage and feedback could shape it before it became the default. That turned into a long stretch of triaging GitHub issues and user reports — and a lot of it wasn't about missing features so much as discovering how people were actually using geojson.io, often in ways we hadn't designed for or could have imagined. Users had built workflows around edge cases and quirks of the old app, well outside anything we'd call the "intended" use case. Each one became a judgment call: is this worth supporting, or would chasing it add complexity and noise the core tool doesn't need? We're still working through some of those today.

It's ended up being as much a product exercise as an engineering one — shaped by feedback from Mapbox teams using it internally, and by the broader open-source GIS/mapping community, who've been generous (and opinionated, in the best way) about what they need from a tool like this.

What Placemark gave us

Forking Placemark Play didn't just hand us a newer codebase — it came with capabilities legacy geojson.io never had, the kind of thing that would've been its own multi-month project to build from scratch. Multiselect and bulk editing meant selecting many features at once and updating their properties together, instead of one at a time. Real editing history — undo/redo, copy, duplicate — plus spatial and geometry operations. Improved data management, with a list view and table view alongside the map, name previews for features, and a feature editor that treats properties as structured data instead of a JSON blob you hand-edit. And a codebase built for the present — modern React patterns and TypeScript that are both easier for us to maintain and a lower bar for outside contributors.

The new stack

The overhaul moved the app to React 18, Vite, and TypeScript. A few of the more interesting pieces under the hood:

A More Capable Editing Toolkit All drawing and editing logic is custom, built around a PMap class that wraps Mapbox GL JS (v3.24.0) directly and layers a Deck.gl MapboxOverlay ( (@deck.gl/core, @deck.gl/mapbox, v9) on top for vertex rendering, selection highlighting, and snapping— This keeps a clean separation of concerns: Mapbox GL JS is responsible for rendering the app's GeoJSON data, while Deck.gl owns the editing UI — vertex handles, selection highlighting, and snapping.
State lives in Jotai atoms, with atomWithStorage things like camera position and UI preferences go straight to localStorage/sessionStorage, no separate persistence layer needed.
Heavy lifting happens off the main thread. Format conversion and reprojection — parsing a Shapefile, converting a big XLSX, reprojecting coordinates — runs in a Web Worker, built natively by Vite's worker support, so importing a large file doesn't freeze the map or the UI.
TypeScript earns its keep on the data model. GeoJSON Features, Geometries, and FeatureCollections aren't just untyped JSON — they're well-defined union types, and typing them properly catches a real class of bugs (wrong geometry type, malformed coordinate arrays) at the boundary, before they ever hit the map.

What we built on top

Placemark's foundation covered the editing and data model — what it didn't cover was the specific functionality legacy geojson.io users had come to expect: globe projection, custom raster layers, sharing, and a long tail of smaller behaviors. Closing those gaps, alongside genuinely new capability, has been most of the work since launch:

The geojson text editing panel (using CodeMirror), was a core part of the legacy geojson.io and ensures that your geojson text is still front and center next to your map. This helps beginners understand the geojson specification and formatting and also allows for direct editing and syncing to app state.
Moving the Feature Editor into it's own flexible dynamic pop up, giving full control over a wide array of data on the selected feature.
Simple Style Spec support for Markers & Polygons — render and edit simple style spec marker-color, marker-symbol, fill-color and more.
Custom raster layers, including WMS support and TMS tilesets with inverted Y coordinates, so you can bring your own basemap imagery.
Globe projection and 3D, with a toggle between globe and mercator, plus pitch/rotation for tilted views — integrating globe projection with Deck.gl's still-experimental support was one of the trickier parity problems.
Vertex snapping while dragging, so edited or drawn geometries snap cleanly to nearby features and vertices.
Shareable URLs — features are zipped and base64-encoded into a link, so you can hand someone a working map of your data without a backend.
A steady stream of smaller fixes: streamlined file import for unambiguous formats (GeoJSON, KML, GPX, Shapefile skip the dialog entirely now), mobile panel resizing and two-finger pan while drawing, and persisted camera state that survives a page reload.

It's a lot of surface area for a tool that's supposed to stay simple, and keeping it feeling simple — while adding real capability underneath — has been the actual design challenge of this overhaul.

The new geojson.io

Still open source

geojson.io remains open source, and the overhaul hasn't changed that. If you hit a bug or have a feature request, open an issue on
GitHub — and if you want to see where it's headed, the full changelog is public too.

Thanks to Tom MacWright for building geojson.io in the first place, and for Placemark Play, which gave this project most of its DNA.

Understanding the `near` Parameter in Mapbox's Search Box API

Erwin Soekianto — Fri, 07 Aug 2026 15:31:17 +0000

AI assistants and conversational search are changing how users search for places. Instead of typing an address or dropping a pin, users increasingly ask questions like "Find coffee near the Eiffel Tower" or "Harold Chicken Shack in Chicago." The new near parameter in the Mapbox Search Box API — introduced alongside the new Mapbox Places API (announced July 27, 2026) — makes these natural-language searches easier to implement, by removing the need for a separate geocoding request before you can search.

In this post, we'll break down what near does, why it exists, and how it stacks up against the other location-narrowing parameters Search Box already offers: proximity and bbox.

The problem `near` solves

Traditionally, if you wanted to search for "Harold Chicken Shack" close to Chicago using the /forward endpoint, you had two separate jobs to do:

Put the search term in q — e.g. q=Harold Chicken Shack
Tell the API where to look using proximity or bbox — which meant you needed actual coordinates or a bounding box, not just the word "Chicago"

That works fine for map UIs where you already know the user's location or have a pin on a map. But it breaks down for AI-driven or chat-style search, where a user might just type or say "Harold Chicken Shack in Chicago" — a name and a place, mixed together in plain English, with no coordinate pair in sight. That's the gap near closes.

How `near` works

near accepts either a place-name string (like Chicago, or a broader anchor like California) or an explicit coordinate pair — whichever you have on hand — alongside your search term in q.

near is a convenience layer. When you pass a place name, it first resolves that name via the geocoder's own /forward, then automatically applies the result to your Search Box query. If you pass coordinates directly, near skips the geocoding step and applies them the same way.

The resolution follows a defined hierarchy based on how coarse or fine the anchor is:

`near` value	Resolves to	Effect on `q`
Raw `lon,lat`	Parsed directly	Proximity point
Country (e.g. `United States`)	Geocoded to a country	Bounding box + country filter
Region / state (e.g. `California`)	Geocoded to a region	Bounding box
Place / locality (e.g. `Chicago`)	Geocoded to a place	Proximity point
Neighborhood / address / POI (e.g. `Eiffel Tower`)	Geocoded to a fine feature	Proximity point

In other words: countries and regions/states constrain results by bbox; everything finer than that (cities, neighborhoods, addresses, landmarks) biases results by proximity — which is why a strongly relevant result just outside the anchor can still appear (this is intentional and desirable). Country-level anchors get one thing regions don't: on top of the bbox, near also applies the dedicated country parameter (an ISO 3166-1 alpha-2 code, like US).

One more mechanical detail worth knowing: if you pass both near and proximity in the same request, near takes precedence — it overrides proximity, and promotes whatever proximity value you'd set to origin instead.

Worth noting: passing something coarser, like near=California, is broad enough to constrain results with a bbox instead of just biasing them. Which behavior you get depends on how specific or coarse the anchor is, per the table above.

Here's what that manual, two-step process actually looks like without near — first geocoding "Chicago" via Geocoding v6 /forward, then passing the resulting coordinates into Search Box as proximity:

# Step 1: geocode "Chicago" to get coordinates
https://api.mapbox.com/search/geocode/v6/forward?q=Chicago&access_token=YOUR_MAPBOX_ACCESS_TOKEN
# → returns coordinates around -87.6298,41.8781

# Step 2: pass those coordinates into Search Box as proximity
https://api.mapbox.com/search/searchbox/v1/forward?q=Harold%20Chicken%20Shack&proximity=-87.6298,41.8781&access_token=YOUR_MAPBOX_ACCESS_TOKEN

With near, both of those become a single request:

https://api.mapbox.com/search/searchbox/v1/forward?q=Harold%20Chicken%20Shack&near=Chicago&access_token=YOUR_MAPBOX_ACCESS_TOKEN

Same result, one less network round trip.

This is also the connective tissue between Search Box and the new Places API. The typical flow now looks like:

Send a Search Box /forward query that includes near
Get back a mapbox_id
Feed that ID into the Places API's Details endpoint to pull the full enriched record (hours, photos, busyness, attributes, etc.)

One more thing worth knowing: near isn't limited to /forward — it's also supported on /suggest and /category with identical resolution semantics (it's not available on /retrieve or /reverse). So this same pattern applies whether you're building autocomplete, one-shot search, or category browse.

Where this fits in a real product

It's worth being explicit about something the API itself doesn't tell you: near doesn't do any natural-language parsing. It only resolves a location string (or coordinates) that's already been isolated — it doesn't pull "Harold Chicken Shack" and "Chicago" apart out of a single sentence for you. That separation has to happen before you ever call the Search Box API, and whose job that is depends on where your input is coming from:

Structured UI — a traditional search box with a separate location field, a map pin, a "search near me" button, a saved address. Here you already have the two pieces separately (no parsing needed) — you just pass them straight into q and near as-is.
Conversational or AI-driven input — a chatbot, voice assistant, or LLM-powered search bar where the user hands you one freeform sentence. Here, something upstream of your Search Box call — an LLM prompt, an NLU/intent-extraction step, or simpler pattern matching for known formats — has to do the decomposition shown below. near doesn't replace that step; it's the thing you call after it, so you're not also manually geocoding the location piece yourself.

Splitting a natural-language query into `q` and `near`

If the input you're working with is a single fused string — the kind an AI assistant or chat interface might hand you, like "Loyola University Chicago, Chicago, IL, USA" — you'll need to decompose it yourself before calling the API. The rule of thumb: put the specific entity (the POI, brand, or category) in q, and put the administrative tail (the part that only disambiguates where — city, state, country) in near.

Original string	`q`	`near`
`Black Hills National Forest, SD, USA`	`Black Hills National Forest`	`SD, USA`
`Mount Hood, Oregon, USA`	`Mount Hood`	`Oregon, USA`
`coffee in Portland Oregon`	`coffee`	`Portland Oregon`

The same decomposition applies on /suggest (with a partial query in q as the user types). On /category there's no q to decompose at all — the category lives in the path, and near carries the location intent on its own.

`near` vs. `proximity` vs. `bbox`

Search Box already gave you several ways to make a search location-aware. Here's how near fits alongside them.

`proximity` — bias, don't restrict

proximity doesn't filter anything out. It biases ranking so that results closer to a given point are favored, while still allowing results further away to appear. You supply it separately from your query, either as:

ip (use the requester's IP-based location), or
explicit longitude,latitude coordinates

The key distinction: proximity needs you to already have coordinates. It says "rank things near this point," where this point is something your app already knows (user's GPS location, map center, etc.).

`bbox` — a hard rectangular filter

bbox is a strict inclusion filter. Anything outside the box (min_lon,min_lat,max_lon,max_lat) is excluded outright — it's not a ranking signal, it's a wall. Useful when you know a user is restricted to, say, a specific metro area or map viewport and you never want results from outside it.

`near` — resolves to proximity or bbox, depending on the anchor

near accepts a place name or coordinates and resolves them internally into either a proximity bias or a bbox filter, depending on how coarse the anchor is: countries and regions/states constrain by bbox, while places, neighborhoods, addresses, and POIs bias by proximity. Either way, near is saving you the manual geocoding lookup you'd otherwise need before calling proximity or bbox directly — and if you pass both near and proximity together, near wins, with the old proximity value shifted to origin.

A sample request and response

Here's a real request/response pair, tested directly against the live API:

https://api.mapbox.com/search/searchbox/v1/forward?q=Harold%20Chicken%20Shack&near=Chicago&access_token=YOUR_MAPBOX_ACCESS_TOKEN

The (trimmed) response came back as a standard GeoJSON FeatureCollection:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "coordinates": [-87.84130128, 41.86461828], "type": "Point" },
      "properties": {
        "name": "Harold's Chicken Shack",
        "mapbox_id": "dXJuOm1ieHBvaToxMjI1MjBkMi02MzIyLTQzYjItYmUwMi00MzJhNjBiYzM3ZmU",
        "feature_type": "poi",
        "full_address": "713 Roosevelt Rd, Maywood, Illinois 60153, United States",
        "place_formatted": "Maywood, Illinois 60153, United States",
        "poi_category": ["american restaurant", "food and drink"],
        "metadata": {
          "phone": "+17083566048"
        },
        "distance": 2688893
      }
    },
    {
      "type": "Feature",
      "geometry": { "coordinates": [-87.56676837, 41.76573045], "type": "Point" },
      "properties": {
        "name": "Harold's Chicken Shack",
        "full_address": "7114 S Yates Blvd, Chicago, Illinois 60649, United States",
        "place_formatted": "Chicago, Illinois 60649, United States",
        "distance": 2709632
      }
    },
    {
      "type": "Feature",
      "geometry": { "coordinates": [-87.62617297, 41.87392112], "type": "Point" },
      "properties": {
        "name": "Harolds Chicken Shack",
        "full_address": "612 S Wabash Ave, Chicago, Illinois 60605, United States",
        "place_formatted": "Chicago, Illinois 60605, United States",
        "brand": ["Chicken Shack"],
        "brand_id": ["chicken_shack"],
        "distance": 2706643
      }
    }
  ],
  "attribution": "© 2026 Mapbox and its suppliers. All rights reserved."
}

(For reference: distance is reported in meters — 2,688,893 m ≈ 1,671 mi, 2,709,632 m ≈ 1,684 mi, and 2,706,643 m ≈ 1,682 mi.)

All three full results came back within the Chicago metro area. near=Chicago narrowed the search exactly as you'd want it to, with no out-of-area results.

Even without an outlier to compare against, the distance field is still worth flagging: despite all five results being genuinely local to Chicago, distance came back around 2.69–2.71 million meters (roughly 1,671–1,684 miles) for every result. That's consistent with distance being based on proximity/IP-derived location rather than on near — in this case, the default reference point is apparently nowhere near Chicago either. Don't read distance as a signal for how well near narrowed things — check place_formatted/context instead.

Worth calling out too: metadata here is richer than the base parameter reference currently documents. In practice it can include phone, website, and a full open_hours.periods array broken down by day of week — more than the generic "additional metadata" description in the docs suggests. From here, you'd grab mapbox_id and pass it straight to the Places API's Details endpoint for the even fuller enriched record.

Quick comparison

Parameter	What it does	Input format	Filters or just biases?	Best for
`proximity`	Ranks closer results higher	`ip` or `longitude,latitude`	Biases only	Map-based apps that already know user location
`bbox`	Restricts results to an area	`minLon,minLat,maxLon,maxLat`	Hard filter	Viewport-limited or region-locked search
`near`	Resolves a place name or coordinates, then applies them as `proximity` (specific anchors) or `bbox` (coarse anchors)	`string` (place name) or coordinates, paired with `q`	Both — biases for specific anchors, filters for coarse ones	Conversational or natural-language search where you don't want to run a separate geocoding call

When to reach for which

Building a classic search box on a map where you already have coordinates ready for proximity or bbox? Those parameters take coordinates directly. near also accepts coordinates and resolves them the same way, so either path works if that's what you have on hand.
Need a hard boundary, like restricting to a delivery zone or map viewport? Use bbox directly for full control, though a coarse near value (like a country or state) can behave similarly.
Have a search term and a place name — from a chat interface, voice input, or freeform text — and don't want to run a separate geocoding call yourself? That's what near is built for.

For point-like anchors, near produces the same ranking behavior as proximity directly — it's a convenience layer, not a separate ranking engine. For coarse anchors, it can behave like bbox instead. Either way, near isn't computing something proximity/bbox couldn't already do on their own — it's resolving the anchor and choosing the right mechanism for you.

What to expect at the edges

A few error and fallback behaviors worth knowing before you ship this:

Situation	Response
`near` omitted or empty	Falls back to a normal `q` search with no anchor — still valid
`near` set to invalid coordinates	`400 Bad Request`
`near` text isn't geocodable	Graceful fallback — anchor is left unchanged, `q` still runs
Geocoder temporarily unavailable	`500 Internal Server Error`

It's also worth setting expectations on result quality: in internal testing across categories like national forests, universities, airports, and malls, most near-anchored queries resolved to the correct region with the intended entity ranked at or near the top — misses were the exception rather than the rule. The residual misses tend to be ranking order (the right result shows up a few slots down) or narrow indexing gaps — not incorrect anchoring.

Wrapping up

near gives you a single parameter that resolves a place name or coordinates into either a proximity bias or a bbox filter, depending on how specific the anchor is — sparing you a separate geocoding call when all you have is a name or a rough location. It's available on /forward, /suggest, and /category, so this pattern isn't limited to a single query style. bbox and proximity remain the direct, explicit tools for when you already know exactly which behavior you want.

Ready to try it? near is available today in the Search Box API — check the live API reference for the latest parameter details, or test it directly against the /forward, /suggest, and /category endpoints with your own queries. You can also try it in the Search Box Playground.

Putting a Live Map Inside Your AI Agent's Chat: MCP Apps and render_map_tool

Matthew Podwysocki — Thu, 06 Aug 2026 13:47:27 +0000

If you have used an MCP server before, you know the pattern: the AI agent calls a tool, the tool returns some JSON, and the model reads that JSON back to you in a sentence. That works fine for a list of restaurant names. It falls apart the moment the data is inherently spatial. A route is not really a sentence. Neither is a set of delivery zones or a cluster of nearby coffee shops. You want to see it on a map.

That is the gap MCP Apps closes, and it is what we built render_map_tool around in the Mapbox MCP Server. This post walks through what MCP Apps actually is, why we ended up with one visualization tool instead of one per data type, and how the tool works whether you are chaining it off another Mapbox tool or feeding it your own GeoJSON from a completely unrelated system.

Want to try this yourself before reading further? Follow the hosted MCP server user guide to connect your own client to the production endpoint.

Try it now

The Mapbox MCP server is hosted and ready to use, no local install required. The production endpoint is:

https://mcp.mapbox.com/mcp

For Claude Code, add it before starting a session:

claude mcp add --transport http mapbox-mcp-production https://mcp.mapbox.com/mcp

Every other major client (Claude Desktop, VS Code, Cursor, and more) has its own setup steps, all covered in the hosted MCP server user guide.

A quick primer: MCP and MCP Apps

The Model Context Protocol is the open standard that lets an AI client (Claude Desktop, Claude Code, VS Code with Copilot, and others) talk to external tools and data sources in a consistent way. An MCP server exposes tools, the client's model decides when to call them, and the results come back as text or structured JSON that the model reasons over.

That is enough for most tools, but it has an obvious ceiling: everything ends up flattened into text for the model to summarize. MCP Apps is an extension to that protocol for exactly the cases where flattening loses too much. Instead of returning only text, a tool can also point at a small, self-contained HTML application that the client renders directly inside the conversation, in a sandboxed iframe. The tool still returns normal MCP output for the model to reason about. The HTML panel is an additional, richer surface for the human on the other end.

For a Mapbox MCP server, that is the natural place to put an actual map.

Why one tool, not one map per tool

Our first instinct was the obvious one: give directions_tool its own map panel, give isochrone_tool its own map panel, and so on. We built that, then threw it away, for two reasons that only became clear once we had multiple tools in play.

Chain position matters more than you would expect. A lot of real requests are two steps: get directions, then show them. That means two tool calls in sequence, and several MCP App hosts, Claude Desktop among them, only fully render the interactive panel for the last tool call in a chain. If the map panel belongs to directions_tool and something else runs after it, the panel either does not render or gets superseded. Funneling every visualization through one tool that is always the final step in the chain sidesteps the problem entirely, rather than working around it per tool.

Geometry is expensive to pass through the model. A route polyline or a set of isochrone contours can be tens of thousands of coordinate pairs. Making the model carry that as a tool-call argument on every hop is slow and burns tokens for no benefit, since the model never actually needs to reason about individual coordinates. We wanted a way to hand geometry from one tool to another without the model ever having to see it.

The result is render_map_tool: a single tool that is the only one in the server declaring an MCP Apps resource, and everything else that produces geospatial output hands its result to it.

Chaining: directions in, a live map out

Here is what that looks like end to end. When you ask an agent for directions, directions_tool returns the usual structured data (distance, duration, turn-by-turn instructions), plus one extra field:

{
  "structuredContent": {
    "routes": [ /* ... */ ],
    "mapboxRender": { "ref": "mapbox://selffetch/directions?data=..." }
  }
}

That ref is a short, opaque reference string, not the route geometry itself. The model never sees a single coordinate. It just passes the ref straight through to render_map_tool:

{ "payload_refs": ["mapbox://selffetch/directions?data=..."] }

You can pass more than one ref in the same call, which is how you merge results from multiple tools onto a single map, for example an isochrone alongside a route:

{
  "payload_refs": [
    "mapbox://selffetch/isochrone?data=...",
    "mapbox://selffetch/directions?data=..."
  ]
}

Driving from the Golden Gate Bridge to Union Square: about 8.3 miles, ~24 minutes via US-101 North/South, through a tunnel and a toll road, with light-to-moderate traffic along the way.

Under the hood, that mapbox://selffetch/... ref is not a pointer into a server-side cache. It base64-encodes the original tool call's parameters directly. When the map panel loads in the client, it decodes the ref and fetches the route geometry itself, directly from the Mapbox Directions API, using the same public token already used to load map tiles. This turned out to matter in a way we did not fully appreciate until we hit it in practice.

The map has to survive things the tool call does not. A conversation can sit idle for an hour, the MCP server process can restart, or a client can reopen an old chat and re-render a map card that was created in a previous session. In every one of those cases, anything that depended on in-memory server state from the original request is gone. Early on, our refs pointed at exactly that kind of ephemeral store, and a restart quietly broke every map card that hadn't been viewed yet. Making the ref self-describing, and having the client fetch geometry itself rather than trust a stashed server-side result, fixes that categorically: there is no server memory to lose, so there is nothing to survive. It also means the map always reflects live data. If you ask for directions and check back on that same map card twenty minutes later, current traffic conditions are what gets drawn, not a snapshot from when the tool first ran.

Standalone: your own data, no other Mapbox tool required

Chaining is what an LLM does automatically once it has called a Mapbox tool. But a lot of real usage has nothing to do with our tools at all. If you are integrating the Mapbox MCP server into your own agent and you already have geospatial data, your own delivery zones, a set of store locations from your own database, a GPS trace from a device you operate, there is no reason to route it through our APIs first just to get it on a map.

render_map_tool accepts that data directly:

{
  "summary": "Downtown delivery zone",
  "layers": [
    {
      "id": "delivery-zone",
      "type": "fill",
      "data": {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [-122.4194, 37.7749],
              [-122.4094, 37.7749],
              [-122.4094, 37.7849],
              [-122.4194, 37.7849],
              [-122.4194, 37.7749]
            ]
          ]
        },
        "properties": {}
      },
      "paint": {
        "fill-color": "#3b82f6",
        "fill-opacity": 0.25,
        "fill-outline-color": "#1d4ed8"
      }
    }
  ],
  "markers": [
    {
      "coordinates": [-122.4144, 37.7799],
      "style": "pin",
      "color": "#ef4444",
      "popup": "Warehouse"
    }
  ],
  "legend": [{ "label": "Delivery zone", "color": "#3b82f6", "opacity": 0.25 }]
}

Rendered the downtown delivery zone map — the blue fill shows the zone with the warehouse pin at its center.

No payload_refs, no dependency on directions_tool or any other tool in the server. This is the entire request, and it is not a lesser or fallback code path either. It is the same rendering pipeline every other tool in the server uses internally, just entered directly.

A few things worth calling out for anyone integrating this from outside our tool set:

layers and markers are a thin pass-through to the Mapbox GL JS style spec, not a custom DSL. The paint and layout objects go straight to addLayer, so anything expressible in GL JS style is expressible in the payload. If you already know Mapbox GL JS, there is nothing new to learn here.
You do not need a Mapbox access token to build the payload. Token handling for the actual map tiles happens entirely inside the client's rendering panel, using the server's own public-token resolution. Your layers/markers are plain GeoJSON and CSS-style values with nothing sensitive embedded in them.
Multiple layers and markers in one call are merged onto the same map, and the camera auto-fits to everything drawn unless you pass an explicit camera.
Each call is a fresh render. The tool does not accumulate state across calls, so if you want several things on one map, put them in the same call's layers/markers/payload_refs rather than calling the tool repeatedly and expecting it to build up a picture.

An LLM with access to the tool can also compose this JSON itself from a plain description, so a prompt like "show a fill polygon over these coordinates, with a red pin labeled Warehouse" works without you hand-building the payload at all. But the direct, tool-level integration is what matters if you are wiring this into an agent programmatically rather than relying on a model to fill it in.

Where this fits if you cannot render MCP Apps at all

Not every MCP client supports MCP Apps yet. In a client without support, render_map_tool still returns its resolved payload as ordinary tool output. You lose the live interactive panel, but the call does not fail, and there is nothing to catch or work around on your end. If you specifically need a guaranteed visual regardless of client capability, the server also ships static_map_image_tool, which returns a base64-encoded PNG that renders anywhere.

The short version

MCP Apps gives tools a way to hand a human a real, interactive surface instead of a wall of text. For anything spatial, that surface is a map. We built render_map_tool as the one place all of that goes through in the Mapbox MCP server, whether the data came from chaining one of our own tools or from a GeoJSON payload you built entirely on your own. The chaining path keeps geometry out of the model's hands and off the wire until it is actually needed, and the standalone path means you never have to route your own data through us just to visualize it.

If you want to see the whole payload schema, the compatible client list, or the reasoning behind specific design choices, the full guide is in the repo: docs/render-map-tool.md. The server itself is open source at github.com/mapbox/mcp-server.

Ready to connect your own client? Follow the hosted MCP server user guide to get started with the production endpoint.

Build with Location AI

Whether you're building AI agents, AI-native applications, or adding location intelligence to an existing product, check out the Mapbox Location AI getting started guides and try the companion benchmarks with your own data. If you'd like to discuss your use case, explore architectural approaches, or build together, contact the Mapbox team.

Prompting for interactive web maps in 2026

Chris Whong — Thu, 30 Jul 2026 20:01:17 +0000

With the rise of AI coding tools, our approach to helping developers get started with Mapbox GL JS has had to adapt. These days you're probably building with Claude Code, Codex, or Gemini — and when it comes time to add a map to your project, being specific about the tools and technology you name in your prompt makes a bigger difference than you might expect.

In this post, I'll start with a sample dataset and show you the real-world output of a few different prompts to Claude Code. The first prompt will be generic. The second will call for Mapbox products by name. The third will push further into custom UI. You'll see the difference immediately, and understand why all web maps are not created equal.

But first, GeoJSON data!

For a sample dataset, I created a GeoJSON FeatureCollection of three point features: landmark buildings in Manhattan, New York City. I've included properties like name, description, and imageUrl — the kind of thing we'd want to display to an interested map user. You can use geojson.io to craft your own GeoJSON data when building spatial apps.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-73.9857, 40.7484]
      },
      "properties": {
        "name": "Empire State Building",
        "description": "An iconic 102-story Art Deco skyscraper completed in 1931. Once the tallest building in the world, it remains one of the most recognizable landmarks in New York City.",
        "yearBuilt": 1931,
        "imageUrl": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/10/Empire_State_Building_%28aerial_view%29.jpg/500px-Empire_State_Building_%28aerial_view%29.jpg"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-73.9755, 40.7516]
      },
      "properties": {
        "name": "Chrysler Building",
        "description": "A stunning Art Deco masterpiece completed in 1930, famous for its terraced crown of radiating sunburst arches and gleaming stainless steel cladding.",
        "yearBuilt": 1930,
        "imageUrl": "https://upload.wikimedia.org/wikipedia/commons/thumb/7/76/Chrysler_Building_by_David_Shankbone_Retouched.jpg/500px-Chrysler_Building_by_David_Shankbone_Retouched.jpg"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-73.9772, 40.7527]
      },
      "properties": {
        "name": "Grand Central Terminal",
        "description": "A world-famous Beaux-Arts railroad terminal opened in 1913. Its Main Concourse features a celestial ceiling mural and massive arched windows.",
        "yearBuilt": 1913,
        "imageUrl": "https://upload.wikimedia.org/wikipedia/commons/thumb/7/71/Image-Grand_central_Station_Outside_Night_2.jpg/500px-Image-Grand_central_Station_Outside_Night_2.jpg"
      }
    }
  ]
}

The generic web map prompt

For demonstration purposes, I'm using simple, single-file web pages with JS in a <script> tag.

If you write a prompt like this:

In index.html, make an interactive map with
markers for each Feature in `landmarks.geojson`

You might get a map like this:

Without being told what to use, the AI coding tool reached for Leaflet and a free raster tileset published by OpenStreetMap. It did what you asked, and even went a step further by adding popups that appear on click. But the resulting map feels clunky, dated, and not like something you'd actually want to ship.

Leaflet is a tried-and-true open source mapping library, but it comes from an era — over a decade ago — before vector-based maps came on the scene. It works by arranging PNG image tiles in a div, with more PNGs or SVGs layered on top for markers and overlays. The basemap you see here is actually called "OpenStreetMap's Standard Tile Layer," and it's intended as a reference basemap for people making edits to OpenStreetMap itself. Used as a basemap in front of real users, it's busy and distracting. It's not a bad tileset — it's just designed for a very different purpose.

Mapbox GL JS: ask for it by name!

Now let's request the exact same map, but specify Mapbox products explicitly:

In index.html, add an interactive map with
markers for each feature in landmarks.geojson
using the latest version of Mapbox GL JS and
the Mapbox Standard Style.

Once the code is generated, your AI tool will remind you to add your access token. Mapbox GL JS includes a generous free tier (50,000 map loads per month), but all usage needs to be tied to an account, so one small edit is required before the map will actually load:

Created index.html using Mapbox GL JS v3.27.0 with
the Standard style. You'll need to replace
YOUR_MAPBOX_ACCESS_TOKEN on line 30 with your
Mapbox access token for it to work.

You'll find the placeholder right before the call that instantiates the map. Swap in a token from your Mapbox account page and you're ready to go:

mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/standard',
  center: [-73.9800, 40.7505],
  zoom: 14
});

You'll immediately see — and feel — the difference. Scroll a bit and you'll experience smooth, incremental zooming. Basemap features fade in and out gradually, surfacing the most important information for whatever part of the planet you're looking at. Hold control and drag up and down, or left and right, and you can pitch and rotate the map, controlling the camera like you would in a video game.

The two key things you asked for were Mapbox GL JS, our best-in-class JavaScript mapping library, and the Mapbox Standard Style, our versatile, configurable 2D/3D basemap. The Standard Style is continuously updated with better data for the whole world, and our professional cartographers are constantly refining its design and usability.

The basemap is worlds apart from where we started, but the markers and popups themselves are still fairly close to defaults. So let's go a step further with a prompt aimed squarely at the interaction design.

Adding UI/UX polish

A classic marker-and-popup map may be all you need, but it can still feel generic. One more prompt gets you custom basemap configuration, camera moves, non-map UI elements, and dynamic markers, all working together:

Hide basemap Point of interest labels.

Use a circle layer instead of markers.

Add a symbol layer using label-bg.png as a
stretchable image to display a label above
each circle.

When clicked, animate the circle to a larger
radius, gray out or subdue the other features,
zoom and pitch the map to show the selected
feature, and animate an info panel in from the
bottom (image on the left, info on the right).
When the panel is closed, restore the original
camera view.

There's a lot packed into that prompt, but take a look at the result first, and then I'll walk through each piece:

First we remove point of interest labels, one of many configurable properties of the Mapbox Standard Style. You can also modify individual colors of major features like water, land, or streets, hide 3d models, and apply new color themes. Explore all of the options in the Mapbox Standard Style Playground.

Instead of generic Mapbox GL JS markers, each point is now represented by a circle. More importantly, those circles live in a circle layer — as opposed to markers, which are HTML elements positioned above the map — which makes them far more performant, since they're rendered directly by the WebGL engine that powers the map. This approach scales up to many thousands of features, and works with both GeoJSON and vector tile data sources.

We also added a label to each feature, which is a nice touch that lets users know what the circle represents without exposing all of its underlying data up front. The label uses a symbol layer with a stretchable image as its background. Like the circles, it's WebGL-rendered and will scale with whatever data you bring in.

Here's label-bg.png, the source image used for the label background. Any image can be stretched this way — the stretchable regions are defined in code, so the label background expands cleanly no matter how long the text inside it is:

map.addImage('label-bg', labelImg, {
  content: [8, 6, 28, 18],
  stretchX: [[8, 28]],
  stretchY: [[6, 18]]
});

The fun part happens when a circle is clicked:

Save the original camera view (center, zoom, pitch, bearing).
Update the paint properties of the circle and label layers, enlarging the active feature and subduing the others.
Populate the UI panel with data from the clicked feature.
"Ease" the map into a nicely pitched view focused on the selected feature, showing 3D buildings with a smooth animation.

If you want to go deeper, here's the code that fires on click — all of it happening inside one concise openPanel() function:

function openPanel(props, coords) {
  // Save original view on first activation
  if (!activeFeatureName) {
    originalView = {
      center: map.getCenter(),
      zoom: map.getZoom(),
      pitch: map.getPitch(),
      bearing: map.getBearing()
    };
  }

  activeFeatureName = props.name;

  // Enlarge active circle, subdue inactive features
  map.setPaintProperty('landmarks-circles', 'circle-radius', [
    'case',
    ['==', ['get', 'name'], activeFeatureName], ACTIVE_RADIUS,
    DEFAULT_RADIUS
  ]);
  map.setPaintProperty('landmarks-circles', 'circle-color', [
    'case',
    ['==', ['get', 'name'], activeFeatureName], '#3b82f6',
    '#b0b8c4'
  ]);
  map.setPaintProperty('landmarks-circles', 'circle-stroke-color', [
    'case',
    ['==', ['get', 'name'], activeFeatureName], '#ffffff',
    '#dde1e7'
  ]);
  map.setPaintProperty('landmarks-circles', 'circle-opacity', [
    'case',
    ['==', ['get', 'name'], activeFeatureName], 1,
    0.5
  ]);
  map.setPaintProperty('landmarks-circles', 'circle-stroke-opacity', [
    'case',
    ['==', ['get', 'name'], activeFeatureName], 1,
    0.4
  ]);
  map.setPaintProperty('landmarks-labels', 'text-opacity', [
    'case',
    ['==', ['get', 'name'], activeFeatureName], 1,
    0.3
  ]);
  map.setPaintProperty('landmarks-labels', 'icon-opacity', [
    'case',
    ['==', ['get', 'name'], activeFeatureName], 1,
    0.3
  ]);

  // Update panel content
  panelImage.src = props.imageUrl || '';
  panelImage.style.display = props.imageUrl ? 'block' : 'none';
  panelName.textContent = props.name;
  panelMeta.textContent = props.yearBuilt ? `Built ${props.yearBuilt}` : '';
  panelDesc.textContent = props.description;
  panel.classList.add('open');

  // Zoom and pitch to feature
  map.easeTo({ center: coords, zoom: 16, pitch: 50, duration: 800 });
}

With this prompt, we've gone from a fairly simple marker map to a genuinely compelling custom interaction. The underlying data hasn't changed at all — only the experience built on top of it.

Why naming your tools matters

AI coding assistants are only as specific as the prompts they're given. When you leave the choice of mapping library and basemap up to the model, it defaults to whatever shows up most often in its training data — which, for web maps, tends to be older, simpler, and less visually polished tooling. That's a reasonable default for a quick prototype, but it's rarely what you want for a production app.

The fix is straightforward: treat your AI coding tool the way you'd treat a new contractor on your team. Tell it exactly which library, which version, and which style or theme you want, the same way you would in a technical spec or a code review comment. A few extra words in your prompt — "using the latest version of Mapbox GL JS and the Mapbox Standard Style" — is the difference between a map that feels like 2012 and one that feels like it belongs in your product today.

Try it yourself

If you want to experiment with this on your own data:

Build a small GeoJSON file with geojson.io.
Ask your AI coding tool for a map with no library specified, and see what you get.
Re-run the prompt, this time naming Mapbox GL JS and the Mapbox Standard Style explicitly.
Push further with a UI/UX prompt of your own — try custom layers, click interactions, or animated camera moves.
Compare the results — check out the Mapbox GL JS examples page for more patterns like clustering, custom markers, and popups you can ask your AI tool to replicate. Drop a link straight into your prompt, or, better yet, connect the Mapbox docs MCP Server so your coding tool can look up Mapbox APIs on its own.

Once you see the difference side by side, "ask for it by name" becomes second nature — and it's a habit worth carrying into every prompt you write for a mapping feature, not just your first one.

Did You Know? Mapbox Geocoding API Lets You Filter by Feature Type

Erwin Soekianto — Tue, 14 Jul 2026 17:04:57 +0000

Episode 1: Geocoding smarter, not harder

This one's about the types parameter on the Mapbox Geocoding API specifically. (The Search Box API has its own types parameter too, but that's a separate product — this post is just about Geocoding.)

Say you're building a signup form and just need the city someone typed. Or you're tagging support tickets by county for routing. Or you just want the state for a sales-tax lookup. You don't need a rooftop-accurate street address — but a lot of geocoders hand you the whole thing anyway, whether you asked for it or not.

Turns out you can filter out the feature types that you don't need — Mapbox lets you ask for exactly the level you need.

TL;DR: the types param filters which feature types come back in the results. Set types=district and you get back only district-type features. (place = city, district ≈ county in the US, region = state, postcode = ZIP).

Filtering with `types`

Here's a reverse geocode of a point in Manhattan with no types filter — by default this can return separate address, place, region, and country features, all at once:

curl "https://api.mapbox.com/search/geocode/v6/reverse?
longitude=-74.05941186207377&
latitude=40.77969220566604&
access_token=TOKEN"

Only need the zipcode for that same point? Filter it down:

curl "https://api.mapbox.com/search/geocode/v6/reverse?
longitude=-74.05941186207377&
latitude=40.77969220566604&
types=postcode&
access_token=TOKEN"

Now the features array only contains postcode-type results — something like this:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "dXJuOm1ieHBsYzpBU2VPN0E",
      "geometry": {
        "type": "Point",
        "coordinates": [-74.056834, 40.789203]
      },
      "properties": {
        "mapbox_id": "dXJuOm1ieHBsYzpBU2VPN0E",
        "feature_type": "postcode",
        "full_address": "Secaucus, New Jersey 07094, United States",
        "name": "07094",
        "name_preferred": "07094",
        "coordinates": {
          "longitude": -74.056834,
          "latitude": 40.789203
        },
        "place_formatted": "Secaucus, New Jersey, United States",
        "bbox": [-74.094356, 40.75046, -74.033648, 40.807552],
        "context": {
          "place": {
            "mapbox_id": "dXJuOm1ieHBsYzpFYmVvN0E",
            "name": "Secaucus",
            "wikidata_id": "Q1013249"
          },
          "district": {
            "mapbox_id": "dXJuOm1ieHBsYzpwQWJz",
            "name": "Hudson County",
            "wikidata_id": "Q490505"
          },
          "region": {
            "mapbox_id": "dXJuOm1ieHBsYzpBbVRz",
            "name": "New Jersey",
            "wikidata_id": "Q1408",
            "region_code": "NJ",
            "region_code_full": "US-NJ"
          },
          "country": {
            "mapbox_id": "dXJuOm1ieHBsYzpJdXc",
            "name": "United States",
            "wikidata_id": "Q30",
            "country_code": "US",
            "country_code_alpha_3": "USA"
          },
          "postcode": {
            "mapbox_id": "dXJuOm1ieHBsYzpBU2VPN0E",
            "name": "07094"
          }
        }
      }
    }
  ],
  "attribution": "NOTICE: © 2026 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service (https://www.mapbox.com/about/maps/). This response and the information it contains may not be retained."
}

Same idea for county — Mapbox's district type is defined as "smaller than a region, larger than a place," and for US addresses, that maps to a county:

curl "https://api.mapbox.com/search/geocode/v6/reverse?
longitude=-74.05941186207377&
latitude=40.77969220566604&
types=district&
access_token=TOKEN"

Same shape, just at the district level:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "dXJuOm1ieHBsYzpwQWJz",
      "geometry": {
        "type": "Point",
        "coordinates": [-74.04667, 40.72069]
      },
      "properties": {
        "mapbox_id": "dXJuOm1ieHBsYzpwQWJz",
        "feature_type": "district",
        "full_address": "Hudson County, New Jersey, United States",
        "name": "Hudson County",
        "name_preferred": "Hudson County",
        "coordinates": {
          "longitude": -74.04667,
          "latitude": 40.72069
        },
        "place_formatted": "New Jersey, United States",
        "bbox": [-74.166087, 40.641695, -73.98538, 40.823543],
        "context": {
          "region": {
            "mapbox_id": "dXJuOm1ieHBsYzpBbVRz",
            "name": "New Jersey",
            "wikidata_id": "Q1408",
            "region_code": "NJ",
            "region_code_full": "US-NJ"
          },
          "country": {
            "mapbox_id": "dXJuOm1ieHBsYzpJdXc",
            "name": "United States",
            "wikidata_id": "Q30",
            "country_code": "US",
            "country_code_alpha_3": "USA"
          },
          "district": {
            "mapbox_id": "dXJuOm1ieHBsYzpwQWJz",
            "name": "Hudson County",
            "wikidata_id": "Q490505"
          }
        }
      }
    }
  ],
  "attribution": "NOTICE: © 2026 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service (https://www.mapbox.com/about/maps/). This response and the information it contains may not be retained."
}

It works the same way on forward geocoding, and there it also changes which matches come back, not just filters a single result down. The docs' own example: searching q=georgia with no filter can match both the country Georgia and the US state Georgia. Add types=country and only the country comes back — you're excluding a whole category of match, not trimming one result's payload.

You can also stack multiple types in one call, comma-separated — e.g. types=address,street,place to get back any of those three, in one request.

Why it matters

If you're doing this at volume — autocomplete-as-you-type, bulk address cleanup, routing tickets by county — asking for exactly the feature type(s) you need means fewer irrelevant features to filter out client-side, and no risk of grabbing the wrong one out of a mixed results list.

Full list of feature types and how the types param works: Mapbox Geocoding API docs.

Got a favorite obscure API parameter that saved you a bunch of overhead? Drop it in the comments — might be the next episode.

Quick Tip: Dynamic Speed Units in Mapbox Navigation SDK for Android

Erwin Soekianto — Wed, 17 Jun 2026 00:03:21 +0000

Hi everyone! I’m Erwin, the newest Developer Evangelist at Mapbox. As I explore our SDKs, I’m focused on making our samples more flexible and easier to implement.

Today, I’m sharing how to add a real-time MPH/KMH toggle to our Render speed limit for a route sample. This implementation is based on the Localization & internationalization guide in our docs.

The Implementation

In the Mapbox Navigation SDK for Android, the speed units are determined by the unitType passed via DistanceFormatterOptions. To make it dynamic, we cache the last location result to refresh the UI instantly.

You can view the full source code changes for this enhancement in this commit on GitHub.

1. Updating the Layout

First, we add a simple button to our layout to trigger the unit switch.

<androidx.appcompat.widget.AppCompatButton
    android:id="@+id/toggleUnitButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Toggle Unit"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintTop_toTopOf="parent" />

2. The Toggle Logic

Rebuild your options and trigger a refresh using the cached LocationMatcherResult:

private var lastLocationMatcherResult: LocationMatcherResult? = null

binding.toggleUnitButton.setOnClickListener {
    val newUnit = if (distanceFormatterOptions.unitType == UnitType.METRIC) 
                    UnitType.IMPERIAL else UnitType.METRIC

    distanceFormatterOptions = distanceFormatterOptions.toBuilder()
        .unitType(newUnit)
        .build()

    // Immediate UI refresh
    lastLocationMatcherResult?.let { updateSpeedLimit(it) }
}

3. Updating the View

Pass the updated options into the MapboxSpeedInfoApi to get the correctly formatted speed "sign" data:

private fun updateSpeedLimit(locationMatcherResult: LocationMatcherResult) {
    val info = speedInfoApi.updatePostedAndCurrentSpeed(
        locationMatcherResult,
        distanceFormatterOptions
    )
    if (info != null) {
        binding.speedLimitView.isVisible = true
        binding.speedLimitView.render(info)
    } else {
        binding.speedLimitView.isVisible = false
    }
}

Why it matters

Localization isn't just a "set and forget" feature. Providing a seamless way to switch units enhances the driving experience for users crossing borders or those with specific personal preferences.
For a deeper dive into localization, check out our full documentation here. Expect more tips as I continue my journey with the Mapbox ecosystem!

React + Mapbox GL JS: Custom Markers, Popups, and Bounds-Based Data Fetching

Chris Whong — Wed, 03 Jun 2026 12:44:04 +0000

React + Mapbox GL JS: Custom Markers, Popups, and Bounds-Based Data Fetching

If you've added a Mapbox map in a React app before, you've probably hit a wall pretty quickly: Mapbox GL JS manages its own DOM, and React manages a virtual DOM, and getting the two to play nicely takes some thought. Markers and popups are a great example of this tension — they're imperative APIs in a world where you want declarative components.

This post walks through a pattern I've landed on for wrapping mapboxgl.Marker and mapboxgl.Popup in composable React components, and combining them with bounds-based data fetching to build something like a real estate or earthquake explorer map — where the data on the map updates as you pan and zoom.

Here's what we'll cover:

Wrapping mapboxgl.Marker in a React component that handles its own lifecycle
Using createPortal to render custom marker content in React
Fetching data from an API using the map's current bounding box
Tracking an active marker with React state
Wrapping mapboxgl.Popup in a component

If you want to see the finished product first, the source code is on GitHub.

The Core Challenge: Two DOMs

Before we get into the code, it's worth understanding why this requires a pattern at all. When you use React's normal component tree, React controls the DOM. But mapboxgl.Marker also creates and manages DOM nodes — it places an element on the map at a specific geographic coordinate, handles repositioning as you pan, and removes itself cleanly when you're done with it.

The approach here is to use React to manage the lifecycle of each marker (mount when data arrives, unmount when data goes away), while letting Mapbox handle the positioning. We use React's createPortal to render JSX content into a DOM node that we hand off to Mapbox.

The example discussed below is a map that fetches earthquake data for the current viewport, displaying a custom Marker and Popup for each. As you move the map and the bounds change, new data is fetched and the Markers and Popups are updated accordingly. Try it out:

Setting Up: A Map Component That Fetches Data

Start with a basic Mapbox GL JS map in a React component. The setup here is pretty standard — a useRef for the map instance, a useRef for the container element, and a useEffect to initialize the map on mount and clean it up on unmount.

// src/Map.jsx
import React, { useEffect, useRef, useState, useCallback } from 'react'
import mapboxgl from 'mapbox-gl'
import 'mapbox-gl/dist/mapbox-gl.css'

function Map() {
    // mapRef holds the mapboxgl.Map instance so we can call methods on it
    // without triggering re-renders when it changes
    const mapRef = useRef()

    // mapContainerRef points to the DOM element that Mapbox will render into
    const mapContainerRef = useRef()

    // earthquakeData holds the GeoJSON FeatureCollection returned by the API
    const [earthquakeData, setEarthquakeData] = useState()

    // useCallback prevents this function from being recreated on every render,
    // which matters because we pass it to map.on() event listeners
    const getBboxAndFetch = useCallback(async () => {
        // getBounds() returns the lat/lng bounds of what's currently visible on screen
        const bounds = mapRef.current.getBounds()
        try {
            const data = await fetch(
                // Pass the SW and NE corners of the viewport as query params
                // so the API only returns earthquakes within the current view
                `https://earthquake.usgs.gov/fdsnws/event/1/query?format=geojson` +
                `&starttime=2024-01-01&endtime=2024-01-30` +
                `&minlatitude=${bounds._sw.lat}&maxlatitude=${bounds._ne.lat}` +
                `&minlongitude=${bounds._sw.lng}&maxlongitude=${bounds._ne.lng}`
            ).then(d => d.json())
            setEarthquakeData(data)
        } catch (error) {
            console.error(error)
        }
    }, [])

    useEffect(() => {
        mapRef.current = new mapboxgl.Map({
            accessToken: 'YOUR_MAPBOX_ACCESS_TOKEN',
            container: mapContainerRef.current,
            center: [124, -1.98],  // Start centered on Indonesia, an earthquake-prone region
            minZoom: 5.5,          // Prevent zooming out too far — keeps API responses manageable
            zoom: 5.5
        })

        // Fetch once when the map finishes its initial load
        mapRef.current.on('load', getBboxAndFetch)

        // Fetch again whenever the user pans or zooms to a new area
        mapRef.current.on('moveend', getBboxAndFetch)

        // Clean up the map instance when this component unmounts
        return () => mapRef.current.remove()
    }, [])

    return <div id='map-container' ref={mapContainerRef} />
}

The key piece here is getBboxAndFetch. It reads the map's current bounds using Map.getBounds(), constructs a URL to fetch earthquake data with those bounds as query parameters, and stores the response in state. It fires once on load and again on every moveend — so every time the user pans or zooms, new data comes in for all earthquakes that occurred in whatever part of the world is in view.

I'm wrapping it in useCallback to avoid it being recreated on every render, which would cause issues with the event listener setup.

The Marker Component

Here's where things get interesting. Rather than imperatively adding and removing markers in the Map component, we can delegate that work to a dedicated Marker component that handles its own lifecycle.

The trick is using createPortal to render JSX content into a DOM node that we create ourselves and hand to mapboxgl.Marker as its element.

// src/Marker.jsx
import { useEffect, useRef } from "react"
import mapboxgl from "mapbox-gl"
import { createPortal } from "react-dom"

const Marker = ({ map, feature, isActive, onClick }) => {
    const { geometry, properties } = feature

    // markerRef holds the mapboxgl.Marker instance so we can remove it on unmount
    const markerRef = useRef(null)

    // contentRef is a plain DOM div that we create once — this is the bridge between
    // React's rendering and Mapbox's marker system. We hand it to Mapbox, and
    // React renders into it via createPortal below.
    const contentRef = useRef(document.createElement("div"))

    useEffect(() => {
        // Pass contentRef.current as the element for the marker.
        // Mapbox will position this div on the map at the given coordinates.
        markerRef.current = new mapboxgl.Marker(contentRef.current)
            .setLngLat([geometry.coordinates[0], geometry.coordinates[1]])
            .addTo(map)

        // Remove the marker from the map when this component unmounts.
        // This fires automatically when the parent re-renders with new data
        // and this earthquake feature is no longer in the result set.
        return () => markerRef.current.remove()
    }, [])

    // createPortal renders our JSX into contentRef.current — the same div
    // that Mapbox is positioning on the map. React controls the content,
    // Mapbox controls the placement.
    return createPortal(
        <div
            onClick={() => onClick(feature)}
            style={{
                display: "inline-block",
                padding: "2px 10px",
                borderRadius: "50px",
                // Flip colors when this marker is the active (clicked) one
                backgroundColor: isActive ? "#333" : "#fff",
                boxShadow: "0px 2px 4px rgba(0, 0, 0, 0.5)",
                fontFamily: "Arial, sans-serif",
                fontSize: "14px",
                fontWeight: "bold",
                color: isActive ? "#fff" : "#333",
            }}
        >
            {/* Show the earthquake's magnitude as the marker label */}
            {properties.mag}
        </div>,
        contentRef.current
    )
}

export default Marker

Let's break down what's happening:

contentRef holds a plain DOM div that we create once and never touch directly
We pass that div to new mapboxgl.Marker(contentRef.current) — Mapbox takes ownership of positioning it on the map
createPortal renders our JSX into that same div, so React controls the content while Mapbox controls the placement
The useEffect cleanup removes the marker from the map when the component unmounts

The result is that you can build marker content using normal React patterns — JSX, props, conditional styles, event handlers — and it all "just works" inside Mapbox's marker system.

Rendering Markers from Data

Back in the Map component, rendering markers is now straightforward. Map over the earthquake features, render a Marker for each one, and use feature.id as the React key. That last part is important — when new data comes in after a pan, React will diff the keys and only create new Marker instances for earthquakes that weren't in the previous result set.

// In Map.jsx

// activeFeature holds the full GeoJSON Feature of the currently selected marker,
// or undefined if no marker has been clicked yet
const [activeFeature, setActiveFeature] = useState()

// Called by a Marker when it's clicked — stores the feature so we can
// highlight the active marker and position the popup
const handleMarkerClick = (feature) => {
    setActiveFeature(feature)
}

return (
    <>
        {/* The div that Mapbox renders the map canvas into */}
        <div id='map-container' ref={mapContainerRef} />

        {/* Guard against mapRef.current being undefined on the first render,
            then render one Marker component per earthquake feature */}
        {mapRef.current && earthquakeData?.features?.map((feature) => (
            <Marker
                key={feature.id}        // Stable ID lets React reuse existing markers on re-renders
                map={mapRef.current}    // The map instance, so Marker can call .addTo(map)
                feature={feature}
                isActive={activeFeature?.id === feature.id}  // True only for the clicked marker
                onClick={handleMarkerClick}
            />
        ))}
    </>
)

activeFeature stores the full feature object of the currently clicked marker. Passing isActive={activeFeature?.id === feature.id} to each Marker lets them style themselves differently when selected — in our case, flipping to a dark background and light text.

The Popup Component

Popups follow a similar pattern to markers. One difference is that we only ever need one popup instance — it just moves around based on which marker is active.

// src/Popup.jsx
import { useEffect, useRef } from "react"
import { createPortal } from "react-dom"
import mapboxgl from 'mapbox-gl'

const Popup = ({ map, activeFeature }) => {
    // popupRef holds the single mapboxgl.Popup instance for its whole lifetime
    const popupRef = useRef()

    // contentRef is the same portal trick as in Marker — a plain DOM div
    // that React renders into, which we then pass to the Mapbox popup
    const contentRef = useRef(document.createElement("div"))

    // Runs once on mount: create the popup instance but don't add it to the map yet.
    // We wait until activeFeature is set before positioning and showing it.
    useEffect(() => {
        if (!map) return
        popupRef.current = new mapboxgl.Popup({
            closeOnClick: false,  // Keep the popup open when the user clicks elsewhere on the map
            offset: 20            // Push the popup up slightly so it doesn't overlap the marker
        })
        // Remove the popup from the map when this component unmounts
        return () => popupRef.current.remove()
    }, [])

    // Runs whenever activeFeature changes: reposition the popup and update its content
    useEffect(() => {
        if (!activeFeature) return

        popupRef.current
            .setLngLat(activeFeature.geometry.coordinates)  // Move popup to the clicked marker's location
            .setHTML(contentRef.current.outerHTML)           // Serialize the React-rendered content to an HTML string
            .addTo(map)                                      // Add (or re-add) the popup to the map
    }, [activeFeature])

    // Render the popup content into contentRef via a portal.
    // By the time the second useEffect above reads contentRef.current.outerHTML,
    // React will have already rendered this JSX into the div.
    return createPortal(
        <div>
            <table>
                <tbody>
                    <tr>
                        <td><strong>Time</strong></td>
                        {/* Convert the Unix timestamp (ms) to a human-readable local time */}
                        <td>{new Date(activeFeature?.properties.time).toLocaleString()}</td>
                    </tr>
                    <tr>
                        <td><strong>Magnitude</strong></td>
                        <td>{activeFeature?.properties.mag}</td>
                    </tr>
                    <tr>
                        <td><strong>Place</strong></td>
                        <td>{activeFeature?.properties.place}</td>
                    </tr>
                </tbody>
            </table>
        </div>,
        contentRef.current
    )
}

export default Popup

There are two useEffect hooks here with different jobs:

The first runs once on mount and creates the mapboxgl.Popup instance (but doesn't add it to the map yet)
The second runs whenever activeFeature changes, and repositions the popup + updates its content

One thing to note: setHTML takes the outerHTML of contentRef.current, not a reference to the element itself. This is because Mapbox's popup API works with HTML strings for its content. The createPortal has already rendered our JSX into that DOM node by the time this runs, so outerHTML gives us the rendered output as a string.

Putting It All Together

The final Map component renders the map container, maps over the earthquake data to produce Marker components, and includes a single Popup that tracks the active feature:

// In Map.jsx

return (
    <>
        {/* The map canvas container */}
        <div id='map-container' ref={mapContainerRef} />

        {/* One Marker per earthquake — guarded so we don't render before the map exists */}
        {mapRef.current && earthquakeData?.features?.map((feature) => (
            <Marker
                key={feature.id}
                map={mapRef.current}
                feature={feature}
                isActive={activeFeature?.id === feature.id}
                onClick={handleMarkerClick}
            />
        ))}

        {/* A single Popup instance that repositions itself when activeFeature changes */}
        {mapRef.current && (
            <Popup map={mapRef.current} activeFeature={activeFeature} />
        )}
    </>
)

The mapRef.current && guards are there because the map instance doesn't exist until after the first render — we don't want to pass undefined as the map prop.

Where to Take It From Here

This pattern is intentionally minimal. Some things you'd want to add in a real app:

Loading state: Show a spinner or disable interaction while a fetch is in progress
Error handling: Surface API errors in the UI instead of just logging them
Clustering: Group nearby markers when zoomed out — Mapbox GL JS has good support for this if you switch to a GeoJSON source/layer approach
Your own data: Swap out the USGS API for anything that returns GeoJSON and can be filtered by bounding box. This pattern works well for store locators, property listings, event maps, etc.

The full source code for the earthquake demo is on GitHub if you want to run it locally or use it as a starting point.

Demystifying Mapbox Styles

Chris Whong — Tue, 05 May 2026 17:32:07 +0000

If you've spent any time building digital maps with Mapbox, you've used a style — but you may not have given it much thought. Most tutorials and example code abstract it down to a single URL, and the map just works. That's by design.

But styles are doing a lot more than most developers realize, and understanding how they actually work opens up patterns that are useful whether you're just getting started or have been shipping Mapbox maps for years.

This post pulls back the curtain: what a style really is, how it gets from a server to your screen, and a few tips and tricks for working with styles more intentionally.

What even is a style?

When you load a map in a web or mobile app it is a style that tells the map what to draw and how to draw it. The map rendering library (Mapbox GL JS, or the Maps SDK for iOS/Android/Flutter) loads and parses the style, then fetches whatever data is needed and renders it to the map canvas using GL technology.

The Mapbox Standard Style is the default style for all renderers, but works in a slightly different way than our Classic Styles, but we'll get to that later. First, let's talk about how styles have worked historically.

In the earlier days of Mapbox maps, most developers would start with one of Mapbox's Classic Styles, a URL that looks like mapbox://styles/mapbox/streets-v12. See all of the Slassic Styles here. These styles were professionally designed by our cartographers, and purpose built for different use cases.

Streets is a great all-purpose style, with a wide variety of colors and details.
Outdoors is designed for hiking and outdoor activities, with terrain shading, contour lines, and vibrant colors.
Light and Dark are designed to be more subdued, ideal for maps where the overlaid data should be the star of the show, and the basemap should recede into the background.

With a mapbox:// URL to a classic style, a center point, and a zoom level, you can summon an amazingly detailed, fluidly scrolling map with five lines of code:

new mapboxgl.Map({
    style: 'mapbox://styles/mapbox/streets-v12',
    center: [-103.64548, 51.14245],
    zoom: 1.78
})

What you may not know is that mapbox://styles/mapbox/streets-v12 is shorthand for a call to the Mapbox Styles API, whose sole purpose in life is (you guessed it) storing and serving up map styles! The actual API call is to https://api.mapbox.com/styles/v1/mapbox/streets-v12, which returns the style as JSON:

{
  "name": "Mapbox Streets",
  "sprite": "mapbox://sprites/mapbox/streets-v12",
  "glyphs": "mapbox://fonts/mapbox/{fontstack}/{range}.pbf",
  "center": [
    -92.25,
    37.75
  ],
  "zoom": 2,
  "fog": {...},
  "projection": {
    "name": "globe"
  },
  "visibility": "public",
  "version": 8,
  "layers": [...],
  "sources": {
    "composite": {
      "url": "mapbox://mapbox.mapbox-streets-v8,mapbox.mapbox-terrain-v2,mapbox.mapbox-bathymetry-v2",
      "type": "vector"
    }
  },  
  "created": "1970-01-01T00:00:00.000Z",
  "modified": "1970-01-01T00:00:00.000Z",
  "owner": "mapbox",
  "id": "streets-v12",
  "draft": false
}

The actual JSON is about 13,000 lines long when pretty-printed, and 99% of it is in the layers array. That's really where the action is, where every detail shown on the map is defined, often using complex expressions to handle zoom-dependent styling, multi-language support, etc. Here's just one, of no particular importance, so you can see what we're working with in the layers array. road-minor handles rendering of minor roads. It's a line layer (other types include fill, circle, symbol, etc) and pulls data from the road source layer.

{
  // Identifies this layer within the style.
  "id": "road-minor",

  // Tells the renderer to draw the features as lines.
  "type": "line",

  // Names the source dataset this layer reads from.
  "source": "composite",

  // Chooses the specific source layer inside the vector tileset.
  "source-layer": "road",

  // Prevents the layer from appearing before zoom level 13.
  "minzoom": 13,

  // Limits which road features are included in this layer.
  "filter": [
    "all",
    ["match", ["get", "class"], ["track"], true, "service", ["step", ["zoom"], false, 14, true], false],
    ["match", ["get", "structure"], ["none", "ford"], true, false],
    ["==", ["geometry-type"], "LineString"]
  ],

  // Controls how line ends and corners are shaped.
  "layout": {
    "line-cap": ["step", ["zoom"], "butt", 14, "round"],
    "line-join": ["step", ["zoom"], "miter", 14, "round"]
  },

  // Defines the visible styling, including width and color.
  "paint": {
    "line-width": ["interpolate", ["exponential", 1.5], ["zoom"], 14, 1, 18, 10, 22, 100],
    "line-color": "hsl(0, 0%, 100%)"
  },

  // Stores internal grouping and categorization metadata.
  "metadata": {
    "mapbox:featureComponent": "road-network",
    "mapbox:group": "Road network, surface"
  }
}

All that just for one layer? Yes, and this is one of the simpler ones!

You'll also notice that in the JSON for this style, there are even more magic mapbox:// URLs for the sprite and glyphs, and the sources. sprite and glyphs are similar shorthand URLs for the styles API endpoints that serve additional resources needed to render the style.

sprite gets back an composite image full of all those little icons you see on the map for restaurants, hotels, parks, attractions, etc.

glyphs gets back font files that are used to render all the labels.

sources includes shorthand URLs for a different API, the Mapbox Vector Tiles API. These vector tilesets contain the actual data shown on the map, served over the network as small chunks of unstyled data representing a quadrangle of the earth's surface. mapbox-streets-v8 does the heavy lifting and contains data for most of what you'll see on any Mapbox style (streets, place names, parks/land use, buildings, etc). The image below contains a simplified rendering of the rich data included in the streets-v8 tileset, including streets, place labels, points of interest, building footprints, etc.

All this complexity gets you to a pretty great starting point, a well-designed "basemap" of the whole planet, at every zoom level from the full globe down to streets and intersections. Many developers never need to edit layers in the basemap, they take it as-is and concern themselves only with styling their own data they add to the map. Others may want complete control, changing colors to match a brand, removing or modifying whole sets of map labels, or changing the width of streets.

The Style Specification

The Mapbox Style Specification is the formal definition of what a style is, and how it should be structured. It lives at docs.mapbox.com/style-spec and defines the required properties, valid values for each property, and the overall structure of the style JSON. If you want to understand how styles work under the hood, or if you want to create your own custom styles from scratch, the style spec is the place to start. It is also a great reference for understanding the different properties and options available when working with styles, and can help you troubleshoot issues when your style isn't working as expected.

Every possible style property is outlined in the style spec:

If you are maintaining complex styles on your own, there are various utilities available to help you validate your style JSON against the specification, and to catch errors before they cause issues in your apps.

Other ways to get a style JSON into your map

The mapbox:// URLs are the most common way to get a style into your map, but they are not the only way.

As mentioned earlier, the style is just JSON, and that JSON can come from anywhere. For example, if I were to strip down the complex style JSON above, and include only a single layer for buildings, the style might look like this:

{
        "version": 8,
        "layers": [
            {
                "id": "building",
                "type": "fill",
                "source": "streets-v8",
                "source-layer": "building",
                "minzoom": 15,
                "filter": [
                    "all",
                    ["!=", ["get", "type"], "building:part"],
                    ["==", ["get", "underground"], "false"]
                ],
                "layout": {},
                "paint": {
                    "fill-color": "#ccc",
                }
            }
        ],
        "sources": {
            "streets-v8": {
                "url": "mapbox://mapbox.mapbox-streets-v8",
                "type": "vector"
            }
        }
    }

We have also removed optional properties: center, zoom, fog, projection, visibility, created, modified, owner, id, and draft. Bear in mind that the above is the bare minimum that the renderer needs to display something from the streets-v8 tileset. So how do we get this style into the map?

Load JSON from your codebase

You can load style JSON from a file in your codebase, or as a JSON string defined in your source code. This codepen shows the minimal style JSON above, implemented as a JSON object in the JavaScript code just before map instantiation:

Web

In a web project, this style could be saved as style.json and imported as a JSON object using a bundler:

import style from '../data/style.json' 

...

const map = new mapboxgl.Map({
  style: style,
  center: [-72, 41],
  zoom: 15.5
})

It can also be defined as an object in the JavaScript:

const style = {
  "version": 8,
  "layers": [ ... ],
  "sources": { ... }
}

...

const map = new mapboxgl.Map({
  style: style,
  center: [-72, 41],
  zoom: 15.5
})

Mobile Applications (iOS, Android, Flutter)

For mobile applications, there's no equivalent to loading the style JSON from an object stored in a variable, so you'll be working with the JSON as a string. You can load the JSON from an asset file in your codebase, or define it as a string directly in your code.

For example, in iOS you could load the JSON from a file in your app bundle:

if let styleURL = Bundle.main.url(forResource: "style", withExtension: "json") {
    let map = MapView(frame: view.bounds, styleURL: styleURL)
    view.addSubview(map)
}

Or in Flutter you could define the string directly in your code:

const String style = '''{
  "version": 8,
  "layers": [ ... ],
  "sources": { ... }         
}''';

final map = MapboxMap(
  styleString: style,
  initialCameraPosition: CameraPosition(
    target: LatLng(41, -72),
    zoom: 15.5,
  ),
);

Host a JSON file somewhere (anywhere!)

You can add any URL to the style option in Mapbox GL JS. This means you can host your style JSON on your own server, an S3 bucket, github raw link, or any other web-accessible location. The only requirement is that the style be accessible at the time of map instantiation, and that it be valid style JSON:

const map = new mapboxgl.Map({
  style: 'https://example.com/my-style.json',
  center: [-72, 41],
  zoom: 15.5
})

On mobile, loading a style from a URL works the same way, just make sure the URL is accessible from the device:

let styleURL = URL(string: "https://example.com/my-style.json")!
let map = MapView(frame: view.bounds, styleURL: styleURL)
view.addSubview(map)

When would I ever need to do this?

Loading a style JSON from your codebase can be useful in development, where you want to move quickly and just get something on the screen without worrying about hosting and network requests. It also allows you to keep your style JSON in version control alongside your app's code, which can be helpful for tracking changes and collaborating with other developers.

There are also plenty of use cases where a full-on basemap isn't needed, such as indoor maps, transit maps, event seating charts, or any map where the data is the star of the show and a real-world basemap would just be visual noise. In these cases, you can maintain a simple style JSON with just your custom sources and layers, and load it directly into the map without having to worry about the complexity of a full basemap style.

For a full style with hundreds of layers and thousands of lines of JSON, it's often less practical to maintain it in your codebase, but some teams may prefer this so they can keep styles in the same codebase as their app, be able to explore changes in version control, and have full control over how and when styles are updated and deployed.

However, modern changes to the style spec allow for importing one style into another, which makes maintaining your own top-level style JSON much more manageable. See the Enter the Standard Style (and style "imports") section below.

Implementation patterns for using Mapbox-hosted Classic Styles

1) Load a Mapbox classic style (mapbox://styles/mapbox/streets-v12) and add your data at runtime

This approach treats the initial map load and its style as the basemap and adds additional sources and layers after the map has loaded. This approach lends itself well to using GeoJSON sources and layers when you have small datasets that you want to add to a style.

const map = new mapboxgl.Map({
  style: 'mapbox://styles/mapbox/streets-v12',
  center: [-72, 41],
  zoom: 15.5
})

map.on('load', () => {
  map.addSource('my-data', {
    type: 'geojson',
    data: 'https://example.com/my-data.geojson'
  })

  map.addLayer({
    id: 'my-data-layer',
    type: 'circle',
    source: 'my-data',
    paint: {
      'circle-radius': 5,
      'circle-color': '#f00'
    }
  })
})

2) Make a custom style based on (e.g. cloned from) a Mapbox-hosted style

With this approach, you start with a clone of a Mapbox style and add your data in the Mapbox Style Editor. Once your style is published, you can use it in your frontend maps using its mapbox:// URL. Behind the scenes there is still a style JSON with thousands of lines, but you the developer never have to interact with it directly, and can make all changes through the UI of the Style Editor.

This approach is more common for developers who have custom tilesets hosted on Mapbox, either created using Mapbox Tiling Service or via the Data Workbench. Adding a custom tileset as a vector source at runtime is still possible, but it's more straightforward to add the tileset to a custom style and use the Style Editor to get it looking the way you want.

This image from the Style Editor shows the Dark classic style, with full control over each of its 100+ layers. Developers get full control, but manual updates are required if the underlying data changes or new features are released.

This approach is also ideal if you want the same map on multiple platforms, as you can maintain one style in the Style Editor and load it on web, iOS, Android, and/or Flutter with the same mapbox:// URL. No additional code is necessary to add your custom sources and layers, as they are already baked into the custom style.

Note: The Style Editor used to allow for the creation of new styles based on the Classic Styles (Streets, Light, Dark, etc.), but this option has been removed. You can still use this approach by adding any of the styles in the Mapbox Gallery's Community Templates tab. Copying a style from the gallery clones it, and your new style is a carbon copy of the original template. Any changes you make are yours to manage.

const map = new mapboxgl.Map({
  style: 'mapbox://styles/your-username/your-style-id',
  center: [-72, 41],
  zoom: 15.5
})

The "Maintenance Tax" of Classic Styles

The classic style paradigm has been around since the earliest days of GL-based mapping at Mapbox, and it remains a powerful and flexible approach — but that flexibility comes with a cost: you own the style JSON, which means you own the maintenance burden.

When you fork a classic style, you're taking a snapshot frozen in time. Mapbox continuously improves both the renderer and the style spec together — new features like HD Roads or Indoor Maps aren't just style layer changes, they're coordinated updates across the rendering engine, the style specification, and the style JSON simultaneously. Classic style users who want these features have to manually integrate those style-side changes without breaking their own customizations.

The more custom styles you maintain, and the more heavily you've modified them, the steeper this tax becomes. What's the solution? Read on to learn about how the Mapbox Standard Style changes the whole style paradigm.

Enter the Mapbox Standard Style (and style "imports")

I've spent all this time telling you about the old way of doing things and the underlying structure of a style so I can better explain the value of the new way. The Mapbox Standard Style is our premier, multipurpose basemap. At its core it is a style just like any other, with sources, layers, sprites, glyphs, etc, but it is designed to be imported and configured instead of being cloned and modified. This is a (relatively) new pattern for Mapbox styles, abstracting away the complexity of the basemap and allowing developers to focus their attention on the data they are presenting on top of the basemap.

In fact, when you load a map with the Mapbox Standard Style (either by not specifying a style at all, or by using the mapbox://styles/mapbox/standard URL), the renderer actually creates a new style on the fly that imports the Standard Style. The style that's actually loaded looks something like this:

{
  "version": 8,
  "sources": {},
  "layers": [],
  "imports": [
    {
      "id": "basemap",
      "url": "mapbox://styles/mapbox/standard"
    }
  ]
}

Mapbox Standard also introduces the concept of slots, which are placeholders in the layer stack of the imported style where any custom layers from the importing style can be inserted. For example, you may want your custom polygon layer to appear above paths and roads, but below buildings, models and labels, so you could place it in the middle slot. For more on slots in Mapbox Standard, see the Mapbox Standard Style documentation.

But what if you want to modify the individual layers in the Standard Style? Direct manipulation of these layers is not possible. This is part of the tradeoff of style imports. Instead of direct access to the layers, the style has been designed with a set of configurable properties. Think of it as an API for the style. You can summon standard with or without map labels, set the color of water, land, and park areas, and toggle 3D buildings.

Here's what that looks like in a Style JSON:

{
  "version": 8,
  "sources": {...},
  "layers": [...],
  "imports": [
    {
      "id": "basemap",
      "url": "mapbox://styles/mapbox/standard",
      "config": {
        showPlaceLabels: false,
        show3dObjects: false,
        colorWater: '#00F',
      }
    }
  ]
}

Best of all, the Standard Style is in continuous development, and because you are importing it instead of copying it, you get all the updates and improvements as they are released, without having to do any work to maintain it.

Implementation Patterns for the Mapbox Standard Style

Here I'll outline three common patterns for implementing the Mapbox Standard Style in your maps, and the pros and cons of each.

1. Instantiate with standard + config parameters, add data as runtime layers and/or Markers/Annotations

Mapbox Standard is now the default style for all Mapbox renderers, so specifying a style when you instantiate a map is no longer required. The renderers also accept config properties during map instantiation, so you can configure the Standard Style without having to create style JSON.

const map = new mapboxgl.Map({
  center: [-72, 41],
  zoom: 15.5,
  config: { // configure the Mapbox Standard Style before the map loads
    basemap: {
      showPlaceLabels: false,
      show3dObjects: false,
      colorWater: '#00F',
    }
  }
})

map.on('load', () => {
  map.addSource('my-data', {
    type: 'geojson',
    data: 'https://example.com/my-data.geojson'
  })

  map.addLayer({
    id: 'my-data-layer',
    type: 'circle',
    source: 'my-data',
    paint: {
      'circle-radius': 5,
      'circle-color': '#f00'
    }
  })
})

Pros:

Simple and straightforward, with no need to maintain any style JSON
Always up to date with the latest version of the Standard Style
Configurable without needing to understand the complexity of the style JSON
The basemap "just works" and you focus on adding your data after the map loads

Cons:

Duplicate client-side configuration if you are using the same style on multiple platforms (web, iOS, Android, Flutter)
Verbose if you are adding a lot of runtime layers and sources, as all of that has to be done in code instead of in a style JSON.

2. Create a custom style JSON that imports the Standard Style, and load the map with the custom style's URL

This approach means crafting your own style JSON, but it's a more manageable size since the Standard Style is abstracted away via an import. You can add your custom sources and layers to the style JSON, and configure the Standard Style via the config property in the import. This style JSON can be hosted anywhere, or included directly in your app's codebase.

const style = {
  "version": 8,
  "sources": {
    "my-data": {
      "type": "geojson",
      "data": "https://example.com/my-data.geojson"
    }
  },
  "layers": [
    {
      "id": "my-data-layer",
      "type": "circle",
      "source": "my-data",
      "paint": {
        "circle-radius": 5,
        "circle-color": "#f00"
      }
    }
  ],
  "imports": [
    {
      "id": "basemap",
      "url": "mapbox://styles/mapbox/standard",
      "config": {
        showPlaceLabels: false,
        show3dObjects: false,
        colorWater: '#00F',
      }
    }
  ]
}

const map = new mapboxgl.Map({
  style: style,
  center: [-72, 41],
  zoom: 15.5
})

Pros:

Centralized style management in a single JSON file, with no need for client-side configuration
Still up to date with the latest version of the Standard Style, without having to manage it yourself
Easier to maintain and update custom sources and layers in a style JSON than in code
Compatible with GeoJSON, image, and video source types

Cons:

Requires understanding of the style JSON structure and the concept of imports
Still requires maintaining a custom style JSON, which may be more work than just adding runtime layers

3. Create a custom style in the Style Editor

All custom styles created via the Mapbox Style Editor now include the Standard Style as an import, so if you are using the Style Editor to create your styles, you are already using the Standard Style under the hood, and can take advantage of all its features and updates without having to do anything extra. You can upload your data to the data workbench, add it to a style, configure the basemap, and get a mapbox:// URL that you can use across all platforms, with the confidence that your basemap is always up to date and looking great.

const map = new mapboxgl.Map({
  style: 'mapbox://styles/your-username/your-style-id',
  center: [-72, 41],
  zoom: 15.5
})

Pros:

No need to maintain any style JSON, as everything is done through the Mapbox Style Editor and served via a mapbox:// URL
The most user-friendly way to create and manage styles, with a visual editor and real-time preview

Cons:

May not be ideal for teams that prefer to manage styles in code or version control, as styles in the Style Editor are not as easily versioned or diffed as JSON files
Only compatible with vector and raster source types from Mapbox-hosted tilesets. If you want to use GeoJSON, image, or video sources, you would need to add those as runtime sources and layers in your app's code, which may be less than ideal if you have a lot of custom data to add.

Comparing The Standard Style with Classic Styles

Style	Usage approaches	Customization	Updates
Mapbox Standard Style	- Load by style URL; add your data layers at runtime - Create a custom style JSON that `imports` Standard as a dependency - Build a custom style in the Mapbox Style Editor that imports Standard	- Predefined configuration parameters (no raw layer editing) - Theme via lookup table (LUT) for cohesive color grading - Specify key colors to globally tint the style - Toggle POIs, landmarks, transit on/off - Light presets (day, dusk, dawn, night)	Automatic — Referenced by URL or import, Mapbox continuously updates the style and you receive all improvements (new features, data, rendering quality) automatically, without any action on your part.
Mapbox Classic Styles	- Load a Mapbox-hosted style URL (Streets, Satellite, Outdoors, etc.); add your data layers at runtime - Fork a Mapbox classic style into your own style JSON and customize freely - Create a custom style in the Mapbox Style Editor based on a classic style template, add your own data sources and layers	- Full access to every layer — edit colors, fonts, filters, zoom ranges directly - Add, remove, or reorder any layer - Customize data sources, expressions, and layout properties without restriction	Manual — When you fork or copy a classic style, it becomes a snapshot. You own the style JSON and must manually apply any upstream changes from Mapbox; there are no automatic updates.

Standard Style replaces multiple Classic Styles

The Mapbox Standard Style also includes config parameters for color themes and light presets, and combing these can yield drastically different looks.

With Classic Styles, we had whole different styles for different looks, like streets, light, and dark. Streets was a good all-purpose style for a basemap, with a wide variety of colors and details. Light and dark were designed to be more subdued, ideal for maps where the overlaid data should be the star of the show, and the basemap should recede into the background. With the Standard Style, you can achieve all three looks with one style, and have more control over the colors and details than ever before.

Classic Style	Equivalent using Standard Style
Mapbox Streets	`lightPreset: 'day'` (default)
Mapbox Light	`lightPreset: 'day'` + `colorTheme: 'monochrome'`
Mapbox Dark	`lightPreset: 'night'` + `colorTheme: 'monochrome'`

There's no quick configuration to replicate the Outdoors classic style with Mapbox Standard, but there is a style template which imports Standard and adds 3D terrain, hillshading, and topographic lines to get you the same effect. See the Outdoors template in the Mapbox Style Gallery. You can clone this template in the Style Editor and add your own data to it. Keep in mind that you'll get continuous updates to the Standard Style since it's imported, but the additional layers are yours to manage.

Modifying styles at runtime

Layers in a map style can be modified at runtime, and involves passing in bits of layer JSON to the setLayoutProperty and setPaintProperty methods on the map. This is a common pattern for adding interactivity to a map, such as changing the color of a layer when it's clicked, or toggling the visibility of a layer with a button click.

map.setLayoutProperty('my-layer', 'visibility', 'none');
map.setPaintProperty('my-layer', 'circle-color', '#0f0');

Since imported styles don't allow direct control of their internal map layers, control happens using the imported style's config parameters. All Mapbox renderers now include a method for modifying the config parameters of an imported style at runtime. This means you can change the colors, labels, and 3D settings of the Standard Style on the fly, without having to reload the map or create a new style JSON. This could be used to make the light preset (dawn, day, dusk, night) dynamic based on the user's actual time of day, or to toggle place labels on and off with a button click.

map.setConfigProperty('basemap', 'lightPreset', 'dusk');

map.setConfigProperty('basemap', 'showPlaceLabels', false);

See the setConfigProperty example for more details.

Building your own imported styles

While not widely documented, the style import pattern is not limited to just the Mapbox Standard Style. You can create your own styles that are designed to be imported into other styles, and have their own configuration options specific to your needs. This is a powerful pattern for managing complex styles, as it allows you to break down a large style into smaller, more manageable pieces, and reuse common elements across multiple styles.

{
  "version": 8,
  "sources": {...},
  "layers": [...],
  "imports": [
    {
      "id": "basemap",
      "url": "mapbox://styles/mapbox/standard",
      "config": { ... }
    },
    {
      "id": "transit",
      "url": "mapbox://styles/your-username/transit-style",
      "config": { 
        showAcessibleTransit: true,
        showTransitLabels: false,
      }
    }
  ]
}

Other style tips and tricks

Here are a few more tips.

Define GeoJSON source data in the style

You can store data for GeoJSON sources right in the style JSON, instead of linking to it. This is ideal for small datasets that are tightly coupled to the style and don't need to be updated independently. Just add a data property to your source definition and include the GeoJSON directly in the style JSON.

{
  "version": 8,
  "sources": {
    "my-data": {
      "type": "geojson",
      "data": {
        "type": "FeatureCollection",
        "features": [
          {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [-72, 41]
            },
            "properties": {
              "name": "My Point"
            }
          }
        ]
      }
    }
  }
}

Manipulate a style via code

When working with a style as a JavaScript object, you can provide GeoJSON data as a variable or assemble any part of the object programmatically before using it in a map.

const myData = {
  type: "FeatureCollection",
  features: [
    {
      type: "Feature",
      geometry: {
        type: "Point",
        coordinates: [-72, 41],
      },
      properties: {
        name: "My Point",
      },
    },
  ],
};

const myStyle = {
  version: 8,
  sources: {
    "my-data": {
      type: "geojson",
      data: myData,
    },
  },
};

// Add a source to the style
myStyle.sources.push({
  type: "vector",
  url: "https://someserver.com/path-to-tilejson.json",
});

Define the default camera position in the style

Mapbox renderers honor camera properties (center, zoom, pitch, bearing) from the style JSON, so you can set the initial map view in the style instead of in code. This is useful for ensuring a consistent initial view across platforms, or when maintaining a style separately from the app code. These properties exist at the root of the style object.

{
  "version": 8,
  "center": [58.0, 0.0],
  "sources": {},
  "layers": []
}

Wrapping up

When it comes to styles, you've got options. Whether you just want a quick and easy way to get a map on the screen, or you want complete control over every layer and source, the style specification and Mapbox's tools are flexible and can accommodate your needs.

The Mapbox Standard Style and the style import pattern have made it easier than ever to get a great-looking basemap up and running, while still allowing for customization and control when you need it.

Hopefully this post has demystified some of the magic and recent changes around map styles, and given you some ideas for how to work with them in your own projects. If you have any questions or want to share your own style tips and tricks, feel free to reach out or leave a comment!

Mapbox GL JS adds support for PMTiles vector sources

Chris Whong — Thu, 30 Apr 2026 16:15:47 +0000

Mapbox GL JS v3.21.0 added support for vector sources using the PMTiles protocol — another option in your toolkit for bringing spatial data into Mapbox-powered web maps.

What is PMTiles?

PMTiles is a single-file open source format for storing tiled map data — vector or raster — built for random access over HTTP range requests. Host one on any static file server and you have a fully functional tileset, no complicated backend required.

Traditional tile serving follows a familiar pattern: each tile gets its own URL using an x/y/z scheme, and behind that URL is either a directory of pre-cut files or a service dynamically pulling tiles from a database. Either way, there's infrastructure involved.

PMTiles sidesteps all of that. Every tile request hits the same URL — what changes is the byte range. A tile's x/y/z coordinates are converted into a specific byte offset within the file, and the server returns just that chunk. The client receives it and renders it like any other tile, none the wiser.

Using PMTiles in Mapbox GL JS

You're probably already familiar with adding a vector tileset to your map at runtime as a vector source. The existing options are:

A URL to a TileJSON(https://docs.mapbox.com/help/glossary/tilejson/) metadata file containing the tileset's URL template
A Mapbox-hosted tileset via its mapbox:// URL (a shorthand for a TileJSON hosted by Mapbox)
An explicit URL template with {z}/{x}/{y} placeholders

// TileJSON URL
map.addSource('mapbox-terrain', {
  type: 'vector',
  url: 'https://somedomain.com/tileset.json'
});

// Mapbox-hosted tileset
map.addSource('mapbox-terrain', {
  type: 'vector',
  url: 'mapbox://mapbox.mapbox-terrain-v2'
});

// Explicit x/y/z URL template
map.addSource('some-vector-tileset', {
  type: 'vector',
  tiles: ['https://somedomain.com/tileset/{z}/{x}/{y}']
});

In all three cases, Mapbox GL JS ends up with a {z}/{x}/{y} template URL and uses it to request tiles based on what's in view.

With PMTiles support, you can now pass a .pmtiles file URL directly as the url property:

map.addSource('mapbox-terrain', {
  type: 'vector',
  url: 'https://somedomain.com/tileset.pmtiles'
});

That's it. Mapbox GL JS detects the .pmtiles extension and handles range requests behind the scenes.

A Working Example

The example below shows USGS Earthquake data served from a PMTiles file and visualized with a circlelayer.

See the full example on docs.mapbox.com →

Here's the JavaScript where addSource() is called with a URL to .pmtiles file:

mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/standard',
  config: {
    basemap: {
      theme: 'monochrome',
      lightPreset: 'night'
    }
  },
  zoom: 1.78,
  center: [-103.64548, 51.14245]
});

map.on('load', () => {
  map.addSource('pmtiles-earthquakes', {
    type: 'vector',
    url: 'https://docs.mapbox.com/mapbox-gl-js/assets/earthquakes.pmtiles'
  });

  map.addLayer({
    id: 'pmtiles-vector-layer',
    type: 'circle',
    source: 'pmtiles-earthquakes',
    'source-layer': 'earthquakes',
    paint: {
      'circle-color': 'transparent',
      'circle-stroke-color': 'teal',
      'circle-stroke-width': 0.5,
      'circle-radius': 3,
      'circle-emissive-strength': 1
    }
  });
});

How do I make a PMTiles?

The PMTiles file in the example above was generated with tippecanoe from a week's worth of USGS earthquake data (~2,400 point features) and hosted on the same S3 bucket as docs.mapbox.com:

tippecanoe -o public/earthquakes.pmtiles -Z0 -z6 -r1 -pk -l earthquakes data/earthquakes-week.geojson --force

Here's what each flag does:

Flag	Description
`-o public/earthquakes.pmtiles`	Output file path
`-Z0`	Minimum zoom level (global view)
`-z6`	Maximum zoom level
`-r1`	Drop rate of 1 — don't drop any features at any zoom
`-pk`	Allow tiles to exceed the 500KB size limit to preserve all features
`-l earthquakes`	Layer name, referenced as `source-layer` in your style
`data/earthquakes-week.geojson`	Input GeoJSON
`--force`	Overwrite output file without prompting

Try It Yourself

Looking for publicly hosted PMTiles files to experiment with? Check out pmtiles.io — it includes several global vector and raster tilesets and is a handy tool for previewing PMTiles files you generate yourself.

We'd love to hear about what you're building — drop into the #web channel in the Mapbox Discord or share a post on r/mapbox.

A GUI editor for Mapbox Color Themes

Chris Whong — Tue, 03 Mar 2026 17:38:03 +0000

Introducing a browser-based prototype tool for iterating on custom Mapbox Standard Style themes in real time — no terminal required.

tl;dr: Open the Mapbox Standard Style Theme Editor →

Maps are a visual medium, and color is one of the most powerful tools in a cartographer's toolkit. Whether you're building a dark-mode experience for a nighttime delivery app, a muted editorial look for a data visualization, or a vivid branded style for a consumer product, the color of your basemap sets the entire tone.

Mapbox Standard — Mapbox's premier basemap style — supports deep color customization through a mechanism called Lookup Tables (LUTs). Most developers haven't encountered LUTs before. They're more at home in film post-production than web development. But once you understand how they work, they're an elegant and powerful way to retheme a map.

This post explains what LUTs are, how Mapbox Standard uses them, and introduces a prototype web tool I built for experimenting with custom color themes in real time: the Mapbox Standard Style Theme Editor.

The Mapbox Standard Style

Mapbox Standard is Mapbox's flagship basemap. It features 3D buildings, photorealistic landmarks, dynamic lighting, and a set of built-in configuration options that make it easy to adapt for a wide range of use cases.

For many applications, the quickest path to a custom look is the lightPreset option, which controls ambient and directional lighting to simulate different times of day — dawn, day, dusk, or night. Combined with predefined theme options like faded, and monochrome, you can achieve a lot without writing much code.

Below you can see Mapbox Standard with its default color theme and daytime light as compared to the night lighting preset and monochrome theme, creating a subdued dark basemap:

You can also control some colors in Mapbox Standard via the configuration options, such as colorWater, colorLand, colorGreenSpace, etc, so a Lookup Table is not required to start customizing colors on the map.

You can try out the preset themes and individual color config options in the Mapbox Standard Style Playground.

But for those who want event more control over the color palette, Mapbox Standard supports setting theme to custom and supplying your own Lookup Table.

What Exactly Is a LUT?

A Lookup Table — or LUT — is a data structure that maps input color values to output color values. In image and video processing, a LUT is typically encoded as a small image (sometimes called a "HALD CLUT" or "color cube") where each pixel's position in the image encodes an input RGB value, and its color encodes the corresponding output.

Think of it as a complete color transformation recipe. Every possible input color has a predetermined output, and the LUT defines that mapping across the entire visible spectrum at once. Apply the LUT to any image, and every pixel is remapped accordingly.

This image shows the "identity LUT", with no colors modified. It's a png with a repeating set of "squares" laid out horizontally. Each square shows red values along the x-axis, and green values along the y-axis. If you can mentally stack the squares, they become a cube, with blue values along the z-axis. The cube represents all possible color values and is used to map any input color to a corresponding output color.

In video production, LUTs create consistent "looks" — film emulation, color grading, log-to-linear conversions. In photography, they power the one-click preset packs ubiquitous in Lightroom marketplaces. In Mapbox Standard, they're the engine behind custom color themes.

The key insight is that the LUT doesn't know or care what it's being applied to. It just says: "If you see this color, output that color." Mapbox Standard renders the map to an intermediate image, applies your LUT, and out comes a fully rethemed map — buildings, roads, labels, land, water — all transformed consistently.

Here is a custom LUT that applies a 15-degree hue rotation and increased saturation.

At first glance it looks the same as the identity LUT above, but look closely and you'll see subtle differences. You can see it applied to both a standalone image (from wikimedia commons), and to the Mapbox Standard Style below:

Try this handy LUT tool by Tony Gratzer to see how different LUTs affect an input image.

Where Do LUTs Come From?

Download one

There's a whole ecosystem of pre-made LUTs available online — similar to stock photography. Sites like Fixthephoto and RocketStock offer free and paid collections. Searching for "free HALD CLUT" will surface many more.

Build one in Photoshop

Photoshop's color grading tools — Curves, Hue/Saturation, Color Balance — can be applied to a standard identity LUT image and then exported. If you're working with a designer, this is a natural fit. Mapbox has a step-by-step tutorial here: Create a custom color theme with Photoshop.

Build one in the browser

Several web-based tools let you create LUTs without any desktop software. LUT Maker by o-l-l-i provides sliders for hue rotation, saturation, brightness, contrast, and more, and exports the result as a PNG.

The Challenge: Iterating on Custom Themes in a Mapbox Map

When I set out to learn custom theming in Mapbox Standard, I arrived at what felt like the natural iteration loop:

Open a browser-based LUT editor and adjust the sliders
Export the LUT as a PNG
Base64-encode it in the terminal: base64 -i my-lut.png | pbcopy
Open the Mapbox Standard Style Playground
Paste the string into the theme field
Look at the result on the map
Go back to step 1

This worked. But it was tedious. Each iteration meant downloading a file, switching to the terminal, running a command, switching windows, and pasting a very long string — just to preview one change. For something as tactile and visual as color grading, that friction destroys creative momentum.

The fix was obvious: put the LUT editor and the map in the same window.

That's exactly what the Mapbox GL Theme Editor does.

Introducing the Mapbox GL Theme Editor

→ Try it now

The tool is a single-page web app pairing a LUT generation UI with a live Mapbox Standard map. It's open source and hosted on GitHub Pages.

Global controls

The main panel applies broad color adjustments across the entire palette:

Hue rotation — shifts all colors around the color wheel
Saturation — makes colors more vivid or more muted
Brightness — lightens or darkens the overall output
Contrast — expands or compresses the tonal range
Temperature — pushes the palette warmer (golden) or cooler (blue)

Drag any slider and the LUT preview in the sidebar updates instantly — and so does the map.

Targeted color corrections

For more surgical edits, the tool includes a color correction mode. An eyedropper lets you select a specific color on the map — the blue of the water, the tan of building facades, the green of parks — and remap it to a different hue. A tolerance slider controls how broadly neighboring colors are pulled along.

This is the right tool when you want to make precise changes: darken just the water, push the buildings to a warmer gray, or give vegetation a more stylized tint — without affecting anything else. The image below shows a targeted color correction changing water from light blue to light violet with low tolerance.

Warning: The Mapbox Standard Style is in active development and default colors could change in the future. An LUT with targeted color corrections may not apply as expected if the input color changes in a future release of Mapbox Standard.

Using Your Theme

You can use the LUT you create in the theme editor in your real-world map development:

In Mapbox Studio

In Mapbox Studio, apply a custom LUT by navigating to the Standard style's theme settings, setting the theme to "Custom" and uploading your LUT as an image file.

In the Standard Style Playground

You can also test directly in the Mapbox Standard Style Playground by setting the theme to custom and pasting in the base64 encoded string for your LUT. You can combine your custom theme with other Standard configuration options — toggling 3D buildings, point-of-interest labels, light presets — and see how they interact.

The Standard Style Playground also provides handy code snippets for applying your theme at runtime in Mapbox GL JS or the Mapbox Mobile Maps SDKs.

In your frontend code

You can use the base64 encoded string in your frontend code when using Mapbox GL JS or the Maps SDKs for iOS and Android along with the theme and theme-data Mapbox Standard Style config properties.

Here's an example of how to instantiate a web map using the Mapbox Standard Style and a custom theme in a web project:

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/standard',
  config: {
    basemap: {
      theme: 'custom',
      'theme-data': YOUR_LUT_STRING
    }
  },
  center: [-73.99059, 40.74012],
  zoom: 11.50
});

Why Build a Custom Tool?

Beyond solving the iteration problem, there was an educational motivation for building this.

LUTs are unfamiliar territory for most web and mobile developers. The best way to build intuition for how they work is to play with one — to drag a hue slider and immediately see every green park on the map turn magenta, or to pick the water with an eyedropper and watch the rivers shift from steel blue to teal. The tool makes an abstract concept concrete in a way that documentation simply can't.

It also demystifies the pipeline. When the LUT preview image updates in the same window as the map, you can see exactly what a LUT is and what it does. You start to understand why cranking contrast makes building shadows punch harder, or why rotating the hue by 180 degrees turns a daylight city into something that looks like a photo negative. That understanding makes you a more intentional user of the feature.

On the practical side, the faster loop changes the quality of the work. Color choices that used to require five minutes of file-downloading and clipboard gymnastics now take five seconds of slider dragging. That's not just a time savings — it's the difference between exploring ten variations and exploring a hundred.

What's Next?

This is a prototype. It works and it's fun to use, but there's room to grow. The repo is open source at github.com/chriswhong/mapboxgl-theme-editor. Issues and pull requests are welcome. And there's a conversation worth having about whether this kind of functionality should eventually live inside Mapbox Studio or the Standard Style Playground — or whether the complexity of a dedicated theming workflow makes it better as its own tool.

Give It a Try

The best way to understand LUTs and custom theming in Mapbox Standard is to open the tool and start dragging sliders. It takes about thirty seconds before you're looking at a map that doesn't look like any map you've seen before.

Open the Mapbox Standard Style Theme Editor →

When you find a look you like, grab the base64 string and drop it into your project — or share a screenshot and tell me what you made.

How Lemontree improved map performance with a small refactor

Chris Whong — Fri, 13 Feb 2026 21:51:45 +0000

A Q&A with Samuel Cole, CTO of Lemontree

Lemontree is a New York-based nonprofit on a mission to fight food insecurity by connecting hungry Americans to free food resources near them. Often described as a "Yelp for food banks," they curate and manage rich data on thousands of food pantries across the U.S., making it accessible through an easy-to-use digital platform with maps, SMS alerts, and more. In 2025, Lemontree helped over a million people locate nearby food pantries.

At the heart of their product is an interactive map — powered by Mapbox GL JS — that lets users instantly see nearby pantry locations, hours, and available foods. Recently, Lemontree overhauled how they load and display map data to dramatically improve performance. We sat down with Samuel Cole, CTO of Lemontree, to learn how they approached the problem and what they'd do differently from the start.

Chris: Let's start with the original setup. What were you displaying on the map, where did the data come from, and what was falling short in terms of user experience?

Samuel: When we load a map, we first call an endpoint to find the best 10 resources for the focus point of the map using our AI sorting algorithm, but then we don't want you to miss out on the other resources in the area, so we built an API called markersWithinBounds that returns all the resources within the bounding box of the map. These are visualized as many smaller background markers in addition to the larger "best 10 resources" markers.

We're using react-map-gl so it was straightforward to loop over the results of that api call with a .map() and create a component for each one. When we first built that, we were testing pretty zoomed in to a few blocks around the location, so while the density of food pantries is pretty high (there are more food pantries in the US than McDonalds!), it seemed like it was scaling ok, because most people are only interested in the immediate area.

But in real life, pretty much everybody immediately zoomed out! All of a sudden the API call returned thousands of points, and rendering thousands of Markers on the screens was chugging. Users' whole device was lagging and slow, and then if they started panning around? It was wild.

Zooming out on the map triggered an API call for new data and could contain hundreds of points or more.

Chris: This is a classic Mapbox GL JS pitfall that catches a lot of developers by surprise. Markers are the most intuitive way to get point features on a map — the API is simple, positioning is easy, and you can drop in a custom image without much fuss. But they're rendered as individual DOM elements, which means performance degrades quickly as the count climbs. Beyond a few hundred markers, you're fighting the browser itself. After you hit this wall, what solutions did you explore, and how did you arrive at the right path forward?

Samuel: When I was preparing my talk for the BUILD with Mapbox virtual conference, you actually pulled me aside and said: "Hey, if you used a symbol layer for this it would scale a ton better."

Chris: Ah, well you were in the right place to get a direct suggestion! Hopefully this post will help a lot more people who might be hitting the same issue. Symbol layers are rendered by the GPU as part of the map's WebGL canvas, which means they handle thousands of points with ease and pan or zoom without any jank. The tradeoff is that they're less intuitive to set up, especially in a React codebase where you're used to thinking declaratively. Can you walk us through what the refactor actually looked like?

Samuel: We have a lot going on at Lemontree! I wasn't able 📍 immediately prioritize that work, but one Friday I took it on as sort of a 'hack day' project. Unfortunately, I got a bit stuck because the react-map-gl <Layer> component, which was declarative in the React style, was being added before the style was loaded, and I just ran out of time in my hack day to figure it out. When I got access to AI-assisted development through Copilot and Claude Code, I was looking for little test cases, and I remembered this performance issue: I asked Claude, it added an styleLoaded && pattern, and we were off to the races! You can compare the code for the Marker implementation vs the Symbol layer:

Before: Markers 📍

 {/* Old approach: Render a DOM marker for each resource */}
  {otherMarkersData?.features.map((feature) => (
    <Marker
      key={feature.properties.id}
      latitude={feature.geometry.coordinates[1]}
      longitude={feature.geometry.coordinates[0]}
    >
      <Image
        src={purplePin}
        alt="Resource"
        width={20}
        height={25}
        style={{ cursor: 'pointer' }}
        onClick={() => router.push(`/resources/${feature.properties.id}`)}
      />
    </Marker>
  ))}

Problems:

Creates a DOM node for every marker (100s+ of elements)
Heavy re-renders when panning/zooming
Poor performance with many markers
Limited styling options

After: Symbol Layer 🚀

{/* New approach: Single GeoJSON source with symbol layer */}
  <Source
    id="other-resources"
    type="geojson"
    data={filteredOtherMarkersData}
    promoteId="id"
  >
    <Layer
      id="other-resources-layer"
      type="symbol"
      layout={{
        'icon-image': 'purpleMarker',
        'icon-allow-overlap': true,
      }}
    />
  </Source>

Benefits:

Single GeoJSON source for all markers
GPU-accelerated rendering
Smooth performance with 1000+ markers
Feature state for hover effects
Click/hover handled via interactiveLayerIds

Performance Impact:

10x faster rendering
Butter-smooth panning and zooming
Reduced memory footprint

Chris: That's a great example of AI tooling unblocking a task that kept slipping down the priority list. The styleLoaded guard is a small but critical detail — symbol layers depend on the map style being fully initialized before you can add sources or layers to the canvas at runtime, and it's an easy thing to miss until things break in subtle ways. What has the impact been since shipping? Are users noticing the difference?

Samuel: Our clients are spending a bit more time exploring around the map, but honestly our recommendation algorithm gives plenty of food pantries near where they live, so in surprising ways exploring the map isn't their primary way of discovering food resources, and they use the map more for navigating the pantries we've already referred them to. Where the map really shines is with our partners! Organizations that run many pantries love to see their whole network, foundations love to see our coverage, and governments are interested in how food access is working in their districts.

Chris: That's a fascinating insight — power users for the map include the partner organizations doing network-level planning, not just the end users trying to find nearby food. It reframes what "map performance" means for your product. Speaking of which, you've been building on Mapbox for a long time. What's your overall take on the platform — what's working well, and where do you think there's room to grow?

Samuel: We love Mapbox; I've been using maps for my whole career, ever since my very first tech startup job, and Mapbox reflects my values for open, accessible, and extensible maps. The reality is that other mapping providers just don't offer the extensibility of Mapbox's platform, whenever I want to create a more targeted experience (which I believe people experiencing food insecurity deserve the best experiences!) the out-of-the-box approach from other map providers, just isn't going to cut it. I don't want a Google Map, I want a Lemontree Map.

Chris: "I don't want a Google Map, I want a Lemontree Map" — I love that. Mapbox gives you all you need to make the whole map experience your own creation. What's on the roadmap next for mapping at Lemontree?

Samuel: I love maps! Around Lemontree, my coworkers all call me the map guy. I think as we grow, it's going to be even more important for our partners to visualize how food access works around the U.S., so I'm excited to make more visualizations to tell stories like "Where are the food pantries that focus on elderly people in New Jersey, and where are the gaps?" There are almost 50 million people who experience food insecurity in the US, and we have a lot of work to do to understand where they are, and what resources they have available to them.

Chris: Great, hopefully Mapbox maps can help with that data storytelling to raise awareness about food insecurity. Thanks for chatting with me about your map's technical hiccup and the fix. I'm glad to hear the map is performing better, especially given the importance of the data you're displaying on it.

Takeaways

Lemontree's Markers to symbol layer refactor is a great case study in a problem many Mapbox developers encounter: Markers and symbol layers are both valid tools for displaying point data, but they have very different performance profiles.

Markers are DOM elements — straightforward to set up, but expensive to render at scale. Symbol layers are drawn by WebGL on the map's canvas, making them capable of displaying tens of thousands of points without breaking a sweat. If you're showing dynamic data that can grow beyond a few hundred points, a symbol layer is almost always the right call.

These graphics help explain the difference between Markers, which are DOM elements displayed "on the map" versus symbol layers which are rendered "in the map"

For teams building in React with react-map-gl, the key implementation detail is guarding your layer additions behind a styleLoaded check — a small fix that, as Samuel found, can make the difference between a polished experience and a broken one. (the equivalent when using Mapbox GL JS without a wrapping library is listening for the map.on(style.load) event.

You can learn more about when to use Markers versus symbol layers in the Add your Data guide in the Mapbox GL JS documentation.

Squarespace X Mapbox

Chris Whong — Thu, 12 Feb 2026 14:48:12 +0000

How to Add an Interactive Mapbox Map to Your Squarespace Website

This guide shows developers how to integrate Mapbox GL JS into a Squarespace website using Squarespace's embed block. If you're already familiar with Mapbox GL JS development and want to add custom interactive maps to your Squarespace site, this post will show you exactly where to place your code to get it working.

✅ What this guide covers: The technical steps to embed Mapbox GL JS code in a Squarespace website
❌ What this guide doesn't cover: Details of interactive map development with Mapbox GL JS (the examples are a great place to start for inspiration and working code snippets)

We'll show a simple example of displaying a business location with a marker, popup, and rotating camera to demonstrate the integration. Once you understand where the code goes and how it's structured in Squarespace, you can implement any Mapbox GL JS functionality you need by changing the JavaScript code.

Here's a codepen so you can get a better look at the actual map and animation shown in this guide. It uses the Mapbox Standard Style as a basemap, showing detailed 3D buildings and an optional monochrome theme. The popup is styled to match the green colors used on the Squarespace site it is embedded in:

Note: This technique of adding custom HTML, CSS and JavaScript via the Squarespace editor is suitable for simpler Mapbox GL JS implementations but does not include version control or other benefits of a separate development workflow. If your map becomes more complex, you may want to deploy it as a standalone web app, then embed it in your Squarespace site using its URL.

Prerequisites

To follow this guide, you'll need:

A Squarespace website
Working knowledge of Mapbox GL JS - you should be comfortable writing HTML, CSS, and JavaScript to create maps
A Mapbox account and access token - if you don't have one yet, sign up here

Getting Your Mapbox Access Token

Before we start, you'll need a Mapbox access token:

Go to mapbox.com and sign up for a free account (if you don't have one)
Once logged in, navigate to your console
Find the "Tokens" link in the left sidebar to go to the tokens page
Copy your default public token (it starts with pk.)

Keep this token handy—you'll need it in a moment.

Step 1: Adding the Code Block

Let's add the HTML that will contain your map code:

Open your Squarespace Editor and navigate to the page where you want to add the map
Click the + ADD BLOCK button
Scroll down in the block selection panel to find "Embed"
Drag and resize the embed block to position it wherever you want it on your site layout.
Double-click on the embed block to open its Content settings panel. Under EMBED AS, choose Code Snippet, then click the Embed Data button.
A code editor will appear. You will add code to this input in the next step.

Step 2: Add Mapbox GL JS Code

Now you'll add Mapbox GL JS code to get a map working in the code block. The code block accepts any HTML, so you can include CSS and JavaScript by using <style> and <script> tags.

Here's a working example that shows a business location with a marker and rotating camera. Copy this code and replace YOUR_MAPBOX_ACCESS_TOKEN with your actual access token:

<!-- import Mapbox GL JS and its CSS file -->
<script src='https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.js'></script>
<link href='https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.css' rel='stylesheet' />

<!-- override default styles for the map and popup -->
<style>
  .mapboxgl-popup-content {
    background-color: #e6f2d2;
    color: #2f5f48;
  }
</style>

<!-- add a container element for the map -->
<div id="map-container" style="position: absolute; height: 100%; width: 100%"></div>

<script>
  // your Mapbox access token
  mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';

  // initialize the map
  const map = new mapboxgl.Map({
    container: 'map-container', // container ID
    style: 'mapbox://styles/mapbox/standard', // style URL
    center: [-73.99986, 40.75300], // starting position [lng, lat]
    zoom: 15.36, // starting zoom
    bearing: 28.00, // bearing in degrees
    pitch: 56.50, // pitch in degrees
    config: {
      basemap: {
        theme: 'monochrome', // use the monochrome basemap theme
        showPointOfInterestLabels: false // hide point of interest labels
      }
    }
  });

  // disable scroll zoom so the map won't zoom as the user scrolls down the page
  map.scrollZoom.disable();

  // create a popup with address details and a link to get directions on Google Maps
  const popup = new mapboxgl.Popup({
    closeOnClick: false,
    closeButton: false,
    offset: 40,
  }).setHTML(
    `<div>
      450 W 33rd St<br/>
      New York, NY 10001</div>
      <a href="https://maps.app.goo.gl/6WzErvMBMi2Hn64Z7" target="_blank" rel="noopener noreferrer"><span class="text-xs">Get Directions</span></a>
    `
  );

  // create a map marker with a custom color, connect the popup, add it to the map, and open the popup
  new mapboxgl.Marker({
    color: '#2f5f48'
  })
    .setLngLat([-73.99986, 40.75300])
    .setPopup(popup)
    .addTo(map)
    .togglePopup();

  // this function rotates the camera continuously
  // see https://docs.mapbox.com/mapbox-gl-js/example/animate-camera-around-point/
  function rotateCamera(timestamp) {
    map.rotateTo((timestamp / 200) % 360, { duration: 0 });
    requestAnimationFrame(rotateCamera);
  }

  map.on('load', () => {
    // start the camera animation.
    rotateCamera(0);
  })
</script>

Paste the Mapbox GL JS snippet from above into the code editor.

Important: Replace the placeholder text YOUR_MAPBOX_ACCESS_TOKEN with the actual token you copied from your Mapbox account.

Click anywhere outside the editor panel to apply your code update. You will see a warning about embedded scripts, with an option to preview in safe mode. This is normal, as Squarespace prevents execution of JavaScript code in the editor by default.

Exit the editor. You should see an animated map with a monochrome basemap, a marker centered over New York City, and a slowly rotating camera. That's it, you're ready to publish this map on your site!

Understanding the Code Structure

Here's how the code for this example map breaks down:

1. Library Imports

<script src='https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.js'></script>
<link href='https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.css' rel='stylesheet' />

These load Mapbox GL JS and its required stylesheet from the Mapbox CDN.

2. Custom Styles

<style>
  .mapboxgl-popup-content {
    background-color: #e6f2d2;
    color: #2f5f48;
  }
</style>

The popup styles customize the appearance to match the page theme.

3. Map Container

<div id="map-container" style="position: absolute; height: 100%; width: 100%"></div>

This div is where the map renders. The inline styles ensure it fills the available space.

4. Your Map Logic

<script>
  // All your Mapbox GL JS code goes here
</script>

This is where you implement your map functionality. In this example, we're:

Setting the access token
Initializing the map with specific style and camera settings
Disabling scroll zoom (important for Squarespace pages!)
Creating a popup and marker
Adding a camera rotation animation

You can replace or extend this code with any Mapbox GL JS functionality you need.

If you want to adapt this example of a single marker and popup, you should:

Change the map's center point, zoom, pitch and bearing to your desired initial camera view.
Change the Marker's coordinates
Change the Popup's content by editing the HTML code in Popup.setHTML()

Or, you can leave the imports and the map container in place and start over with the map JavaScript code and build whatever you need. See additional developer resources below.

Resources for Mapbox GL JS Development

Here are essential resources for building your map functionality:

Mapbox Documentation

Mapbox GL JS Examples - Dozens of live, interactive code examples
Mapbox GL JS Guides
Mapbox GL JS API Reference - Complete documentation of all map methods and options

Key Examples

Display a map - Basic map initialization
Add markers to a map - Working with markers
Display a popup - Popup functionality
Add GeoJSON data - Display custom data

Community

r/mapbox on Reddit - Get help and share ideas
Mapbox Developer Discord - Post in the #web channel to ask questions and share what you build.

Troubleshooting

Map not displaying?

Verify you've replaced YOUR_MAPBOX_ACCESS_TOKEN with your actual token
Check that your access token has the correct permissions
Ensure the code block has sufficient height and width in the Squarespace editor and that the map container div also has sufficient height and width
Open your browser's developer console to check for JavaScript errors

By following the steps in this guide, you should now have a Mapbox GL JS map working in your Squarespace website and are ready to iterate the JavaScript code to customize the map to meet your needs.

Questions about this integration approach? Found a better way to do something? Share your experience in the comments!

DEV Community: Mapbox

Rebuilding geojson.io: A Look at the 2026 Overhaul

Why overhaul it

How we approached it

What Placemark gave us

The new stack

What we built on top

Still open source

Understanding the `near` Parameter in Mapbox's Search Box API

The problem near solves

How near works

Where this fits in a real product

Splitting a natural-language query into q and near

near vs. proximity vs. bbox

proximity — bias, don't restrict

bbox — a hard rectangular filter

near — resolves to proximity or bbox, depending on the anchor

A sample request and response

Quick comparison

When to reach for which

What to expect at the edges

Wrapping up

Putting a Live Map Inside Your AI Agent's Chat: MCP Apps and render_map_tool

Try it now

A quick primer: MCP and MCP Apps

Why one tool, not one map per tool

Chaining: directions in, a live map out

Standalone: your own data, no other Mapbox tool required

Where this fits if you cannot render MCP Apps at all

The short version

Build with Location AI

Prompting for interactive web maps in 2026

But first, GeoJSON data!

The generic web map prompt

Mapbox GL JS: ask for it by name!

Adding UI/UX polish

Why naming your tools matters

Try it yourself

Did You Know? Mapbox Geocoding API Lets You Filter by Feature Type

Filtering with types

Why it matters

Quick Tip: Dynamic Speed Units in Mapbox Navigation SDK for Android

The Implementation

1. Updating the Layout

2. The Toggle Logic

3. Updating the View

Why it matters

React + Mapbox GL JS: Custom Markers, Popups, and Bounds-Based Data Fetching

React + Mapbox GL JS: Custom Markers, Popups, and Bounds-Based Data Fetching

The Core Challenge: Two DOMs

Setting Up: A Map Component That Fetches Data

The Marker Component

Rendering Markers from Data

The Popup Component

Putting It All Together

Where to Take It From Here

Demystifying Mapbox Styles

What even is a style?

The Style Specification

Other ways to get a style JSON into your map

Load JSON from your codebase

Web

Mobile Applications (iOS, Android, Flutter)

Host a JSON file somewhere (anywhere!)

When would I ever need to do this?

Implementation patterns for using Mapbox-hosted Classic Styles

1) Load a Mapbox classic style (mapbox://styles/mapbox/streets-v12) and add your data at runtime

2) Make a custom style based on (e.g. cloned from) a Mapbox-hosted style

The "Maintenance Tax" of Classic Styles

Enter the Mapbox Standard Style (and style "imports")

Implementation Patterns for the Mapbox Standard Style

1. Instantiate with standard + config parameters, add data as runtime layers and/or Markers/Annotations

2. Create a custom style JSON that imports the Standard Style, and load the map with the custom style's URL

3. Create a custom style in the Style Editor

Comparing The Standard Style with Classic Styles

Standard Style replaces multiple Classic Styles

Modifying styles at runtime

Building your own imported styles

Other style tips and tricks

Define GeoJSON source data in the style

The problem `near` solves

How `near` works

Splitting a natural-language query into `q` and `near`

`near` vs. `proximity` vs. `bbox`

`proximity` — bias, don't restrict

`bbox` — a hard rectangular filter

`near` — resolves to proximity or bbox, depending on the anchor

Filtering with `types`