JS 5.5. sun is now light, and hillshade.anchor is light.fixedToScreen. See Migration from v6.

> Upgrading from v5? v6 is a breaking release: the palette builders (colorful, shadow, …) are

replaced by osm({ theme }), options are grouped (textScale → text.scale), all 34 of

the renamed colour keys moved under a group prefix, and both sprite sheets were renamed.

Unknown option keys now throw, and the error names the v6 replacement.

> - Migration from v5 — the full option, colour-key and type tables.

- Migrating sprite ids from v5 — basics → base and markers → extras/icons.

- CHANGELOG — every breaking change in 6.0.0.

Styles Overview

The osm() function renders OpenStreetMap vector tiles using one of five built-in color palettes, each available as a light theme and a dark one (colorful-dark, …). satellite() renders raster/satellite tiles with an optional vector overlay.

| Palette | Light | Dark | | ------------- | :---------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------: | | colorful | | | | natural | | | | muted | | | | gray | | | | toner | | | | satellite | | — |

Lookalike themes

Further themes have a colour scheme that resembles another project's map. They are still VersaTiles styles — the same layers, labels and icons as every other theme, in different colours — which is why they carry names of their own. A lookalike has a dark theme only where the map it resembles has one. It may also draw its borders and paths the way that map does — solid where VersaTiles dashes them, or in another dash.

Lookalike themes are not part of the prebuilt styles.tar.gz; generate them with osm({ theme }).

| Theme | Resembles | Light | Dark | | ------------- | ---------------------- | :---------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------: | | positrino | Positron, Dark Matter | | | | protocol | Protomaps Light, Dark | | | | protostar | Protomaps White, Black | | | | protozoa | Protomaps Grayscale | | — | | fnord | Fiord Color | — | | | classic | OpenStreetMap Carto | | — | | googol | Google Maps | | — | | freedom | OSM Liberty | | — | | macbob | Mapbox Streets | | — | | mactaylor | MapTiler Streets | | — | | bingo | Bing Maps | | — |

Using VersaTiles Styles

Prebuilt Styles and Sprites

Download the assets from the latest release:

• styles.tar.gz: Contains the styles above in multiple languages (the lookalike themes are generated on demand).

• sprites.tar.gz: Includes map icons and other sprites.
• Sprite overview: every icon in all three sheets, with its sprite ID, title and aliases.
• versatiles-style.tar.gz: Contains a JavaScript file to generate styles dynamically in the browser.

Generating Styles On-the-Fly

Frontend Usage (Web Browser)

Download the latest release:

curl -Ls "https://github.com/versatiles-org/versatiles-style/releases/latest/download/versatiles-style.tar.gz" | gzip -d | tar -xf -

Integrate it into your HTML application:

<div id="map"></div>
<script src="maplibre-gl.js"></script>
<script src="versatiles-style.js"></script>
<script>
  (async () => {
    const style = VersaTilesStyle.osm({
      theme: 'colorful-dark',
      text: { language: 'de' },
      recolor: { gamma: 0.5 },
    });
const map = new maplibregl.Map({
      container: 'map',
      style: await VersaTilesStyle.inlineSources(style),
    });
  })();
</script>

inlineSources is required, not optional. osm() and satellite() are synchronous and do no

I/O: they leave each source as a { type, url } reference to a TileJSON and let MapLibre fetch it.

That works only if the TileJSON lists absolute tile URLs — and the VersaTiles ones list relative

templates (/tiles/osm/{z}/{x}/{y}), which MapLibre does not resolve. Handing such a style straight

to new maplibregl.Map() fails with

Request constructor: /tiles/osm/2/2/2 is not a valid URL and no tiles appear.

> inlineSources fetches the TileJSON and folds it in, so the tile URLs come out absolute and the

attribution, bounds and maxzoom it carries are preserved. That last part matters: the attribution

is a licensing obligation.

> It also translates the VersaTiles extensions

to TileJSON, which MapLibre does not read, into the source properties MapLibre does. Without it:

> - MLT tiles (tile_format: application/vnd.maplibre-tile) are decoded as MVT, and the map stays empty.

- Terrain-RGB elevation (tile_schema: dem/mapbox) is decoded as Terrarium, so terrain and hillshade

show wrong heights.

- Raster tiles with tile_size: 256 are drawn at MapLibre's default of 512 px, at the wrong scale.

> You can skip it and stay fully synchronous only if the TileJSON lists absolute tile URLs and uses none

of these extensions.

Everything the bundle provides is listed under versatiles-style.js in the API documentation — that page is generated from the bundle's own entry point, so it is the definitive answer to "is this available in the browser?". The surface is smaller than the npm one on purpose: the authoring helpers (osm.minimizeOptions, osm.toCode, osm.validateOptions), the font-discovery functions, randomColor, isDarkPalette and the TileJSON validators are npm-only, because a page that builds a style and hands it to MapLibre never calls them and would otherwise download them. The shipped versatiles-style.d.ts carries the same list as types.

Requires MapLibre GL JS 5.5 or newer.

The generated styles set the globe projection

and a root sky, which need 5.0, and

features.hillshade writes hillshade-method and hillshade-illumination-altitude, which need 5.5.

A version below 5.5 rejects a style with hillshade, so it fails to load.

> npm users have this checked automatically through an optional peer dependency. Loading MapLibre

from a Chat with me