Module @versatiles/style

This library provides everything you need to build a map style.

This page documents the npm package. Install it and import what you need:

npm i @versatiles/style

import { osm } from '@versatiles/style';
const style = osm({ theme: 'colorful' });

There is a second way to use the library — a prebuilt bundle loaded from a <script> tag, which puts the same functions on a VersaTilesStyle global:

<script src="https://tiles.versatiles.org/assets/lib/versatiles-style/versatiles-style.js"></script>
<script>
  const style = VersaTilesStyle.osm();
</script>

That bundle carries less than this page lists, and it is documented on its own page: see the "versatiles-style.js" module. Everything you build a style with — osm, satellite, guessStyle, inlineSources, Color — is in both. What only npm has is editor and tooling work: osm.minimizeOptions and osm.toCode, the font-discovery helpers, randomColor, isDarkPalette, and the TileJSON validators. Each of those is marked npm only on its own page. They are left out so that a page which merely builds a style and hands it to MapLibre does not download them.

Generate a style for OpenStreetMap data:

osm accepts an OsmOptions object and returns a MapLibre style. It is synchronous and performs no I/O: a *.json source URL becomes a source url that MapLibre resolves when the map loads.

Pass the style through inlineSources before handing it to MapLibre. The VersaTiles TileJSONs list relative tile URLs, which MapLibre does not resolve, and describe MLT tiles, Terrain-RGB elevation and raster tile sizes in fields MapLibre does not read — see inlineSources for what goes wrong without it.

import { osm, inlineSources } from '@versatiles/style';
const style = osm({
  theme: 'colorful',
  urls: { base: 'https://tiles.example.org' },
});

// resolve every source reference into a self-contained style
const standalone = await inlineSources(style);

Available palettes: 'colorful' | 'natural' | 'muted' | 'gray' | 'toner', each also as a dark theme with a -dark suffix ('colorful-dark', …). The lookalike themes ('positrino', 'protocol', 'fnord', …) resemble other projects' maps.

Generate a satellite / raster style:

satellite wraps a raster tile source and optionally adds an OSM vector overlay.

import { satellite } from '@versatiles/style';
const style = satellite({ osmOverlay: { theme: 'toner' } });

Guess a style from a tile source:

guessStyle inspects a tileset and returns the most appropriate style for it. Pass the URL of a TileJSON document, which it downloads, or a TileJSON object you already hold, which it uses without network access. It is the one style function that is asynchronous.

import { guessStyle } from '@versatiles/style';
const style = await guessStyle('https://tiles.example.org/tiles.json');
const fromObject = await guessStyle(tileJSON, { urls: { base: 'https://tiles.example.org' } });