Introducing a browser-based prototype tool for iterating on custom Mapbox Standard Style themes in real time — no terminal required.
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
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.
Top comments (1)
Wow! I lik it!