Map & Camera¶

The map block in your project's settings.json sets the starting view, camera limits and the optional globe.

"map": {
  "style": "https://tiles.openfreemap.org/styles/positron",
  "center": [-98.5, 39.5],
  "zoom": 4
}

Fields¶

Example with camera limits¶

A camera held to the San Francisco Bay Area:

"map": {
  "style": "https://tiles.openfreemap.org/styles/liberty",
  "center": [-122.4, 37.8],
  "zoom": 11,
  "pitch": 45,
  "minZoom": 9,
  "maxZoom": 18,
  "maxBounds": [[-123.2, 37.2], [-121.6, 38.3]]
}

Scroll zoom¶

"scrollZoom": false stops the mouse wheel and trackpad scroll from zooming the map, which helps when the map is embedded in a longer page that people scroll past. The zoom buttons, double-click and keyboard still zoom, and pinch zoom on touch screens isn't affected.

Load only visible layers¶

By default every layer loads at startup, hidden ones included, and the loading overlay waits for all of them, so everything is ready when it fades. With many or large hidden layers that makes startup slow. Set "onlyVisibleOnLoad": true in map to load only the layers visible at startup.

• Hidden geojson (by URL or with duckdb), geoparquet and flatgeobuf layers load the first time they're turned on. Until their data is drawn, a small spinner takes the place of their eye in the Layer List; after that, toggling is instant.
• The loading overlay doesn't wait for them, so startup is faster.
• Export Data, Filter and Zoom to Extent on a layer that hasn't loaded yet load it first. FlatGeobuf is the exception: its Zoom to Extent does nothing until the layer has been shown once.
• PMTiles, tile servers, raster layers and Esri services aren't affected: they only ever fetch what's in view, hidden or not.

Basemaps¶

map.style is the starting basemap. The full list users can switch between is in your project's basemaps.json, used by the Basemap widget:

{
  "$schema": "../../schema/basemaps.schema.json",
  "basemaps": [
    { "id": "positron-openfreemap", "name": "Positron (OpenFreeMap)", "style": "https://tiles.openfreemap.org/styles/positron" },
    { "id": "liberty-openfreemap", "name": "Liberty (OpenFreeMap)", "style": "https://tiles.openfreemap.org/styles/liberty" }
  ]
}

A style can also be an inline MapLibre style object instead of a URL (the demo's Satellite (ESRI) entry is one).

A basemap only provides the map's look. If its style declares a projection or a sky (VersaTiles styles declare a globe projection), the kit ignores them, so switching basemaps never turns the globe on or off. The projection comes only from the globe block below and the Globe control.

Default catalog¶

The demo ships 17 basemaps: Esri World Imagery, five OpenFreeMap styles and eleven VersaTiles themes. None needs an API key.

Globe projection¶

Add a globe block to start the map as a 3D globe, with optional stars, comets, a glow around the edge and an auto-spin. Leave it out for a flat (mercator) map.

"globe": {
  "enabled": true,
  "stars": true,
  "comets": true,
  "atmosphere": true,
  "spin": { "direction": "east", "speed": 6, "continuous": false }
}

It goes inside map. A speed of 6 degrees per second is about one turn a minute.

The stars, comets and glow are adapted from Leonel J. Dias's globe atmosphere, halo and comets technique.