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, 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.

Call inlineSources afterwards when the style has to stand on its own — a published style.json, an offline deployment, or anywhere the first tile request should not wait for a TileJSON round-trip.

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

// optional: 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', …).

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' } });