Map Style Converter

Convert between Mapbox style JSON and simplified style schemas

Import & Export

Input Style

Input Format

Input

Output Style

Mapbox GL Style

Converted style will appear here

Format Reference

GeoJSON: Simple styling properties embedded in features

Mapbox GL: Layer-based styling with paint/layout properties

Leaflet: PathOptions object with color, weight, opacity

OpenLayers: Style objects with stroke and fill components

CSS: CSS custom properties for use in stylesheets

What Is a Map Style Converter?

A map style converter translates between different map styling formats so a single design can be reused across rendering libraries and tools. The most common scenario is converting between full Mapbox style JSON (the rich, expression-based spec used by Mapbox GL JS and MapLibre GL JS) and a simplified style schema that's easier to edit, version, or apply to non-Mapbox renderers like Leaflet, OpenLayers, or D3. The Map Style Converter on gis.tools is a free, browser-based tool for that round trip: paste in a Mapbox style, get a simplified version out, and vice versa.

Map styling is one of the harder parts of modern web cartography. The Mapbox Style Specification is powerful but verbose, with hundreds of layer types, paint properties, layout properties, expressions, and filters. Translating between styling languages is rarely a clean one-to-one mapping; the converter makes the trade-offs visible and documents what was preserved and what was lost.

How Style Conversion Works

The converter parses the input style as JSON, walks the layer list, and produces an equivalent representation in the target schema. Common visual properties like fill colour, line width, opacity, and stroke transfer cleanly. Expression-based properties (data-driven styling, zoom-dependent values) are preserved when the target schema supports them and approximated otherwise.

For each layer, the converter identifies:

The geometry type (point, line, polygon, raster, hillshade)
The data source (the source layer and any filters)
The visual properties (paint and layout)
Any expressions or interpolations

It then maps each of these to the target schema, flagging anything that couldn't be translated faithfully.

Mapbox to Simplified Schema

From Mapbox style JSON to a simplified schema, the converter strips less common properties (e.g., tile-aware label collisions) and flattens expressions to constants where possible. The output is easier to edit by hand and works with renderers that don't support the full Mapbox spec.

Simplified to Mapbox

Going the other way, the converter expands shorthand properties to their full Mapbox equivalents and wraps simple values in expressions where the spec requires.

Practical Applications

Style Migration

A team moving from Leaflet to MapLibre GL JS needs to translate their existing Leaflet style into a Mapbox-compatible format. The converter is the starting point.

Cross-Tool Editing

Designers using a simplified visual editor can author styles in plain JSON and convert to full Mapbox style JSON for production deployment.

Style Backup and Versioning

Keeping styles in a simplified format makes them easier to diff in Git and review in pull requests.

Educational Use

Students learning about map styling can compare the verbose Mapbox spec with a simplified equivalent to understand the underlying concepts.

Custom Renderers

Developers building custom map renderers benefit from a simplified style schema they can implement without supporting the entire Mapbox spec.

Style Documentation

A simplified version of a complex Mapbox style is easier to include in documentation and design systems.

Theme Variants

Maintaining a light, dark, and high-contrast variant of a style is easier when the canonical version is the simplified schema.

Step-by-Step Workflow in gis.tools

Open the Map Style Converter page.
Paste your Mapbox style JSON (or simplified schema) into the input area.
Choose the target format from the dropdown.
Click Convert — the tool reports any properties that couldn't be translated.
Inspect the converted output side by side with the original.
Copy the output to your clipboard or download as a JSON file.
Test the converted style in your map renderer.

Worked Example

A cartographer has a Mapbox style JSON for an editorial map with 18 layers, custom expressions, and zoom-dependent line widths. She wants a simplified version she can share with stakeholders for review. She pastes the style in, converts to the simplified schema, and reviews the warnings: two layers used an expression that flattened to its zoom-7 value, and one used a property the simplified schema doesn't support. With those caveats noted in the design doc, she sends the cleaner JSON for review, then converts back to the full Mapbox spec when reviewers approve the changes.

Common Pitfalls and Gotchas

Expression flattening — Complex Mapbox expressions don't always have a simplified equivalent and may be replaced with constants.
Sprite and glyph references — These are external resources; the converter preserves the URLs but doesn't fetch them.
Source URL changes — Tile source URLs may need updating when migrating between hosting providers.
Filter syntax differences — Mapbox supports both legacy filter arrays and modern expression filters; converters may not handle both correctly.
Custom property naming — Layer IDs and property names are case-sensitive; mismatches break styling silently.
Version drift — Mapbox style spec versions 7, 8, and beyond have differences; the converter targets v8 by default.
Unsupported layer types — Heatmap, hillshade, and 3D layers may have no simplified equivalent.

Tips for Best Results

Always review the conversion warnings before deploying the result.
Test the converted style in the target renderer to catch silent issues.
For complex styles, convert layer by layer instead of all at once.
Keep the original style as a backup.
Pair with the Vector Tile Packager when developing styles against test data.
Use the PMTiles/MBTiles Inspector to confirm layer names and schemas match.
Document the source spec version of any converted style.

Comparison with Other GIS Approaches

Mapbox Studio and Mapbox's style-spec library are the canonical authoring tools for full Mapbox styles. MapLibre Studio is a community-maintained open-source alternative. There's no widely adopted simplified style schema, though several projects have proposed one. The browser-based gis.tools converter occupies a niche where you need to translate between schemas without locking into a specific authoring tool.

Performance Considerations

Style conversion is fast — even a 200-layer style converts in a fraction of a second. The bottleneck is usually the human review of the output.

Data Privacy and Browser-Based Processing

The converter runs entirely in your browser tab. Style JSON often contains tile source URLs and Mapbox access tokens; keeping the conversion local means those tokens never leave your machine.

Related GIS Concepts

Mapbox Style Specification — The JSON schema defining how Mapbox GL renders maps. Now also implemented by MapLibre GL.

Expression Language — Mapbox's mini DSL for data-driven styling, including conditionals, interpolation, and arithmetic.

Source Layer — Within a vector tileset, the named layer a styling rule applies to.

Style URL — A reference to a hosted style file, used by Mapbox GL JS as the entry point to a map.

Frequently Asked Questions

Can I convert my Mapbox style to Leaflet?

The converter produces a simplified schema that can be implemented in Leaflet, but a direct Leaflet style format doesn't exist. You'll need to write a small adapter.