/maplibre-tile-sources

name: maplibre-tile-sources
description: Choosing what form your data needs for MapLibre GL JS — GeoJSON read straight from a file versus vector or raster tiles, the feature-count and file-size thresholds where each stops working, and how a basemap and your own data combine as separate sources. Use when deciding which source type a dataset needs, not when hosting or configuring one.
status: verified

MapLibre Tile Sources

MapLibre GL JS does not ship with map data. You provide a **style** that references **sources** — URLs or inline data that MapLibre fetches and renders. MapLibre works equally well for a store locator with 200 addresses, a city transit map, and a global basemap — the right source type depends on geographic scale and level of detail, update frequency, infrastructure constraints, and use case.

This skill is about **choosing** that source type. For getting a configured source to render see [maplibre-source-wiring](../maplibre-source-wiring/SKILL.md).

When to Use This Skill

• Setting up a new MapLibre map and choosing where your data comes from
• Deciding between GeoJSON and tiles for a dataset of a given size
• Working out whether you need tile infrastructure at all
• Planning how a basemap and your own data fit together

How styles and sources work

A **style** (a style JSON, style document, or style object) is the configuration you pass to MapLibre. It contains the specific rendering rules governed by the [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/), maintained with parity for MapLibre GL JS and MapLibre Native.

You can use a **style URL** from a provider — that URL references a style with sources, layers, glyphs, and sprite. Or you can **build your own style** and configure each yourself.

A style has three main components:

• **Sources** — Point to the actual data. Each source has a `type` and either inline data or a URL. MapLibre requests tiles or data as the viewport changes. The same source can back many layers (e.g. roads, water, and labels all from one vector URL).
• **Layers** — An ordered list defining what to draw and how. Each layer references a source (and for vector tiles, a `source-layer` name) and specifies paint/layout properties.
• **Glyphs and sprite** — URLs to font SDF stacks and icon spritesheets. `sprite` has no fallback: a missing icon is silently omitted. `glyphs` does have one on GL JS ≥ 5.11.0 (text still renders, in a local/system font) — see [maplibre-fonts-glyphs](../maplibre-fonts-glyphs/SKILL.md) for the mechanism and its limits. Production styles should still supply both explicitly.

**Source types:**

| Type | Description | | ------------ | -------------------------------------------------------------------------------------------------------- | | `vector` | Vector tiles — binary-encoded geometry and attributes; the primary format for basemaps and data overlays | | `raster` | Raster tile imagery — satellite photos, WMS/WMTS layers | | `raster-dem` | Elevation tiles — for terrain rendering and hillshading | | `geojson` | GeoJSON data — inline object or URL; no tile server needed | | `image` | A single georeferenced image — scanned maps, annotated overlays | | `video` | Georeferenced video |

`vector` and `raster` are the most common for basemaps and data overlays. `geojson` is ideal for small datasets or interactive data that doesn't need tiling. `raster-dem` is used for terrain and hillshade effects, as well as emerging use cases in scientific visualization. `image` and `video` sources are the least common, but let you georeference static images (such as a scanned map, chart, or overlay) or georeferenced videos as map layers.

GeoJSON and Direct Data Sources

For many use cases you don't need a tile service. MapLibre can render points, lines, or polygons directly from an inline GeoJSON object or a URL to a GeoJSON file. The entire dataset is downloaded and parsed in the browser; MapLibre handles rendering client-side.

map.addSource('my-data', {
  type: 'geojson',
  data: '/path/to/data.geojson' // or an inline GeoJSON object
});
map.addLayer({
  id: 'my-layer',
  type: 'fill',
  source: 'my-data',
  paint: { 'fill-color': '#0080ff', 'fill-opacity': 0.5 }
});

GeoJSON performance thresholds

GeoJSON downloads the entire file on every load. This works well at small scale and degrades predictably:

| Range | File size / feature count | Behavior | | ---------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------- | | Sweet spot | < 2 MB / < 5,000 features | Instantaneous loading, smooth interaction | | Lag zone | 5–20 MB / up to ~50,000 features | 1–3s parse delay; mobile may struggle; optimize by simplifying geometries and reducing coordinate precision | | Crash zone | > 50 MB / > 100,000 features | High risk of browser freeze or crash; switch to vector tiles |

GeoJSON is **lossless** (exact coordinates preserved) and gives you full client-side access to feature properties — ideal for interactive data, dynamic updates, and datasets where you need to query or modify features without a server round-trip.

If your dataset exceeds these thresholds, or if you need zoom-dependent rendering (less detail at lower zoom levels), consider vector tiles instead.

Other