Map & Camera¶

The map block in app/settings.ts sets the map's initial view, camera limits, and the optional globe projection.

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

Fields¶

Field	Type	Default	Description
`style`	`string \\| StyleSpecification`	— (required)	The initial basemap. A URL to a MapLibre style JSON, or an inline style object
`center`	`[lng, lat]`	— (required)	Initial map center
`zoom`	`number`	— (required)	Initial zoom level
`pitch`	`number`	`0`	Initial camera tilt in degrees (0 = straight down). Common for 3D / oblique views
`bearing`	`number`	`0`	Initial rotation in degrees
`minZoom`	`number`	`0`	Camera zoom floor — the user can't zoom out past this
`maxZoom`	`number`	`22`	Camera zoom ceiling
`maxBounds`	`LngLatBoundsLike`	none	Clamp panning to a region, most simply `[[west, south], [east, north]]`
`globe`	`GlobeConfig`	none	Globe projection + starry backdrop + auto-spin (see below)

Camera clamp vs. layer zoom range

map.minZoom / map.maxZoom bound the camera — how far the user can zoom the whole map. These are different from a layer's minZoom / maxZoom, which control at what zooms an individual layer renders (see Adding Layers).

Example with camera limits¶

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]],  // San Francisco Bay Area
},

Basemaps¶

map.style is the initial basemap. The full list the user can switch between lives in the separate basemaps array, consumed by the Basemap widget:

basemaps: [
  { id: 'positron', name: 'Positron', style: 'https://tiles.openfreemap.org/styles/positron' },
  { id: 'liberty',  name: 'Liberty',  style: 'https://tiles.openfreemap.org/styles/liberty' },
  // … an inline style object also works (e.g. a raster OSM basemap)
],

Field	Type	Description
`id`	`string`	Unique id
`name`	`string`	Display name in the switcher
`style`	`string \\| StyleSpecification`	Style URL or inline style object
`thumbnail`	`string`	Optional preview image (see Basemap widget)

The demo's default basemaps come from OpenFreeMap (Positron, Liberty, Bright, Dark, Fiord) plus a raw OpenStreetMap raster style defined inline.

Globe projection¶

Add a globe block to start the map as a 3D globe with an optional starry backdrop and an auto-spin. Omit it for a flat (mercator) map.

map: {
  /* … */
  globe: {
    enabled: true,   // start on the globe instead of mercator
    stars: true,     // starry-space backdrop (globe-only)
    spin: {
      direction: 'east',  // 'east' (default) | 'west'
      speed: 6,           // degrees/sec (default 6 ≈ 1 revolution/min)
      continuous: false,  // see below
    },
  },
},

Field	Type	Default	Description
`enabled`	`boolean`	`false`	Start on the globe projection. The native Globe control can still toggle it at runtime regardless
`stars`	`boolean`	`false`	Render the starry backdrop (shows on the globe, removed in mercator)
`spin`	`GlobeSpinConfig`	none	Auto-spin on load. Omit to disable
`spin.direction`	`'east' \\| 'west'`	`'east'`	`'east'` matches Earth's real rotation
`spin.speed`	`number`	`6`	Rotation rate in degrees of longitude per second
`spin.continuous`	`boolean`	`false`	When `false`, the spin stops permanently on the first user interaction ("attract mode"). When `true`, it pauses during interaction and resumes a moment after — a kiosk-style perpetual globe