Skip to main content

BasemapSwitcher

BasemapSwitcher

Switch between different map basemaps with a thumbnail grid flyout

Tags: basemap switcher tiles provider osm maptiler stadia

View Demo

The BasemapSwitcher component provides a control for switching between different map tile providers (OSM, MapTiler, Stadia Maps) with a thumbnail grid flyout. It includes built-in basemap definitions for free and API-key-based providers, and automatically preserves user-added data layers across basemap changes via the styleVersion mechanism.

Import​

<script>
  import { BasemapSwitcher } from '@classic-homes/maps-svelte';
</script>
// React
import { BasemapSwitcher } from '@classic-homes/maps-react';

Basic Usage​

<script>
  import { Map, Source, FillLayer, BasemapSwitcher } from '@classic-homes/maps-svelte';
</script>

<Map title="My Map" center={[-122.4, 37.8]} zoom={12}>
  <Source id="data" type="geojson" data={myData}>
    <FillLayer id="data-fill" source="data" fillColor="#3b82f6" />
  </Source>
  <BasemapSwitcher
    position="bottom-right"
    onBasemapChange={(basemap) => console.log('Switched to', basemap.name)}
  />
</Map>

Props​

Component-Specific Props​

Prop Type Default Description
basemaps BasemapDefinition[] - Basemap options to show (defaults to FREE_BASEMAPS)
extraBasemaps BasemapDefinition[] - Additional basemaps appended to the list
apiKeys BasemapApiKeys - API keys for providers (maptiler, stadia)
defaultBasemapId string - ID of the initially active basemap
activeBasemapId string - Controlled active basemap ID
onBasemapChange (basemap: BasemapDefinition) => void - Callback when the basemap is changed
columns number 3 Number of columns in the thumbnail grid
position 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' 'bottom-right' Control position on the map

Inherited Base Map Props​

Prop Type Default Description
title string required Map title for accessibility (aria-label)
description string - Optional description for screen readers
height number | string 400 Map height in pixels or CSS value
width number | string - Map width in pixels or CSS value
loading boolean false Show loading skeleton
error string | null - Error message to display
emptyMessage string - Message shown when data is empty
theme 'light' | 'dark' | 'auto' 'auto' Theme preference
animation boolean true Enable/disable animations (respects prefers-reduced-motion)
class string - Custom CSS class for styling

Accessibility​

  • The title prop is used as aria-label for screen readers
  • Keyboard navigation support for interactive elements
  • Animations respect prefers-reduced-motion media query
  • High contrast colors in both light and dark modes
  • CoordinateDisplay - Show cursor coordinates and zoom level on the map
  • Legend - Display a legend for map data layers
  • Map - Base map component
On this page