Skip to content
Navara

Vector Tile Source

A vector-tile source describes a Mapbox Vector Tiles (MVT) tileset. Render it with a vector layer. Which source layers inside the tileset to render is chosen per layer via the layer’s sourceLayers property.

The url accepts two forms:

  • Tile templates — a URL containing {z}/{x}/{y} placeholders, where each tile is fetched individually.
  • PMTiles archives — a single URL ending in .pmtiles, where all tiles live in one file served over HTTP range requests. See PMTiles Archives below.

Both forms produce the same source; the engine picks the right implementation automatically based on the URL.

Properties

Section titled “Properties”
PropertyTypeDefaultDescription
type"vector-tile"(required)Source type.
urlstring(required)Tile URL — either a {z}/{x}/{y} template or a .pmtiles archive URL.
maxZoomnumber20Maximum zoom level new tiles are requested for.
overscaledMaxZoomnumber24Maximum zoom overscaled (stretched-parent) tiles are used up to.
maxSsenumber2.0Maximum screen-space error driving tile traversal.
crsstring—Coordinate reference system of the tiles.

Source sharing

Section titled “Source sharing”

Multiple vector layers can reference one vector-tile source; the tile data and traversal are shared, and each layer styles its own sourceLayers.

import ThreeView, { Color } from "@navaramap/three";


const tiles = view.addSource({
  type: "vector-tile",
  url: "https://example.com/{z}/{x}/{y}.pbf",
  maxZoom: 16,
});


view.addLayer({
  type: "vector",
  source: tiles,
  sourceLayers: ["waterarea"],
  polygon: { color: new Color().setStyle("#00aaff"), clampToGround: true },
});


view.addLayer({
  type: "vector",
  source: tiles,
  sourceLayers: ["building"],
  polygon: { color: new Color().setStyle("#555555") },
});

PMTiles Archives

Section titled “PMTiles Archives”

A PMTiles archive packs an entire tile pyramid into a single file. Instead of one HTTP request per tile, the engine reads the archive’s header and directory once, then fetches individual tiles with HTTP range requests. Only archives whose payload is MVT are supported.

To use one, point the source url at the archive. The URL has no {z}/{x}/{y} placeholders and ends in .pmtiles; the engine selects the archive source implementation automatically:

import ThreeView, { Color } from "@navaramap/three";


// Credit: © OpenStreetMap contributors, © Protomaps (https://protomaps.com)
const PMTILES_URL =
  "https://pmtiles.io/protomaps(vector)ODbL_firenze.pmtiles";


const firenze = view.addSource({
  type: "vector-tile",
  url: PMTILES_URL,
  maxZoom: 15,
});


view.addLayer({
  type: "vector",
  source: firenze,
  sourceLayers: ["water"],
  polygon: { color: new Color().setStyle("#4a90d9"), clampToGround: true },
});

Everything else is identical to a templated vector-tile source — the same materials apply, sourceLayers selects which vector layers to style, and multiple vector layers referencing the same source share one archive (a single header/directory fetch and a shared tile cache):

const firenze = view.addSource({
  type: "vector-tile",
  url: PMTILES_URL,
  maxZoom: 15,
});


// Base land fill.
view.addLayer({
  type: "vector",
  source: firenze,
  sourceLayers: ["earth"],
  polygon: { color: new Color().setStyle("#d0bf70"), clampToGround: true },
});


// Roads drape on top — same archive, resolved once.
view.addLayer({
  type: "vector",
  source: firenze,
  sourceLayers: ["roads"],
  polyline: {
    show: true,
    color: new Color().setStyle("#278b8c"),
    width: 6,
    height: 1,
    clampToGround: true,
  },
});
Section titled “Related Resources”