Forem: Chris Whong

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!

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)

Introducing Appearances: A Simpler Way to Dynamically Style Mapbox Map Icons

Chris Whong — Fri, 28 Nov 2025 12:52:09 +0000

Mapbox maps just got a major usability upgrade with the new appearances functionality, making it easier than ever to change icon images based on user interaction—without the verbose, error-prone workarounds of the past.

This screen capture shows appearances in action, displaying different icons for four distinct feature states:

default icon
feature hovered
feature selected
feature was previously selected

What Are Appearances?

Appearances allow you to define how a symbol layer's icons should change in response to changes in feature state (the ability to set state on specific features on a map). The appearances layer property contains one or more appearance objects defining layout properties like icon-image and the conditions on which to apply them. For example, the following symbol layer defaults to using the image hotel, but includes appearances for 3 additional icons for 3 distinct feature states (currentlySelected, hover, and hasBeenClicked).

{
  id: 'points',
  type: 'symbol',
  source: 'points',
  layout: {
    'icon-allow-overlap': true,
    'icon-image': 'hotel',
    'icon-size': 0.75
  },
  appearances: [
    {
      name: 'clicked',
      condition: [
        'boolean',
        ['feature-state', 'currentlySelected'],
        false
      ],
      properties: {
        'icon-image': 'hotel-active'
      }
    },
    {
      name: 'hovered',
      condition: [
        'boolean', 
        ['feature-state', 'hover'], 
        false
      ],
      properties: {
        'icon-image': 'hotel-hover'
      }
    },
    {
      name: 'has-been-clicked',
      condition: [
        'boolean',
        ['feature-state', 'hasBeenClicked'],
        false
      ],
      properties: {
        'icon-image': 'hotel-clicked'
      }
    }
  ]
}

Appearances make the display logic for different states concise and easy to understand. The map style responds in a predictable way to feature state changes, so your frontend code can focus on managing state, not directly updating the map.

To make use of the appearances defined in the symbol layer above, you just need to set feature state as the user interacts with each marker.

For example, when a feature is hovered, set its hover feature state to true using an interaction:

map.addInteraction('hover-in', {
    type: 'mouseenter',
    target: { layerId: 'points' },
    handler: (e) => {
        map.setFeatureState(e.feature, { hover: true });
        map.getCanvas().style.cursor = 'pointer';
    }
});

On click, the process is similar. The currentlySelected feature state for the clicked feature is set to true:

map.addInteraction('click', {
    type: 'click',
    target: { layerId: 'points' },
    handler: (e) => {
        // deselect the currently selected feature
        if (selectedFeature) {
            map.setFeatureState(selectedFeature, {
                currentlySelected: false
            });
        }
        // set selectedFeature and add to list of clickedFeatures
        selectedFeature = e.feature;
        clickedFeatures.push(e.feature);
        map.setFeatureState(e.feature, {
            currentlySelected: true,
            hasBeenClicked: true
        });
    }
});

You can see the full example outlined above and try it for yourself in the Mapbox docs.

The above example shows frontend implementation for the web using Mapbox GL JS, but the same patterns apply to the Maps SDKs for iOS and Android. See the iOS and Android code examples linked at the bottom of this post.

Zoom-dependent expressions

In addition to using feature state to determine which icon to show, you can also use zoom expressions. The following layer definition uses appearances the icon-size property based on the current zoom:

{
    'id': 'points',
    'type': 'symbol',
    'source': 'points',
    'layout': {
        'icon-allow-overlap': true,
        'icon-image': 'hotel',
        'icon-size': 0.5
    },
    'appearances': [
        {
            'name': 'zoomed-in',
            'condition': ['>=', ['zoom'], 16],
            'properties': {
                'icon-size': 1.2
            }
        },
        {
            'name': 'zoomed-mid',
            'condition': ['>=', ['zoom'], 14],
            'properties': {
                'icon-size': 0.8
            }
        }
    ]
}

The Old Way: Updating feature properties

Before appearances, the only way to achieve per-feature icon changes was to store the icon name in each feature's properties and update the entire GeoJSON source every time a state changed. This approach is verbose and requires a lot of client-side code to track state, update properties, and re-set the data source:

{
    'id': 'points',
    'type': 'symbol',
    'source': 'points',
    'layout': {
        'icon-allow-overlap': true,
        'icon-image': ['get', 'icon'],
        'icon-size': 0.75
    }
}

function setFeatureIcon(id, icon) {
  const source = map.getSource('points');
  const data = getSourceData();
  if (!data) return;
  const feature = data.features.find(f => f.id === id);
  if (feature) {
    feature.properties.icon = icon;
    source.setData(data);
  }
}

This method is not only cumbersome, but it also does not work with vector tiles, since you cannot update the data on a vector tile source. This limitation made dynamic icon styling impossible for symbol layers visualizing a vector source.

Why Appearances Are a Game Changer

Declarative: Define all your icon state logic in one place, right in the layer definition.
No data changes required: No more manual property management or data source updates.
Works with vector tiles: Since appearances are based on feature-state, you can now have dynamic icons on vector tile sources, unlocking new possibilities for large-scale, performant maps.
Cleaner code: Less boilerplate, fewer bugs, and easier to maintain.

Try It Out and Share Feedback!

We invite you to test out the new appearances feature in your projects to make symbol layers that respond to feature state or zoom changes.

Have feedback or ideas? Let us know—your input helps us make Mapbox maps even better!

Additional resources

You can also explore full working examples in the official documentation:

Quickstart: Mapbox in React Native

Chris Whong — Wed, 26 Nov 2025 17:38:22 +0000

This is a condensed version of the full React Native Mapbox tutorial. For advanced features, troubleshooting, and more, check out the full tutorial.

@rnmapbox/maps is a community-maintained react native package that wraps the Mapbox Maps SDKs for iOS and Android, allowing for development of cross-platform mobile mapping apps.

1. Create a New React Native Project

npx @react-native-community/cli@latest init MyMapboxApp
cd MyMapboxApp

2. Install Mapbox Dependencies

npm install @rnmapbox/maps

3. Mapbox Access Token & Platform-specific Setup

Get a token from your Mapbox account.

iOS Setup

Podfile hooks: In your ios/Podfile, add the following inside your app's target block:

   pre_install do |installer|
     $RNMapboxMaps.pre_install(installer)
   end

   post_install do |installer|
     $RNMapboxMaps.post_install(installer)
     # ...other post_install hooks
   end

Install pods:

   cd ios && pod install

Add access token: In ios/{YourProjectName}/Info.plist, add inside <dict>:

   <key>MBXAccessToken</key>
   <string>YOUR_MAPBOX_ACCESS_TOKEN</string>

Android Setup

Add access token: Create android/app/src/main/res/values/mapbox_access_token.xml:

   <resources>
     <string name="mapbox_access_token">YOUR_MAPBOX_ACCESS_TOKEN</string>
   </resources>

Add Mapbox Maven repo: In android/settings.gradle, add:

   dependencyResolutionManagement {
     repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
     repositories {
       google()
       mavenCentral()
       maven { url = uri("https://api.mapbox.com/downloads/v2/releases/maven") }
     }
   }

4. Update `App.tsx` to Show a Map

Replace the contents of App.tsx with:

import React from 'react';
import { MapView, Camera } from '@rnmapbox/maps';

export default function App() {
  return (
    <MapView style={{ flex: 1 }}>
      <Camera
        defaultSettings={{
          zoomLevel: 12,
          centerCoordinate: [-74.006, 40.7128] // New York City
        }}
      />
    </MapView>
  );
}

5. Run Your App

npx react-native run-ios # or run-android

You should see a Mapbox map centered on New York City. From here, you are ready to add your own data to the map, customize the style of the basemap, add interactivity, and more!

For more features (GeoJSON data, basemap configuration, user location, etc.), see the full tutorial.

Adding a Hover Tooltip to a Polygon Layer in Mapbox GL JS

Chris Whong — Thu, 20 Nov 2025 20:00:27 +0000

Hover tooltips are a great way to enhance the UX of your web maps. When the user moves their mouse across a region, district, delivery zone, or any other polygon, the map can talk back — instantly showing what the user is pointing at.

At Mapbox, we just published an updated code example demonstrating this pattern, and it highlights one of the most common UX needs: a lightweight tooltip that follows the cursor and displays the properties of the polygon underneath. If you're designing thematic maps, dashboards, or interactive exploratory tools, this is a pattern worth adding to your toolkit.

Why this pattern matters

A hover-follow tooltip gives users:

Instant context without clicking
A smooth, responsive feel as users move the mouse across boundaries
A clean, focused UI (no permanent labels cluttering the map)
A natural interaction pattern for data-rich polygons

This approach uses a single popup that moves dynamically with the cursor, updating its content with the feature you're hovering.

Key Concepts (with snippet examples)

1. Create a single reusable popup

You don’t want a new popup on every movement — just one that updates.

const popup = new mapboxgl.Popup({
  closeButton: false,
  closeOnClick: false,
  offset: [0, -20]  // keeps tooltip above the cursor
});

Update the popup position + content on mousemove The new example uses map.addInteraction to target a specific polygon layer and update the tooltip as the cursor moves across it.

map.addInteraction('hover-tooltip', {
  type: 'mousemove',
  target: { layerId: 'polygon-fills' },
  handler: (e) => {
    const label = e.feature.properties.name;

    popup
      .setLngLat(e.lngLat)
      .setHTML(`<strong>${label}</strong>`)
      .addTo(map);
  }
});

This keeps the tooltip synced to the cursor while pulling feature properties on demand.

Hide the tooltip on mouseleave A tiny interaction detail that keeps your UI clean:

map.on('mouseleave', 'polygon-fills', () => {
  popup.remove();
});

See the full working example

These snippets illustrate the pattern, but the full example includes a real dataset, layer styling, and the complete interaction flow.

👉 Check out the latest Mapbox GL JS hover tooltip example:

https://docs.mapbox.com/mapbox-gl-js/example/hover-tooltip/

The example shows exactly how this pattern works in a realistic scenario — a polygon dataset that updates the tooltip in real time as you move the mouse pointer across the map.

Explore More UX Patterns

If you're building interactive maps—dashboards, analytics tools, administrative boundaries, or selection-based interfaces—you’ll find more great patterns across the Mapbox GL JS example gallery.

👉 Browse all Mapbox GL JS examples

https://docs.mapbox.com/mapbox-gl-js/examples/

These examples are excellent starting points for designing modern, intuitive map interactions to make your web maps sing!

Mapbox Developer Tutorials help you start building quickly

Chris Whong — Wed, 19 Nov 2025 16:25:17 +0000

At Mapbox, we’ve been shipping a ton of new developer tutorials to help you get started and level up as you integrate our maps and location services into your web and mobile apps.

But first:

🔥 We launched a brand-new step-by-step tutorial UI.

It’s cleaner, more focused, and way easier to follow as you move through code, concepts, and hands-on tasks.

Below is the full list of new and refreshed tutorials — grouped by platform so you can jump right into the stack you’re working with.

🕸️ Web Tutorials

React, Angular, Vue & GL JS

Dynamic Markers & Popups in React

https://docs.mapbox.com/help/tutorials/dynamic-markers-react/
POI Search in React (Search Box API)

https://docs.mapbox.com/help/tutorials/poi-search-react/
Toggle Layers with Checkboxes (React)

https://docs.mapbox.com/help/tutorials/react-toggle-layers/
Store Locator with React + GL JS

https://docs.mapbox.com/help/tutorials/building-a-store-locator-react/
Store Locator with Vanilla JavaScript

https://docs.mapbox.com/help/tutorials/building-a-store-locator/
GL JS in an Angular App

https://docs.mapbox.com/help/tutorials/use-mapbox-gl-js-with-angular/
GL JS in a Vue App (rewrite)

https://docs.mapbox.com/help/tutorials/use-mapbox-gl-js-with-vue/

📱 Mobile Tutorials

iOS

Turn-by-Turn Navigation

https://docs.mapbox.com/help/tutorials/ios-navigation/
Geofencing

https://docs.mapbox.com/help/tutorials/ios-geofencing/
Marker App from a Custom Style + Tileset

https://docs.mapbox.com/help/tutorials/ios-marker-app-custom-style/?step=3
Interactions

https://docs.mapbox.com/help/tutorials/ios-interactions/
Location Search (Search SDK)

https://docs.mapbox.com/help/tutorials/ios-location-search/
Offline Maps (iOS)

https://docs.mapbox.com/help/tutorials/ios-offline-maps/

Android

Geofencing

https://docs.mapbox.com/help/tutorials/android-geofencing/
Marker App from GeoJSON

https://docs.mapbox.com/help/tutorials/android-markers-from-geojson/
Interactions

https://docs.mapbox.com/help/tutorials/android-interactions/
Location Search (Search SDK)

https://docs.mapbox.com/help/tutorials/android-location-search/
Offline Maps (Android)

https://docs.mapbox.com/help/tutorials/android-offline-maps/

🗺️ Mapbox Studio Tutorials

Create a Custom Map Style (rewrite)

https://docs.mapbox.com/help/tutorials/create-a-custom-style/
Add & Style Data in Studio

https://docs.mapbox.com/help/tutorials/add-data-to-mapbox-style

🧱 Data Processing & MTS (Mapbox Tiling Service)

Cluster Point Data with MTS

https://docs.mapbox.com/help/tutorials/cluster-point-data-with-mts/
Incremental Update with MTS

https://docs.mapbox.com/help/tutorials/mts-incremental-updates/

🤖 Build AI Agents with Mapbox

The Mapbox MCP Server provides helpful skills for LLM to work with powered by Mapbox web services APIs. For example, you can retrieve directions, generate isochrones, or create static maps from your AI agent app.

Build Your Own Agent with the Mapbox MCP Server https://docs.mapbox.com/help/tutorials/build-your-own-agent/

💬 What Should We Build Next?

We want to know: What’s missing?

Is there a tutorial you wish existed? A concept that felt tricky the first time you built with Mapbox? Something you'd love to see broken down step-by-step?

Drop your ideas in the comments — I read every one, and your feedback shapes what we create next.

Let’s keep making location tech fun, powerful, and developer-friendly.

Forem: Chris Whong

A GUI editor for Mapbox Color Themes

The Mapbox Standard Style

What Exactly Is a LUT?

Where Do LUTs Come From?

Download one

Build one in Photoshop

Build one in the browser

The Challenge: Iterating on Custom Themes in a Mapbox Map

Introducing the Mapbox GL Theme Editor

Global controls

Targeted color corrections

Using Your Theme

In Mapbox Studio

In the Standard Style Playground

In your frontend code

Why Build a Custom Tool?

What's Next?

Give It a Try

How Lemontree improved map performance with a small refactor

Takeaways

Squarespace X Mapbox

How to Add an Interactive Mapbox Map to Your Squarespace Website

Prerequisites

Getting Your Mapbox Access Token

Step 1: Adding the Code Block

Step 2: Add Mapbox GL JS Code

Understanding the Code Structure

Resources for Mapbox GL JS Development

Troubleshooting

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

The Challenge

The Solution

Key Implementation Details

Performance Benefits

Cross-Platform Compatibility

Wix X Mapbox

How to Add an Interactive Mapbox Map to Your Wix Website

Prerequisites

Getting Your Mapbox Access Token

How Wix Embeds Work

Step 1: Adding the Embed Element

Step 2: Add Mapbox GL JS Code

Understanding the Code Structure

Resources for Mapbox GL JS Development

Troubleshooting

Server-rendered Maps for Web and Mobile

A Developer's Guide to the Mapbox Static Images API

What Is the Static Images API?

Adding Your Data with Overlays

Three Real-World Use Cases

Use the Developer Playground to get started

When to Choose Static Maps

Gradio X Mapbox

Introducing Appearances: A Simpler Way to Dynamically Style Mapbox Map Icons

What Are Appearances?

Zoom-dependent expressions

The Old Way: Updating feature properties

Why Appearances Are a Game Changer

Try It Out and Share Feedback!

Additional resources

Quickstart: Mapbox in React Native

1. Create a New React Native Project

2. Install Mapbox Dependencies

3. Mapbox Access Token & Platform-specific Setup

iOS Setup

Android Setup

4. Update App.tsx to Show a Map

5. Run Your App

Adding a Hover Tooltip to a Polygon Layer in Mapbox GL JS

Why this pattern matters

Key Concepts (with snippet examples)

1. Create a single reusable popup

See the full working example

👉 Check out the latest Mapbox GL JS hover tooltip example:

Explore More UX Patterns

👉 Browse all Mapbox GL JS examples

Mapbox Developer Tutorials help you start building quickly

🕸️ Web Tutorials

React, Angular, Vue & GL JS

4. Update `App.tsx` to Show a Map