Basemap¶

Switches the basemap. It lists every entry in settings.basemaps with a thumbnail and name. Picking one swaps the basemap's layers underneath yours, so your layers, popups, drawings, and any visibility or opacity changes aren't touched. The picked basemap is highlighted at once, and a spinner shows over its thumbnail until the map has drawn it. If its style can't load, the highlight goes back to the basemap still on the map, and the console says why. Restoring a bookmark switches basemaps the same way. Clicking the active basemap does nothing.

id: basemap
Surfaces: top-bar, side-panel

Place it¶

"sidePanelWidgets": [{ "widgetName": "basemap" }]

or

"topBarWidgets": [{ "widgetName": "basemap" }]

Configuration¶

The list comes from the top-level basemaps array:

"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" }
]

Field	Type	Description
`id`	`string`	Unique id, also used to find the thumbnail
`name`	`string`	Name in the switcher
`style`	`string \\| StyleSpecification`	Style URL or inline style object
`thumbnail`	`string`	Optional thumbnail image

Basemaps has the full field list, and the default catalog lists the 17 basemaps in the demo.

No Basemap¶

A "No Basemap" button sits above the list, separated by a line. It turns the basemap off, so only your data shows, drawn on map.backgroundColor (black unless you set one). Your labels keep drawing with the last basemap's fonts. Picking a basemap again puts it back underneath your data. Bookmarks remember it.

Hide the button with settings.basemap:

"basemap": {
  "showNone": false
}

Field	Type	Default	Description
`showNone`	`boolean`	`true`	Show the "No Basemap" button

Thumbnails¶

Without thumbnail, the widget looks for assets/basemap-images/<id>.jpg (or .jpeg, .png, .webp) in its folder (app/widgets/basemap/). The filename must match the basemap's id exactly; the name doesn't count. Every basemap in the demo has a thumbnail. Images are cropped to a square from the center, so roughly square screenshots line up. A missing image shows a plain placeholder. When you add a basemap, add its image yourself, saved as a color (RGB) JPEG: Chrome can leave grayscale JPEGs blank at thumbnail size, even though they open fine on their own.