Forem: Mapbox

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!

Introducing Mapbox Agent Skills

Matthew Podwysocki — Wed, 11 Feb 2026 22:09:57 +0000

I'm excited to share something we've been working on that makes building with Mapbox a lot easier, especially if you're using AI coding assistants like Claude Code, Cursor, or GitHub Copilot.

We've built a collection of Agent Skills that teach AI assistants how to build better Mapbox applications. Think of it as giving your AI assistant a crash course in Mapbox development best practices.

TL;DR

Agent Skills teach AI assistants Mapbox development best practices. We've built 15 skills and counting covering web/iOS/Android integration, performance optimization, search implementation, geospatial operations, map design, migrations, security, and common patterns. Install them and your AI will know things like "cluster 1000+ markers" and "use Search Box API for autocomplete."

Install all skills:

npx add-skill mapbox/mapbox-agent-skills

Install specific skills:

npx skills add mapbox/mapbox-agent-skills --skill mapbox-web-performance-patterns

List available skills:

npx skills add mapbox/mapbox-agent-skills --list

What Are Skills?

If you've been using AI coding assistants, you've probably noticed they're pretty good at writing code, but sometimes they miss the nuances. They might suggest patterns that work but aren't optimal, or miss important details about how things should be done.

Agent Skills are a way to fix this. They're folders with instructions and guidance that AI assistants can load and use when helping you build. Unlike tools (which let AI do things) or prompts (which give specific instructions), skills provide domain expertise. The know-how.

When an AI assistant has access to Mapbox skills, it knows things like "if you're adding 1000+ markers, you should use clustering" or "use the Search Box API for autocomplete, not the Geocoding API." It's the difference between an AI that knows how to code and one that knows how to code Mapbox apps specifically.

See It In Action

This production-ready store locator was built in minutes using Claude Code with Mapbox Agent Skills. The AI assistant handled marker patterns, distance calculations, search functionality, and responsive design automatically—following Mapbox best practices from the start.

Why Skills Are Important

Here's the thing: Mapbox has a lot of surface area. We have SDKs for web, iOS, and Android. We have multiple search APIs with different use cases. We have performance patterns that matter at scale. We have migration paths from other platforms.

When you're building with an AI assistant, you want it to know all this stuff. You don't want to spend time correcting it when it suggests using 1000 individual markers instead of clustering. You don't want it to miss that you should debounce search requests. You want it to just know.

That's what these skills do. They encode the knowledge we've built up from working with thousands of developers building Mapbox applications. The patterns that work. The mistakes to avoid. The right tool for the job.

What's Inside the Box

We've organized the skills into a few main areas. Here's what's available:

Platform Integration

Web, iOS, and Android patterns - These skills cover the fundamentals of integrating Mapbox into your app, whether you're building for the web with React, Vue, Svelte, or Angular, or going native with Swift/SwiftUI on iOS or Kotlin/Jetpack Compose on Android. They know about framework-specific patterns, lifecycle management, and platform best practices.

Performance

Web performance patterns - This one's huge. It covers everything from initialization strategies to handling thousands of markers, optimizing data loading, and managing memory. If you're building something that needs to perform at scale, this skill will save you a lot of debugging time.

Search

Search integration and patterns - We have two skills here. One walks through the complete workflow of adding search to your app (asking the right discovery questions, picking the right product, implementing it correctly). The other helps you choose between our different search tools and configure them properly. Between these two, your AI assistant will know exactly how to implement search for your use case.

Geospatial Operations

Geometric calculations and routing - This skill helps decide when to use offline geometric calculations (like measuring straight-line distance) versus when to use our routing APIs (like getting actual drive times). It's the "as the crow flies vs as the crow drives" decision framework, plus a ton of practical examples.

Design and Cartography

Map design, styles, and quality - Three skills covering cartographic principles (color theory, visual hierarchy, typography), common style patterns and layer configurations, and style validation and optimization. If you're doing custom map design, these will help you make maps that look professional and work well.

Migration

Google Maps and MapLibre migration - If you're moving from Google Maps Platform or MapLibre, these skills provide comprehensive migration guides with API equivalents and pattern translations. They know the gotchas and the breaking changes.

Security

Token security - Best practices for handling access tokens securely across all platforms. This is one of those things that's easy to get wrong, so having your AI assistant know the right patterns from the start is valuable.

Common Patterns

Store locators - A focused skill on building location finders and store locators, with patterns for markers, filtering, distance calculations, and all the UX details that make these features work well.

Getting Started

Installing skills is straightforward. If you're using Claude Code, Cursor, or another AI assistant that supports Agent Skills, you can add them all at once:

npx skills add mapbox/mapbox-agent-skills

Or install specific skills if you only need certain ones:

npx skills add mapbox/mapbox-agent-skills --skill mapbox-web-performance-patterns

You can list what's available:

npx skills add mapbox/mapbox-agent-skills --list

Once installed, your AI assistant will automatically use these skills when you're working on Mapbox projects. You don't need to do anything special. Just start building and you'll notice better suggestions, fewer mistakes, and more production-ready code.

Pro tip: These skills work great with our Mapbox MCP servers. We have the Mapbox MCP Server for core Mapbox operations and the Mapbox MCP DevKit Server for development workflows. Skills provide the expertise (how to design good maps, which patterns to use), while MCP tools provide the actions (create styles, generate tokens, preview maps). Together they make a pretty powerful development workflow.

Build Stuff and Let Us Know

We built these skills based on what we've learned from years of working with developers building Mapbox applications. But they'll get better as more people use them and give us feedback.

If you build something cool with these skills, or if you find gaps where your AI assistant could use more guidance, let us know. Open an issue on GitHub or contribute a new skill if you've discovered patterns we should capture.

We're excited to see what you build.

Unlocking Mapbox GL JS's Hidden Field of View Control

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

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

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

The Problem: Fixed Field of View

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

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

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

What is the Transform Class?

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

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

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

The (Unofficial) Solution

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

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

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

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

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

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

FOV Values Explained

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

How It Works Under the Hood

When you modify _fov, three things need to happen:

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

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

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

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

Interactive Field of View Controller

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

Why Isn't This a Public API?

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

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

The Risks

Before you rush to implement this, understand the risks:

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

Alternative: The FreeCamera API

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

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

Conclusion

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

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

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

Additional Resources

Mapbox Demo: Bike route visualization color gradient and data scrubbing UX

Chris Whong — Mon, 09 Feb 2026 18:45:07 +0000

A developer on Reddit recently asked for help building a ride playback feature with speed visualization on a Mapbox GL JS map. They had detailed GPS and speed data from a bike ride and wanted to show speed variations along the route.

The Challenge

The original question centered on two main requirements:

Visualize speed variations along the route with color-coded gradients (slow = green, medium = yellow, fast = red)
Interactive scrubbing that shows detailed speed and time data when the user hovers over any point on the route

The Solution

Here's the working implementation on codepen. The line visualizes the variations in speed along the bike trip. Move your mouse over the line to "scrub" and see data for a specific spot on the line.

Key Implementation Details

Speed Gradient
Instead of creating separate line segments for each speed zone, we use a single GeoJSON LineString with lineMetrics: true and build a dynamic gradient using the line-gradient paint property:

'line-gradient': [
  'interpolate',
  ['linear'],
  ['line-progress'],
  ...gradientStops  // Dynamically generated from speed data
]

Each speed data point gets mapped to a position along the line (0 to 1) and assigned a color based on its speed value. Check out the official line-gradient example for more details on this technique.

A Note on Accuracy
This demo simplifies the gradient calculation by evenly distributing speed data points along the line based on timestamps. In a production app, you'd want to map each speed measurement to its actual GPS coordinate along the route for precise gradient placement. This ensures the gradient accurately reflects where speed changes occurred geographically, not just temporally.

Interactive Scrubbing
The scrubber uses geometry calculations to find the nearest point on the route as you move your mouse, then interpolates between speed data points to show accurate values at that location. A pink circle marker follows your cursor along the route, displaying the time and speed in a floating tooltip.

Performance Benefits

This approach renders a single line layer with a gradient instead of dozens of individual geometries, resulting in:

Faster initial render
Smooth interactions
Lower memory usage
Simpler state management

Cross-Platform Compatibility

While this example uses Mapbox GL JS for the web, the same line-gradient technique works on iOS and Android using the native Maps SDKs. The gradient expression syntax is consistent across all platforms.

Check out the full code in the CodePen above to see how the speed interpolation and distance calculations work. Happy mapping!

Wix X Mapbox

Chris Whong — Wed, 04 Feb 2026 17:43:31 +0000

How to Add an Interactive Mapbox Map to Your Wix Website

This guide shows developers how to integrate Mapbox GL JS into a Wix website using the Wix editor's embed code feature. If you're already familiar with Mapbox GL JS development and want to add custom interactive maps to your Wix 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 Wix 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 Wix, you can implement any Mapbox GL JS functionality you need by changing the JavaScript code.

Note: This technique of adding custom HTML, CSS and JavaScript via the Wix 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 Wix site using its URL.

Prerequisites

To follow this guide, you'll need:

A Wix 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.

How Wix Embeds Work

Before we dive in, it's important to understand what's happening under the hood. When you add an embed element in the Wix editor, it becomes an <iframe> in your published site. This iframe contains whatever HTML, CSS, and JavaScript you add to it—completely isolated from the rest of your Wix page.

This isolation is actually a benefit: you have complete control over the content inside the iframe without worrying about conflicts with Wix's own code. You can implement any Mapbox GL JS functionality you want, exactly as you would in a standalone HTML page.

Step 1: Adding the Embed Element

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

Open your Wix Editor and navigate to the page where you want to add the map
Click the "+ Add" button (in the top left) to add an element
Scroll through the different elements and select "Embed"
Choose "Embed Code" on the next panel
Drag and resize the embed element to your desired size on the page
Double click the embed element to open its Settings panel

Step 2: Add Mapbox GL JS Code

Now you'll add Mapbox GL JS code to get a map working in the embed. The embed 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>
  body {
    margin: 0
  }

  .mapboxgl-popup-content {
    background-color: #e6f2d2;
    color: #2f5f48;
  }

  .mapboxgl-popup-tip {
    border-top-color: #e6f2d2 !important;
  }
</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>

Delete the existing code in the textarea labeled Enter HTML embed code and paste the Mapbox GL JS snippet from above:

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

Click "Apply" to save your code, then preview your site. You should see an interactive map with a monochrome basemap, a marker centered over New York City, and a slowly rotating camera.

Understanding the Code Structure

Here's how the code for this 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>
  body {
    margin: 0
  }

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

The body { margin: 0 } removes default margins so the map fills the entire iframe. 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 Wix 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 embed element has sufficient height and width in the Wix 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 Wix 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!

Server-rendered Maps for Web and Mobile

Chris Whong — Thu, 29 Jan 2026 16:42:21 +0000

A Developer's Guide to the Mapbox Static Images API

Interactive maps are a powerful user experience element — they let users pan, zoom, and explore wide geographic areas or interact with dense datasets. But there's a catch: not every use case needs the full weight of a client-rendered map.

Rendering vector maps in the client requires loading all the map data into the browser or device, which means significant network traffic, device processing overhead, and performance costs.

Sometimes you just need a picture of a map.

If users are quickly scrolling past location information, or if you're displaying a long list where every item needs a map thumbnail, it doesn't make sense to bring in a vector map library or SDK and load lots of client-rendered data just to show a marker or two.

That's where the Mapbox Static Images API comes in.

What Is the Static Images API?

The Mapbox Static Images API is an HTTP endpoint that returns map images. All you need is a center point (latitude and longitude) and a zoom level (0 is zoomed out to world level, 18 or so gets you to street level). This will serve up a beautiful map image from anywhere in the world — no JavaScript libraries, no SDK packages, no client-side rendering, just a clean image URL.

To help you get an understanding of the URL structure for a call to the Static Images API, here are some map images of landmarks and their associated Static Images API URLs. You can try the URLs yourself, just replace YOUR_MAPBOX_ACCESS_TOKEN with an access token from your Mapbox account:

The Eiffel Tower

The site of the Eiffel Tower in Paris (2.295,48.8584), France, using the Mapbox Streets style at zoom 12.77:

https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/2.295,48.8584,12.77,0/400x300@2x?access_token=YOUR_MAPBOX_ACCESS_TOKEN

The site of the Golden Gate Bridge (-122.4717,37.8177) in San Francisco, California, USA, using the Mapbox Dark style at zoom 10.56:

https://api.mapbox.com/styles/v1/mapbox/dark-v11/static/-122.4717,37.8177,10.56,0/400x300@2x?access_token=YOUR_MAPBOX_ACCESS_TOKEN

The site of the Sydney Opera House in Sydney, Australia, using the Mapbox Satellite Streets style at zoom 13.63.

https://api.mapbox.com/styles/v1/mapbox/satellite-streets-v12/static/151.215,-33.858,13.63,0/400x300@2x?access_token=YOUR_MAPBOX_ACCESS_TOKEN

As you can see, the syntax for the URL structure is straightforward. Each of these images is 800x600 pixels (the request shows 400x300@2x for retina images), and include the longitude, latitude, zoom level, and style id.

You can copy the URLs, add your own Mapbox access token and change out the longitude and latitude coordinates to get a map image for an area of interest to you. If you need to quickly get coordinates for a place, try our handy Location Helper tool.

Adding Your Data with Overlays

It's rare that you would ever want just a basemap. The real power of the Static Images API comes from its overlays feature. Overlays let you add your own data — markers, lines, and polygons — directly onto the map.

The overlay system is completely flexible: you can use simple longitude and latitude coordinates, or bring in encoded linestrings or GeoJSON for more complex geometries. This makes it trivial to combine Mapbox's professional basemaps with your application's location data.

Overlays use a DSL and end up as sections of the URL. For example, a small (s) red (#b44646) marker at coordinates -0.1717,51.5068 is encoded as pin-s+b44646(-0.1717,51.5068). Don't worry about the learning curve for encoding overlays, we made a Developer Playground to help you configure them.

Three Real-World Use Cases

Below are three practical examples that showcase how to combine Mapbox basemaps with overlays from the Static Images API.

1. Directions Route with Origin and Destination Markers

A common use cases in location apps is showing directions and travel times from point A to point B. Whether you're building a ride-sharing app, a delivery service, or a travel planner, you need to visualize routes clearly.

With the Static Images API, you can overlay a route polyline along with markers for the origin and destination. This gives users an instant visual understanding of the journey without requiring them to interact with a full map.

Example:

https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/path-7+6d8afd-0.8(ycmlFdweuM%3FglAsF%40B_CirAi%7CGkHyfG%7ByCspD%7B%7DGyfCyrAgsCenHcoCgbDylBiaHgkJ_lDabB_fGszFuxDqeJ%7BfCw%5Bq%7C%40%7BcAwcEczA_Aa%7D%40aR%5C%5C%3F),pin-l+51bd5e(-77.0393863890253,38.90253),pin-l+f54747(-76.612299,39.289643)/-76.7636,39.1125,8.45,0/600x400@2x?attribution=true&logo=true&access_token=YOUR_MAPBOX_ACCESS_TOKEN

Use an encoded polyline overlay for the route geometry (The Mapbox Directions API can return this format, that's where the geometry in this example came from)
Add marker overlays for origin and destination with different colors

2. Property Listing with 15-Minute Accessibility Isochrone

Real estate and rental platforms need to communicate location value effectively. Showing a home's location is helpful, but showing what's accessible from that location is even better.

An isochrone is a polygon that represents all the areas reachable from a point within a certain time frame. (We have an API for that too!) For a property listing, overlaying a 15-minute isochrone shows potential buyers or renters exactly how far they can get by walking, biking, or driving — highlighting the home's convenience and accessibility.

This approach could also show the delivery area for a business or any other relevant polygon like a school district.

Example:

https://api.mapbox.com/styles/v1/mapbox/dark-v11/static/geojson({"type":"FeatureCollection","features":[{"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-76.508577,42.514225],[-76.509957,42.513128],[-76.509123,42.508674],[-76.51144,42.504265],[-76.513577,42.502387],[-76.510127,42.500128],[-76.511751,42.498128],[-76.512271,42.488128],[-76.511283,42.487128],[-76.511306,42.483128],[-76.510324,42.480128],[-76.504437,42.472268],[-76.504167,42.470538],[-76.50139,42.467128],[-76.501189,42.464516],[-76.505282,42.461833],[-76.507577,42.46181],[-76.508577,42.459468],[-76.503577,42.45937],[-76.505579,42.457126],[-76.505802,42.454903],[-76.507577,42.453848],[-76.515345,42.45436],[-76.51784,42.452865],[-76.513262,42.450444],[-76.515998,42.448128],[-76.519319,42.453386],[-76.521577,42.455901],[-76.525577,42.452965],[-76.523118,42.451587],[-76.522831,42.449128],[-76.520577,42.449318],[-76.517225,42.445128],[-76.521577,42.443245],[-76.521074,42.438128],[-76.524371,42.436128],[-76.521759,42.434128],[-76.514694,42.434245],[-76.511158,42.433548],[-76.510105,42.430128],[-76.505996,42.428128],[-76.502577,42.428537],[-76.500033,42.432584],[-76.498334,42.429128],[-76.500068,42.428619],[-76.500394,42.425945],[-76.503844,42.423395],[-76.503226,42.418128],[-76.505035,42.417128],[-76.505053,42.412128],[-76.50193,42.410481],[-76.501943,42.417128],[-76.499577,42.418592],[-76.497577,42.417807],[-76.495368,42.419919],[-76.497856,42.421407],[-76.494862,42.424128],[-76.489532,42.425173],[-76.485245,42.42246],[-76.483325,42.418128],[-76.480532,42.417083],[-76.482577,42.421654],[-76.484577,42.423622],[-76.482577,42.426795],[-76.485577,42.428684],[-76.486205,42.4315],[-76.476577,42.43128],[-76.475212,42.428493],[-76.470462,42.427243],[-76.468432,42.425273],[-76.469064,42.422641],[-76.464577,42.42142],[-76.462577,42.422323],[-76.460151,42.419554],[-76.456427,42.418278],[-76.455088,42.416617],[-76.451321,42.415128],[-76.455346,42.410897],[-76.459955,42.408506],[-76.458864,42.407414],[-76.455822,42.409373],[-76.451921,42.410785],[-76.449577,42.412473],[-76.443373,42.411332],[-76.437577,42.4076],[-76.436152,42.409554],[-76.439795,42.41091],[-76.447756,42.414949],[-76.453774,42.420325],[-76.448577,42.420775],[-76.448577,42.426175],[-76.453577,42.426839],[-76.456253,42.429452],[-76.461745,42.43196],[-76.461577,42.434379],[-76.457577,42.434404],[-76.4523,42.432406],[-76.446577,42.432548],[-76.450577,42.434781],[-76.455577,42.434836],[-76.458759,42.435946],[-76.458898,42.438128],[-76.461577,42.438809],[-76.466099,42.442606],[-76.464577,42.444003],[-76.458577,42.443598],[-76.454577,42.44578],[-76.452594,42.448111],[-76.450577,42.448707],[-76.446577,42.45155],[-76.440577,42.452472],[-76.438577,42.454801],[-76.442577,42.454598],[-76.446577,42.452706],[-76.449577,42.452709],[-76.450577,42.45048],[-76.45896,42.449511],[-76.466132,42.452128],[-76.46527,42.455128],[-76.473577,42.457868],[-76.475924,42.463128],[-76.476577,42.466596],[-76.471577,42.466572],[-76.467379,42.46493],[-76.464225,42.46748],[-76.465716,42.469267],[-76.468577,42.469357],[-76.469577,42.471132],[-76.472577,42.46976],[-76.475128,42.470128],[-76.475922,42.472473],[-76.474547,42.475128],[-76.477756,42.477128],[-76.477876,42.480128],[-76.474577,42.481343],[-76.468331,42.481374],[-76.469151,42.478702],[-76.467634,42.475071],[-76.4651,42.474128],[-76.465577,42.480314],[-76.461577,42.482593],[-76.455577,42.482704],[-76.454577,42.481743],[-76.450052,42.482128],[-76.454577,42.484442],[-76.462577,42.483733],[-76.463577,42.482681],[-76.468577,42.483644],[-76.476577,42.483066],[-76.481577,42.481804],[-76.486278,42.482829],[-76.491577,42.480834],[-76.495577,42.481012],[-76.493917,42.483128],[-76.500868,42.483837],[-76.502166,42.487128],[-76.504577,42.48936],[-76.506515,42.489128],[-76.505577,42.484372],[-76.503577,42.48469],[-76.502328,42.481879],[-76.504875,42.481426],[-76.504915,42.478128],[-76.508832,42.481128],[-76.50985,42.484128],[-76.509782,42.488128],[-76.510887,42.489128],[-76.510926,42.493128],[-76.509491,42.493042],[-76.508864,42.498841],[-76.506173,42.500128],[-76.509066,42.502128],[-76.509133,42.505128],[-76.507936,42.508128],[-76.508577,42.514225]]]},"properties":{"fill-opacity":0.33,"opacity":0.33,"fill":"%237dcff5","fillOpacity":0.33,"color":"%23bf4040","contour":10,"metric":"time"}}]}),pin-l-home+744ce1(-76.48957711003335,42.44212800096554)/-76.4821,42.4615,10.98,0/600x400@2x?attribution=true&logo=true&before_layer=admin-0-boundary-bg&access_token=YOUR_MAPBOX_ACCESS_TOKEN

Generate the isochrone polygon using the Mapbox Isochrone API
Add it as a GeoJSON polygon overlay with a semi-transparent fill
Place a marker overlay at the property location to clearly identify the starting point
Use the before_layer parameter to position overlay underneath the map labels
Use a dark basemap style to make the colors pop

3. School Proximity Map with Labeled Markers

Parents searching for a new home often prioritize school proximity. For a real estate or neighborhood information app, showing a home's location alongside nearby schools provides instant context about the area.
Using the Static Images API, you can overlay multiple custom markers — one for the home and one for each nearby school — with labeled markers (A, B, C) to make it easy to cross-reference with a list displayed alongside the map.

Example:

https://api.mapbox.com/styles/v1/mapbox/light-v11/static/pin-s-c+4682b4(-122.3332,47.6113),pin-s-b+4682b4(-122.3401,47.6161),pin-s-a+4682b4(-122.3521,47.6138),pin-l-star+66ff2e(-122.3428,47.6139)/-122.3425,47.6141,13.8,0/600x400@2x?attribution=true&logo=true&access_token=YOUR_MAPBOX_ACCES_TOKEN

Use a distinct marker style for the home location
Add labeled markers for each school with letters A, B, C (Glyphs are also available as marker labels using the label parameter)

Use the Developer Playground to get started

The Static Images API Playground makes it easy to get started without needing to learn the intricacies of the overlay DSL or manually dial your map in to your desired area and zoom level. The Playground provides a graphical user interface where you can easily position the map, add overlays visually, and tinker with all the API parameters in real time.

We recently improved the overlay UI to make it even simpler to add markers, lines, and polygons — just click, drag, and configure. Once your map image and overlays look exactly the way you want, simply copy the generated URL.

You can use that URL directly in your frontend code as an <img> source, or use it as a template to generate similar URLs dynamically based on your application's data — just swap in different coordinates, zoom levels, or overlay parameters as needed.

When to Choose Static Maps

Static maps aren't a replacement for interactive maps — they're a complement.

Use static maps when:

You're displaying many maps at once (list views, galleries, grids)
The map is supplementary context, not the primary interaction
You need fast page loads and minimal JavaScript overhead
You want a consistent image that won't change based on user interaction

By combining beautiful Mapbox basemap styles with your own overlay data, the Static Images API gives you a lightweight, performant way to bring maps into your web and mobile applications — without the complexity or cost of full interactive rendering.

Ready to get started?

Try the Static Images API Playground and see how easy it is to create custom static maps for your next project.
See the API reference documentation for detailed breakdowns of each parameter.

Gradio X Mapbox

Chris Whong — Thu, 29 Jan 2026 16:25:53 +0000

A developer on r/mapbox asked for if anyone had successfully integrated a Mapbox GL JS map with Gradio, a python library for creating web interfaces for machine learning models.

After a quick peek at Gradio's docs, I quickly found the sections on adding custom CSS and JS. With a bit of help from AI, I learned the best way to get data out of python world and into JavaScript world in a Gradio app (there are several ways, but the one I used involves stashing it in a hidden output textarea)

I built a demo to show a simple implementation of Gradio X Mapbox:

Start with a pandas dataframe of U.S. cities with their longitude/latitude coordinates.
Convert the city points to GeoJSON in python, dropping the GeoJSON in a hidden output.
On map load, pick up the GeoJSON and add circles to the map representing the cities using a geojson source and a fill layer.
Add a button to trigger some processing in python. In this case, it's the calculation of a convex hull around the point data.
Convert the convex hull to GeoJSON and stash it in another hidden output.
Render the convex hull polygon on the on the map using a geojson source and a fill layer.

There are a few considerations for loading Mapbox GL JS:

Load Mapbox GL JS and its css via CDN links using the head argument of demo.launch
Create a map container div using gr.HTML()
Before instantiating the map, poll for the existence of the map container (it may not exist when the JavaScript code first runs). In the example below, there is a timeout and subsequent checks for setting up the map.

The full code snippet is below if you want to give it a try. You'll need a Mapbox access token to get it working, so sign up here if you don't already have a Mapbox account.

import gradio as gr
import pandas as pd
import numpy as np
import json
from shapely.geometry import MultiPoint, mapping, Point


# cities DataFrame
df = pd.DataFrame({
    "city": [
        "New York",
        "Los Angeles",
        "Chicago",
        "Houston",
        "Phoenix",
        "Philadelphia",
        "San Antonio",
        "San Diego",
        "Dallas",
        "San Jose",
    ],
    "lat": [
        40.7128,
        34.0522,
        41.8781,
        29.7604,
        33.4484,
        39.9526,
        29.4241,
        32.7157,
        32.7767,
        37.3382,
    ],
    "lon": [
        -74.0060,
        -118.2437,
        -87.6298,
        -95.3698,
        -112.0740,
        -75.1652,
        -98.4936,
        -117.1611,
        -96.7970,
        -121.8863,
    ],
})


# compute convex hull and return GeoJSON
def compute_convex_hull(data):
    points = [Point(row["lon"], row["lat"]) for _, row in data.iterrows()]
    multipoint = MultiPoint(points)
    hull = multipoint.convex_hull
    hull_geojson = mapping(hull)
    features = [
        {
            "type": "Feature",
            "geometry": mapping(pt),
            "properties": {"city": row["city"]},
        }
        for pt, (_, row) in zip(points, data.iterrows())
    ]
    geojson = {
        "type": "FeatureCollection",
        "features": [
            {
                "type": "Feature",
                "geometry": hull_geojson,
                "properties": {"type": "convex_hull"},
            }
        ]
        + features,
    }
    return json.dumps(geojson)


# convert points to GeoJSON for initial display
def get_points_geojson(data):
    """Convert dataframe to GeoJSON for initial point display"""
    features = [
        {
            "type": "Feature",
            "geometry": {"type": "Point", "coordinates": [row["lon"], row["lat"]]},
            "properties": {"city": row["city"]},
        }
        for _, row in data.iterrows()
    ]
    return json.dumps({"type": "FeatureCollection", "features": features})


# Gradio interface, two columns: left data table and button, right map display
with gr.Blocks() as demo:
    with gr.Row():
        with gr.Column():
            gr.Markdown(
                """
                # US Cities Convex Hull Demo
                This demo computes the convex hull of a set of US cities and outputs the result as GeoJSON for display on a [Mapbox GL JS](https://docs.mapbox.com/mapbox-gl-js/) map.

                GeoJSON strings are assembled in python and stored in hidden Gradio outputs for easy access in the Javascript map code.
                """
            )
            gr.Dataframe(df, label="City Locations")
            btn = gr.Button("Compute Convex Hull GeoJSON")


        # this html includes the map container, Mapbox GL JS will add a map in this div
        with gr.Column():
            gr.HTML(
                """
                <div>
                    <h3>Mapbox GL JS Visualization</h3>
                    <div id='map-container' style='width: 100%; height: 450px; background-color: lightgray;'></div>
                    <div>© Mapbox &nbsp; © OpenStreetMap</div>
                </div>
                """
            )


    # empty output boxes to hold GeoJSON data
    geojson_output = gr.JSON(visible=False)
    initial_points = gr.JSON(value=get_points_geojson(df), visible=False)


    def handle_click():
        return compute_convex_hull(df)


    # on click, compute convex hull and update map
    btn.click(
        handle_click,
        outputs=geojson_output,
    ).then(
        None,
        inputs=geojson_output,
        outputs=None,
        js="""
        (data) => {
            console.log("Received GeoJSON data:", data);
            if (window.map) {
                // Remove existing hull layer if it exists
                if (window.map.getLayer('convex-hull')) {
                    window.map.removeLayer('convex-hull');
                }
                if (window.map.getSource('hull')) {
                    window.map.removeSource('hull');
                }


                // Add hull
                window.map.addSource('hull', {
                    type: 'geojson',
                    data: data,
                });


                window.map.addLayer({
                    id: 'convex-hull',
                    type: 'fill',
                    source: 'hull',
                    paint: {
                        'fill-color': '#088',
                        'fill-opacity': 0.3,
                        'fill-emissive-strength': 1,
                    },
                });


                window.map.addLayer({
                    id: 'convex-hull-outline',
                    type: 'line',
                    source: 'hull',
                    paint: {
                        'line-color': '#FFF',
                        'line-width': 2,
                        'line-emissive-strength': 1,
                    },
                });
            }
        }
        """,
    )


    # on initial load, initialize a map, then add points as a GeoJSON source and circle layer
    # initMap() contains a retry mechanism to wait for the map container to be available,
    # as Gradio may take some time to render the HTML and the map container div may not be present immediately
    demo.load(
        None,
        inputs=initial_points,
        outputs=None,
        js="""
        (pointsData) => {
            function initMap() {
                const container = document.getElementById('map-container');
                if (!container) {
                    setTimeout(initMap, 100);
                    return;
                }


                mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';


                window.map = new mapboxgl.Map({
                    container: 'map-container',
                    style: 'mapbox://styles/mapbox/standard',
                    config: {
                        basemap: {
                            theme: 'monochrome',
                            lightPreset: 'night',
                        },
                    },
                    center: [-98.92906, 40.25617],
                    zoom: 2.5,
                    projection: 'mercator',
                    attributionControl: false,
                });


                // Add points after map loads
                window.map.on('load', function () {
                    window.map.addSource('cities', {
                        type: 'geojson',
                        data: pointsData,
                    });


                    window.map.addLayer({
                        id: 'city-points',
                        type: 'circle',
                        source: 'cities',
                        paint: {
                            'circle-radius': 6,
                            'circle-color': '#B42222',
                            'circle-emissive-strength': 1,
                        },
                    });
                });
            }


            initMap();
        }
        """,
    )


# load mapbox gl js and its css in the head
head = """
<link href="https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.js"></script>
"""


# custom css to position the Mapbox logo, as Gradio css interferes with default positioning
# note that attributionControl is set to false in the map options because Gradio CSS also interferes with the attribution control
# map attribution is required and was manually added in the HTML above
custom_css = """
.mapboxgl-ctrl-bottom-left .mapboxgl-ctrl,
.mapboxgl-ctrl-left .mapboxgl-ctrl {
    margin: 0 0 10px 10px !important;
}
"""


demo.launch(head=head, css=custom_css)

Build a ChatGPT App with Mapbox

Chris Tufts — Fri, 09 Jan 2026 19:40:05 +0000

ChatGPT Apps are a new way to build interactive experiences within the ChatGPT interface. In this tutorial, we'll explore and run a Points of Interest (POI) search app powered by Mapbox APIs that lets users find places like coffee shops, restaurants, and gas stations near any location using natural language. The focus of this tutorial is on understanding how to build a ChatGPT App using the ChatGPT Apps SDK and the Model Context Protocol (MCP). The app is loosely based on the Mapbox Build a store locator using Mapbox GL JS tutorial, but adapted for the ChatGPT UI. For the remainder of the post I'll refer to ChatGPT apps as apps for brevity.

How ChatGPT Apps Work

From a user perspective, utilizing an app is identical to the traditional chat workflow: select any tools you want to use, type a prompt into the chat interface, and you get a response.

The workflow under the hood starts in ChatGPT, utilizes your app (an MCP server), and uses the results to render a widget in the chat UI. The process is shown in the following diagram.

┌─────────────────────────────────────────────────────────────────┐
│                         ChatGPT                                 │
│        User: "Find coffee shops near Times Square"              |
│                           │                                     │
│                           ▼                                     │
│              Calls find_nearby_places tool                      │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Your MCP Server                              │
│  • Geocode "Times Square" → coordinates (Geocoding API)         │
│  • Search for "coffee" near coordinates (Search Box API)        │
│  • Return structuredContent with place data                     │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                         ChatGPT                                 │
│  • Receives structuredContent from tool response                │
│  • Sets window.openai.toolOutput = structuredContent            │
│  • Loads your widget HTML (from MCP resource) in an iframe      │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│              Your Widget (iframe in ChatGPT UI)                 │
│  • Your HTML/CSS/JS from widget.html                            │
│  • Reads data from window.openai.toolOutput                     │
│  • Renders Mapbox GL JS map with markers                        │
└─────────────────────────────────────────────────────────────────┘

Key Concepts

If you are new to MCP's and ChatGPT apps, the following table shows some new key concepts to keep an eye out for as we go through the example. The table is meant for quick reference as more detail will be provided as we progress through the tutorial.

Concept	What It Is	In Our App
MCP	Model Context Protocol— the spec for connecting an LLM with external tools and resources	The App is an MCP server
Resource	An HTML template ChatGPT can render	Our map widget (`widget.html`)
Tool	External tools our MCP exposes to ChatGPT	`find_nearby_places` tool
`text/html+skybridge`	MIME type that tells ChatGPT "this is a widget"	Set on our resource
`window.openai.toolOutput`	How tool results reach your widget	Contains our POI/place data

Learn more: See the ChatGPT Apps SDK documentation for detailed guides on MCP servers, widgets, tools, and more.

Project Setup

Prerequisites

Mapbox account with access token (get one here). For additional info on tokens see the deep dive.
Node.js 18+ installed
ChatGPT Plus or Team account with developer mode enabled
(Optional): Download ngrok for local development. ChatGPT requires the MCP be hosted behind an HTTPS endpoint, ngrok is a simple way to do this.

1. Clone the repository

git clone https://github.com/mapbox/location-ai-tutorials.git
cd location-ai-tutorials/chatgpt-app-tutorial

2. Install dependencies

npm install

Package	Purpose
`@modelcontextprotocol/sdk`	MCP protocol implementation
`zod`	Schema validation (required by MCP)
`dotenv`	Load environment variables

3. Configure environment

Copy the example environment file and add your Mapbox token:

cp .env.example .env

Edit .env and add your token:

MAPBOX_ACCESS_TOKEN=pk.your_token_here

4. Project structure

chatgpt-app-tutorial/
├── server.js           # MCP server
├── public/
│   └── widget.html     # Map widget
├── package.json
├── .env.example
└── .env                # Your local config (not tracked)

Understanding the MCP Server

Let's walk through server.js to understand how the MCP server works.

Server setup

import "dotenv/config";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { createServer } from "node:http";
import { readFileSync } from "node:fs";
import { z } from "zod";

// Load widget HTML and inject Mapbox token
const widgetHtml = readFileSync("public/widget.html", "utf8")
  .replace("{{MAPBOX_ACCESS_TOKEN}}", process.env.MAPBOX_ACCESS_TOKEN || "");

function createPoiSearchServer() {
  const server = new McpServer({
    name: "poi-search",
    version: "1.0.0"
  });

  // Resources are added here

  return server;
}

Register the widget resource

Resources are HTML templates that ChatGPT can render. The key is the text/html+skybridge MIME type which tells ChatGPT it's a widget, not just HTML text.

server.registerResource(
  "places-widget",           // Name (for reference)
  "ui://widget/places.html", // URI (links tool output to this widget)
  {},
  async () => ({
    contents: [{
      uri: "ui://widget/places.html",
      mimeType: "text/html+skybridge",  // This makes it a widget!
      text: widgetHtml,
      _meta: {
        "openai/widgetPrefersBorder": true
      }
    }]
  })
);

Register the find_nearby_places tool

Tools are functions ChatGPT can call. The _meta["openai/outputTemplate"] links this tool to our widget. When ChatGPT calls the tool, the widget renders with the returned data.

server.registerTool(
  "find_nearby_places",
  {
    title: "Find Nearby Places",
    description: "Use this when the user wants to find places like coffee shops, restaurants, gas stations, grocery stores, or other businesses near a specific location. Always requires both a type of place and a location.",
    inputSchema: {
      category: z.string().describe("Type of place to search for (e.g., 'coffee', 'restaurant', 'grocery', 'pharmacy', 'gas station', 'hotel', 'bank')"),
      location: z.string().describe("Location to search near (e.g., 'Times Square NYC', 'downtown Seattle', '1600 Pennsylvania Ave')")
    },
    _meta: {
      "openai/outputTemplate": "ui://widget/places.html",  // Link to widget
      "openai/toolInvocation/invoking": "Searching for nearby places...",
      "openai/toolInvocation/invoked": "Places found"
    }
  },
  async ({ category, location }) => {
    // Implementation coming next
  }
);

Add Mapbox API helpers

The following functions call Mapbox APIs to convert text locations to coordinates and search for places.

// Convert text location to coordinates
async function geocodeLocation(locationText, accessToken) {
  const url = new URL("https://api.mapbox.com/search/geocode/v6/forward");
  url.searchParams.set("q", locationText);
  url.searchParams.set("access_token", accessToken);
  url.searchParams.set("limit", "1");

  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`Geocoding failed: ${response.status}`);
  }

  const data = await response.json();
  if (!data.features || data.features.length === 0) {
    throw new Error(`Could not find location: ${locationText}. Try a more specific address or city name.`);
  }

  const feature = data.features[0];
  const [longitude, latitude] = feature.geometry.coordinates;
  const placeName = feature.properties.full_address || feature.properties.name || locationText;
  return { longitude, latitude, placeName };
}

// Search for places by category
async function searchCategory(categoryId, longitude, latitude, accessToken) {
  const url = new URL(`https://api.mapbox.com/search/searchbox/v1/category/${encodeURIComponent(categoryId)}`);
  url.searchParams.set("access_token", accessToken);
  url.searchParams.set("proximity", `${longitude},${latitude}`);
  url.searchParams.set("limit", "10");

  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`Category search failed: ${response.status}`);
  }

  return response.json();
}

Add category mapping and response transformer

These helper functions normalize user input to Mapbox category IDs and transform the API response to our widget's expected format:

// Category mappings - maps common user terms to Mapbox category IDs
const CATEGORY_MAPPINGS = {
  "coffee": "coffee",
  "coffee shop": "coffee",
  "restaurant": "restaurant",
  "grocery": "grocery",
  "gas station": "gas_station",
  "pharmacy": "pharmacy",
  "hotel": "hotel",
  "bank": "bank",
  // ... add more as needed
};

function mapCategoryToId(userCategory) {
  const normalized = userCategory.toLowerCase().trim();
  return CATEGORY_MAPPINGS[normalized] || normalized;
}

// Transform Mapbox response to widget-compatible GeoJSON
function transformToWidgetGeoJSON(mapboxResponse, categoryName) {
  return {
    type: "FeatureCollection",
    features: (mapboxResponse.features || []).map((feature) => ({
      type: "Feature",
      geometry: feature.geometry,
      properties: {
        name: feature.properties.name || "Unknown",
        address: feature.properties.address || feature.properties.full_address || "",
        city: feature.properties.context?.place?.name || "",
        state: feature.properties.context?.region?.region_code || "",
        postalCode: feature.properties.context?.postcode?.name || "",
        phoneFormatted: feature.properties.metadata?.phone || null,
        category: categoryName,
        mapbox_id: feature.properties.mapbox_id
      }
    }))
  };
}

Implement the tool

Now wire up the tool to use these helper functions and return data in the format our widget expects:

async ({ category, location }) => {
  const accessToken = process.env.MAPBOX_ACCESS_TOKEN;

  if (!accessToken) {
    return {
      content: [{ type: "text", text: "Error: Mapbox access token not configured." }],
      isError: true
    };
  }

  try {
    // Step 1: Geocode the location
    const { longitude, latitude, placeName } = await geocodeLocation(location, accessToken);

    // Step 2: Map category to Mapbox ID
    const categoryId = mapCategoryToId(category);

    // Step 3: Search for places
    const searchResults = await searchCategory(categoryId, longitude, latitude, accessToken);

    // Step 4: Transform to widget format
    const places = transformToWidgetGeoJSON(searchResults, category);

    // Step 5: Calculate map center and zoom
    const center = [longitude, latitude];
    const zoom = places.features.length > 0 ? 13 : 12;

    return {
      structuredContent: {
        places: places,
        center: center,
        zoom: zoom,
        searchLocation: placeName,
        searchCategory: category
      },
      content: [{
        type: "text",
        text: places.features.length > 0
          ? `Found ${places.features.length} ${category} places near ${placeName}.`
          : `No ${category} places found near ${placeName}. Try a different location or category.`
      }]
    };
  } catch (error) {
    return {
      content: [{ type: "text", text: `Search failed: ${error.message}` }],
      isError: true
    };
  }
}

Set up the HTTP server

ChatGPT connects to your server via HTTP. The /mcp endpoint handles the MCP protocol.

const PORT = process.env.PORT || 8787;

const httpServer = createServer(async (req, res) => {
  // CORS headers (required for ChatGPT)
  if (req.method === "OPTIONS") {
    res.writeHead(204, {
      "Access-Control-Allow-Origin": "*",
      "Access-Control-Allow-Methods": "POST, GET, OPTIONS, DELETE",
      "Access-Control-Allow-Headers": "Content-Type, mcp-session-id"
    });
    res.end();
    return;
  }

  // MCP endpoint
  if (new URL(req.url, `http://localhost`).pathname === "/mcp") {
    res.setHeader("Access-Control-Allow-Origin", "*");

    const server = createPoiSearchServer();
    const transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: undefined,  // Stateless mode
      enableJsonResponse: true
    });

    res.on("close", () => {
      transport.close();
      server.close();
    });

    await server.connect(transport);
    await transport.handleRequest(req, res);
    return;
  }

  res.writeHead(404);
  res.end("Not Found");
});

httpServer.listen(PORT, () => {
  console.log(`MCP Server running at http://localhost:${PORT}/mcp`);
});

Understanding the Widget

When a tool returns structuredContent, ChatGPT can render a custom UI embedded directly in the chat interface known as a widget. This is what transforms our app from plain text responses into an interactive map experience.

The widget is loaded in an iframe within ChatGPT. It receives data from the tool via window.openai.toolOutput and can render anything a web page can: maps, charts, forms, or any interactive UI. In our case, the widget (public/widget.html) displays a Mapbox map with place markers and a clickable sidebar.

Since the widget is just HTML/CSS/JavaScript, you have full control over the user experience without requiring any special framework.

Updating the Widget's Data

The data arrives via window.openai.toolOutput and it might not be available immediately when your script runs. We set up an event listener to ensure the widget can updated once the data is received from the API's.

// Traditional app
const places = await fetch('/api/places').then(r => r.json());

// ChatGPT App - data comes from tool output
const places = window.openai?.toolOutput?.places;

// But it might arrive later, so also listen for updates
window.addEventListener("openai:set_globals", (event) => {
  const places = event.detail?.globals?.toolOutput?.places;
  // Re-render with new data
});

Widget structure

<!DOCTYPE html>
<html>
<head>
  <script src="https://api.mapbox.com/mapbox-gl-js/v3.14.0/mapbox-gl.js"></script>
  <link href="https://api.mapbox.com/mapbox-gl-js/v3.14.0/mapbox-gl.css" rel="stylesheet"/>
  <style>
    /* Sidebar + map layout */
    .container { display: flex; height: 100vh; }
    .sidebar { width: 280px; overflow-y: auto; padding: 1rem; }
    .sidebar.hidden { display: none; }
    .map { flex: 1; }
    /* Place cards, markers, etc. */
  </style>
</head>
<body>
  <div class="container">
    <!-- Sidebar starts hidden until results arrive -->
    <div class="sidebar hidden">
      <h2 id="place-count">Places nearby: 0</h2>
      <div id="listings"></div>
    </div>
    <div id="map" class="map"></div>
  </div>

  <script>
    // Get data from ChatGPT tool output
    let places = window.openai?.toolOutput?.places || { type: "FeatureCollection", features: [] };
    let mapCenter = window.openai?.toolOutput?.center || [-77.03915, 38.90025];
    let mapZoom = window.openai?.toolOutput?.zoom || 4;

    // Listen for data updates
    window.addEventListener("openai:set_globals", (event) => {
      const output = event.detail?.globals?.toolOutput;
      if (output?.places) {
        places = output.places;
        mapCenter = output.center ?? mapCenter;
        mapZoom = output.zoom ?? mapZoom;
        // Re-render everything
        clearMarkers();
        addMarkers();
        buildLocationList();
        // Show sidebar now that we have data
        document.querySelector('.sidebar').classList.remove('hidden');
        map.resize();
        map.flyTo({ center: mapCenter, zoom: mapZoom });
      }
    });

    // Standard Mapbox GL JS code
    mapboxgl.accessToken = '{{MAPBOX_ACCESS_TOKEN}}';
    const map = new mapboxgl.Map({
      container: 'map',
      center: mapCenter,
      zoom: mapZoom,
      config: {
        basemap: { theme: 'faded' }
      }
    });

    // Add markers, build listings, handle clicks...
  </script>
</body>
</html>

Testing

1. Start the server

npm start

You should see:

POI Category Search MCP Server
==============================
Server running at: http://localhost:8787
MCP endpoint:      http://localhost:8787/mcp

2. Test with MCP Inspector

npx @modelcontextprotocol/inspector@latest http://localhost:8787/mcp

You should see the tool find_nearby_places and the resource places-widget in the inspector.

This lets you call tools and see responses without ChatGPT.

3. Expose with ngrok

ChatGPT needs a public URL to connect:

ngrok http 8787

Copy the https:// URL.

4. Add to ChatGPT and Test Your App

Go to ChatGPT → Settings → Apps & Connectors → Advanced settings
Enable developer mode
Add a connector with your ngrok URL + /mcp (e.g., https://abc123.ngrok.io/mcp)
Open a new chat, click the connector icon, add your connector
Try: "Find coffee shops near Times Square"

You've now successfully built and integrated your first ChatGPT App!

Additional Resources

Mapbox

Mapbox Location AI Tutorials repository
Mapbox MCP Server
Mapbox Store Locator Tutorial - The original tutorial this builds upon
Mapbox GL JS Documentation - Full guide to the mapping library
Mapbox Geocoding API - Convert addresses to coordinates
Mapbox Search Box API - Search for places by category
Mapbox Access Tokens - Get your API token

OpenAI / ChatGPT Apps

ChatGPT Apps SDK - Complete documentation for building ChatGPT Apps
MCP Inspector - Test your MCP server locally
Connecting Your App to ChatGPT