Map

The map. One instance owns a DOM container, a camera, an optional style document and the layers and controls added to it. Everything on this page is a method or event of Map; the layers it holds are in Layers.

Before 0.5 the class was called TsMap. That name still works, as a deprecated alias of Map.

import { Map, styles } from 'ts-maps'
import 'ts-maps/styles.css'

const map = new Map('map', {
  center: [40.758, -73.9855], // [lat, lng]
  zoom: 14,
  style: styles.light({ url: 'https://tiles.openfreemap.org/planet' }),
})

Coordinates are [lat, lng] throughout the map's own API, as in Leaflet. Anywhere a point is taken, a LatLng, a [lat, lng] pair or a { lat, lng } object will do. GeoJSON and the style spec keep their [lng, lat] order.

Creating a map

The view is set at construction only when both center and zoom are given. Without them the map is empty until the first setView or fitBounds. Before then, getCenter() — and so flyTo, easeTo and jumpTo — throws Set map center and zoom first.

Options

View

Style and look

Interaction

Each of these is also a handler on the map, with enable() and disable(): map.dragging.disable().

Animation

Controls

Camera

Moving

map.flyTo([51.5074, -0.1278], 13, { bearing: 30, pitch: 50 })
map.easeTo({ zoom: 16, bearing: 90, pitch: 60, duration: 1200 })
map.jumpTo({ center: [48.8566, 2.3522], zoom: 14 })
map.fitBounds([[40.70, -74.02], [40.80, -73.93]], { padding: [40, 40] })

Options:

• flyTo(center, zoom, { bearing?, pitch?, duration?, animate?, essential? }). duration is in milliseconds; left out, it follows the distance flown.
• easeTo({ center?, zoom?, bearing?, pitch?, duration?, easing?, essential?, noMoveStart? }). duration defaults to 300 ms. Bearing turns the short way round.
• setView, panTo and panBy take Leaflet's options: animate, and duration in seconds (default 0.25), unlike flyTo and easeTo.
• fitBounds and flyToBounds take padding as a [x, y] pair (not a single number), or paddingTopLeft and paddingBottomRight, and maxZoom. fitBounds also takes setView's animate.
• When the reader has asked the system for reduced motion, flyTo and easeTo arrive without animating, unless the call says essential: true.

Starting a camera move cancels the one running.

Limits

Reading

Style

The map can hold one style document: sources, and style layers that draw them, as in the Mapbox GL Style Spec. Leaflet-style layers (Marker, TileLayer, …) sit alongside it and are added with addLayer — see Layers and controls.

map.on('style.load', () => {
  map.addSource('parks', { type: 'geojson', data: '/parks.geojson' })
  map.addStyleLayer({
    id: 'parks',
    type: 'fill',
    source: 'parks',
    paint: { 'fill-color': '#16a34a', 'fill-opacity': 0.3 },
  })
})

map.setPaintProperty('parks', 'fill-opacity', 0.6)
map.setFilter('parks', ['>', ['get', 'area'], 10000])

Sources. vector (a tiles template, a TileJSON url, or a pmtiles:// archive), raster, raster-dem and geojson. A geojson source takes data as an object or a URL, and cluster, clusterRadius (default 50), clusterMaxZoom (16) and clusterMinPoints (2); clusters carry point_count for expressions. image and video sources are not supported: use ImageOverlay and VideoOverlay.

Layers. background, fill, fill-extrusion, line, circle, symbol, raster, hillshade and heatmap.

A raster source is drawn only through raster layers that use it. With none, it draws nothing. The layer's minzoom, maxzoom and visibility decide when it shows, and outside them its tiles are not fetched. raster-opacity is applied, and can change with the zoom. raster-brightness-min, raster-brightness-max, raster-contrast, raster-saturation and raster-hue-rotate become a CSS filter on the layer, close to Mapbox's but not the same. If several raster layers use one source, the first one that shows at the current zoom is drawn.

Loading. A style given as a URL is fetched; one whose sources name a TileJSON url has those read first. Either way setStyle returns at once and the style goes in when they arrive. Sources and layers added in the meantime are put on it then.

addSource reads a TileJSON url too, for vector, raster and raster-dem sources. The source is in the style at once, with its url, and layers can be added for it straight away; it draws once the TileJSON is in, with tiles, minzoom, maxzoom, attribution, bounds and encoding filled in from it. What the source says itself wins. The map fires sourcedata with sourceId when it is ready, or error with sourceId if the TileJSON cannot be read. A pmtiles:// URL is read in place, as before.

When both the old and the new style are in place, setStyle applies the difference rather than rebuilding, so swapping a light basemap for a dark one keeps the tiles it has.

style.load fires each time a style goes in, a microtask after setStyle puts it in place — so a listener added on the line after the constructor hears it, even for a style with nothing to fetch. If two styles are set in quick succession, it fires for the one that won. isStyleLoaded() is already true by then.

Setting a new style replaces the old one's sources and layers. Add your own again on style.load.

Querying features

The first argument is a point or a box, in container pixels: a Point, { x, y } or [x, y], or a box as [[x1, y1], [x2, y2]]. A box returns the features that touch it. Options go second, or on their own as the only argument: layers, a list of style layer ids, and filter, an expression the features must also pass. The options may carry the geometry themselves, as point or bbox. With no point and no box, every feature in the loaded tiles that passes the filters is returned.

map.queryRenderedFeatures([[0, 0], [200, 100]], { layers: ['poi'] })
map.queryRenderedFeatures({ layers: ['roads'], filter: ['==', ['get', 'class'], 'motorway'] })

Each result is { feature, layer, tile }: feature.properties, feature.id and feature.type (1 point, 2 line, 3 polygon), layer the style layer that drew it, and tile its { x, y, z }. feature.toGeoJSON(x, y, z) gives a GeoJSON feature. Only vector and geojson sources answer.

map.on('click', (e) => {
  const [hit] = map.queryRenderedFeatures(e.containerPoint, { layers: ['roads'] })
  if (hit)
    console.log(hit.layer.id, hit.feature.properties)
})

Feature state

State kept per feature, read by style expressions with ['feature-state', key]. Changing it repaints the tiles already loaded; it does not refetch them.

sourceLayer is the source-layer the feature is in, and a vector source needs it. A geojson source has only one, so { source, id } is enough, as in Mapbox; giving the source's id as sourceLayer reaches the same state.

map.on('pointermove', 'parks', (e) => {
  const id = e.features[0].feature.id
  map.setFeatureState({ source: 'parks', id }, { hover: true })
})

map.setPaintProperty('parks', 'fill-opacity',
  ['case', ['boolean', ['feature-state', 'hover'], false], 0.6, 0.3])

Events

map.on('moveend', () => console.log(map.getCenter()))
map.on('click', 'roads', e => console.log(e.features[0].feature.properties))

Pointer events follow the Pointer Events names. mousedown, mouseup, mousemove, mouseover and mouseout are not fired: listen for pointerdown, pointerup, pointermove, pointerover and pointerout.

Pointer and keyboard events

Camera events

jumpTo fires move and zoom, and rotate and pitch without a payload; it does not fire movestart or moveend.

Style and data events

Other events

3D

Terrain

map.addSource('dem', {
  type: 'raster-dem',
  tiles: ['https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png'],
  tileSize: 256,
  encoding: 'terrarium',
})
map.setTerrain({ source: 'dem', exaggeration: 1.3 })

Fog and sky

Tilted far enough to see the horizon, the map draws a sky above it whether or not setSky was called; setSky chooses its colours. On the globe, fog's color colours the halo and space-color the space around it.

Custom WebGL layers

render runs each frame after a WebGL tile layer has drawn. See 3D rendering.

Projection

With 'globe', the map zoomed out is a WebGL sphere textured with the tiles the flat map has loaded. Between zoom 5.5 and 6 it fades into the flat map. Without WebGL the flat map shows, with a halo round it.

Rendering and theme

The theme colours the controls, popups and attribution, not the basemap. Pair styles.dark(...) with setTheme('dark').

Image export

Tiles from a server that sends no CORS headers taint the canvas, and toDataURL then throws.

Layers and controls

Coordinates

Geolocation

LocateControl (control.locate()) is the button for it.

Offline

map.offline is the page's offline maps manager: download, list, delete, estimate, usage, and search and routing over what was downloaded. Reading it through a map makes that map the one a bare download({ bounds }) downloads. See Offline.

const region = await map.offline.download({ bounds: map.getBounds(), name: 'Paris' })

Lifecycle and DOM