How to Create a Custom Map Style with MapLibre GL

What a Map Style Actually Is

MapLibre GL renders vector tiles in the browser. What the map looks like is decided entirely by the MapLibre style specification, a JSON document with four important parts:

• sources: where the vector tiles come from (a TileJSON URL or a tile template).
• layers: an ordered list of paint rules. Water is a fill layer, roads are line layers, place names are symbol layers. Order matters: later layers draw on top.
• glyphs: where the font PBF ranges live, used by all text labels.
• sprite: one image atlas with all the small icons (optional but needed for POI icons).

A realistic basemap has around 70 layers. Writing them by hand is possible with a visual editor like Maputnik, but maintaining 70 handwritten layers across data updates is painful. There is a better way.

The Fast Path: Protomaps Flavors

The @protomaps/basemaps package generates the whole layer list from a compact color object called a flavor. Five named flavors ship out of the box: light, dark, white, grayscale and black.

npm install @protomaps/basemaps

import { layers, namedFlavor } from "@protomaps/basemaps";

const style = {
  version: 8,
  sources: {
    protomaps: {
      type: "vector",
      url: "https://tiles.hititmedya.com/planet.json",
      attribution: "Protomaps © OpenStreetMap"
    }
  },
  layers: layers("protomaps", namedFlavor("light"), { lang: "en" }),
  glyphs: "https://tiles.hititmedya.com/v1/fonts/{fontstack}/{range}.pbf",
  sprite: "https://tiles.hititmedya.com/v1/sprites/v4/light"
};

That is a complete, production-ready basemap style. The interesting part is what comes next.

Making It Yours: a Brand Flavor

A flavor is a plain object where every key is a map feature and every value is a color: water, parks, buildings, road casings, label colors and so on. To brand the map, spread a named flavor and override only what you need:

import { layers, namedFlavor } from "@protomaps/basemaps";

const brandFlavor = {
  ...namedFlavor("light"),
  earth: "#eef1ee",
  water: "#b7dcd2",
  park_b: "#a8dcbd",
  buildings: "#d9ded9",
  highway_casing_early: "#a7d9c4",
  city_label: "#1f2937",
  boundaries: "#8aa397"
};

const brandLayers = layers("protomaps", brandFlavor, { lang: "en" });

Three practical rules we follow when we design flavors at Hitit Medya:

Special Variants Worth Building

Once the build script exists, extra variants are nearly free and very useful:

• No labels: filter out all symbol layers. Perfect when you draw your own annotations on top.
• Labels only: generate with the labelsOnly option and you get a transparent overlay you can stack above custom data layers.
• Localized labels: pass a different lang value (for example tr) to render place names in another language.

// no labels
const noLabels = layers("protomaps", brandFlavor, { lang: "en" })
  .filter((layer) => layer.type !== "symbol");

// transparent label overlay
const labelsOnly = layers("protomaps", brandFlavor, {
  lang: "en",
  labelsOnly: true
});

Hosting and Using the Style

The output is a static JSON file. Put it on any static host or object storage with CORS enabled, and any MapLibre GL app can use it directly:

const map = new maplibregl.Map({
  container: "map",
  style: "https://tiles.hititmedya.com/v1/styles/hitit-green.json",
  center: [32.85, 39.93],
  zoom: 6
});

If you do not want to design your own flavor yet, we publish a gallery of ready-made branded styles with live previews, embed codes and copyable style URLs. Every style is free, with no API key and no request limits.

Frequently Asked Questions

Sources and References