Basemap Flavors

These examples use the preferred MapLibre GL JS library.

The Flavor TypeScript interface is the preferred way to customize the basemap style. See the shape of the interface at the @protomaps/basemaps TypeScript docs.

A Flavor is a plain object of color definitions and optional properties such as font names, landcover shades and POI properties. You can define a Flavor yourself for a custom style, similar to a text editor color scheme, or use one of the default named flavors as a base.

Default Flavors

These flavors are included as part of the @protomaps/basemaps package.

light

A general-purpose basemap with icons.

dark

A general-purpose basemap with icons.

white

A flavor for data visualization.

grayscale

A flavor for data visualization.

black

A flavor for data visualization.

Overriding Defaults

Use ES6 spread syntax to override any part of the Flavor object. For example, to color buildings red:

import { namedFlavor } from "@protomaps/basemaps"
let flavor = {...namedFlavor("light"),buildings:"red"}

Sprites

Default Sprites

Each of the five default Flavors has an associated spritesheet. Sprites are necessary for displaying:

• Townspots - circles for cities and named places at low zoom levels.
• Highway shields - Shields are localized for different countries and road classes. See shields.
• Points of interest - used for the light and dark flavors only.

Spritesheets are designed according to the MapLibre Sprite specification. Because these sprites are stored in a static PNG image, the colors are pre-rendered to match the associated basemap Flavor.

A spritesheet can be generated by building the program in basemaps/sprites:

cargo build # creates the binary target/release/spritegen
make # builds all 5 default flavor spritesheets in dist/
# Create a new JSON in flavors/custom.json and customize the colors...
./target/release/spritegen refill.svg flavors/custom.json dist/custom

Custom Sprites

A custom spritesheet (custom.json, custom.png, custom@2x.json, custom@2x.png) can be referenced from a MapLibre JSON style:

sprite: "https://example.com/assets/custom"

Sprites can be replaced with custom sets by assigning new icons to the same sprite names. Sprite names can be found in light.json:

townspot
capital
arrow
generic_shield-1char
...

To generate a spritesheet with a sigle icon based on the CC0 Maki icon set created by Mapbox, use the spreet command line tool:

mv airport.svg icons/aerodrome.svg
spreet icons output
# creates output.json and output.png
spreet --retina icons output@2x
#creates output@2x.json and output@2x.png, used on HiDPI displays