Styles & Sprites

Geog provides four hosted map styles and matching sprite sheets, ready to use with MapLibre GL JS and MapLibre Native. All assets are served from a global CDN.

Hosted Styles

Each style is a complete MapLibre style JSON with 109 layers, vector tile sources pointing to api.geog.dev, and glyphs hosted at assets.geog.dev/fonts/.

Usage

Set the style URL in your MapLibre configuration. Authentication is still required via transformRequest since the style's tile sources point to the authenticated API:

const map = new maplibregl.Map({
  container: "map",
  style: "https://assets.geog.dev/styles/v0/light.json",
  transformRequest: (url) => {
    if (url.startsWith("https://api.geog.dev")) {
      return {
        url,
        headers: { Authorization: `Bearer ${accessToken}` },
      };
    }
  },
});

Switching Themes

Swap the path segment to change themes — no other configuration changes needed:

// Light theme
style: "https://assets.geog.dev/styles/v0/light.json"

// Dark theme
style: "https://assets.geog.dev/styles/v0/dark.json"

// Gray theme
style: "https://assets.geog.dev/styles/v0/gray.json"

// Warm theme
style: "https://assets.geog.dev/styles/v0/warm.json"

Hosted Sprites

Sprite sheets provide 571 map icons (POI markers, road shields, patterns, etc.) in four theme-matched variants. Each variant includes standard and high-DPI (@2x) assets.

URL pattern:

https://assets.geog.dev/sprites/v0/{theme}

MapLibre automatically appends .json and .png (or @2x.json and @2x.png for retina displays).

The hosted styles already include the matching sprite URL, so no manual configuration is needed when using a hosted style. If you're building a custom style, set the sprite property:

{
  "version": 8,
  "sprite": "https://assets.geog.dev/sprites/v0/light",
  "sources": { ... },
  "layers": [ ... ]
}

npm Packages

For advanced use cases like custom styles or self-hosted sprites, two npm packages are available.

@geogdev/styles

Provides layer definitions as a function, letting you build custom MapLibre styles programmatically.

npm install @geogdev/styles

import { layers, LIGHT, DARK, GRAY, WARM } from "@geogdev/styles";

// Generate layers for a specific theme
const mapLayers = layers("geog", LIGHT);

// Use in a custom MapLibre style
const style = {
  version: 8,
  sources: {
    geog: {
      type: "vector",
      tiles: ["https://api.geog.dev/v1/tiles/basemap/{z}/{x}/{y}.mvt"],
      maxzoom: 14,
    },
  },
  layers: mapLayers,
};

The layers(source, style, options?) function accepts:

• source — name of the vector tile source in your style
• style — theme constant (LIGHT, DARK, GRAY, or WARM)
• options — optional overrides (e.g., custom colors)

@geogdev/sprites

Generates sprite sheets from source SVGs for self-hosted deployments.

npm install @geogdev/sprites

This package is primarily useful if you need to host sprites on your own infrastructure or customize the icon set.

See Also

• Vector Tiles API — Tile endpoint reference
• Examples Overview — Working integration examples