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

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

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"