json-maps

Basemap

The basemap field controls the map's background style. It accepts a preset name or a custom style URL.

Presets

Three built-in basemaps are available, all served free by CARTO (no API key needed):

  • light — clean, minimal light theme (CARTO Positron)
  • dark — dark background with light labels (CARTO Dark Matter)
  • streets — colorful with road detail (CARTO Voyager)
{ "basemap": "light" }

If basemap is omitted, it defaults to light.

Custom Style URL

You can pass any MapLibre-compatible style URL:

{ "basemap": "https://your-server.com/style.json" }

The URL must point to a valid MapLibre Style Specification JSON document.

How It Works

Basemap changes call map.setStyle() on the MapLibre instance. The map re-renders with the new style while preserving the current viewport.

// From lib/spec.ts
export const BASEMAP_STYLES: Record<string, string> = {
  light: "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json",
  dark: "https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json",
  streets: "https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json",
};

Examples

Dark theme:

{ "basemap": "dark" }

Streets with viewport:

{
  "basemap": "streets",
  "center": [2.35, 48.86],
  "zoom": 13
}