Map Styles Plugin

Adds a UI control for switching between basemap styles and, where supported by the map provider, adjusting the map size.

Usage

Copy
import createMapStylesPlugin from '@defra/interactive-map/plugins/map-styles'

const mapStylesPlugin = createMapStylesPlugin({
  mapStyles: [
    {
      id: 'default',
      label: 'Default',
      url: '/styles/default.json',
      thumbnail: '/images/default-thumb.png'
    },
    {
      id: 'satellite',
      label: 'Satellite',
      url: '/styles/satellite.json',
      thumbnail: '/images/satellite-thumb.png'
    }
  ]
})

const interactiveMap = new InteractiveMap({
  plugins: [mapStylesPlugin]
})

Options

Options are passed to the factory function when creating the plugin.

mapStyles

Type: MapStyleConfig[] Required

Array of map style configurations. Each style appears as an option in the style switcher UI.

See MapStyleConfig for full details.

Copy
createMapStylesPlugin({
  mapStyles: [
    {
      id: 'outdoor',
      label: 'Outdoor',
      url: '/styles/outdoor.json',
      appColorScheme: 'light',
      mapColorScheme: 'light',
      backgroundColor: '#f5f5f0',
      thumbnail: '/images/outdoor-thumb.png'
    },
    {
      id: 'dark',
      label: 'Dark',
      url: '/styles/dark.json',
      appColorScheme: 'dark',
      mapColorScheme: 'dark',
      backgroundColor: '#1a1a1a',
      thumbnail: '/images/dark-thumb.png'
    }
  ]
})

includeModes

Type: string[]

Array of mode identifiers. When set, the plugin only renders when the app is in one of these modes.

excludeModes

Type: string[]

Array of mode identifiers. When set, the plugin does not render when the app is in one of these modes.

Map size

When the active map provider supports map sizes (i.e. mapProvider.capabilities.supportsMapSizes is true), the panel also shows a map size control. This lets users choose between three size levels:

Increasing the map size scales all features — labels, lines, polygons, and symbols — proportionally larger. If the map provider does not support this capability, the size control is not shown.

Persistence

The selected map style and map size are automatically saved to localStorage and restored on the next page load, keyed by the map instance ID. Users' choices therefore persist across sessions without any additional configuration.

Methods

This plugin does not expose any public methods.

Events

map:setstyle

Emitted when the user selects a map style.

Payload: The full MapStyleConfig object for the selected style.

Copy
interactiveMap.on('map:setstyle', (mapStyle) => {
  console.log('Style changed to:', mapStyle.id)
})

map:setsize

Emitted when the user selects a map size. Only fired when the map provider supports map sizes.

Payload: 'small' | 'medium' | 'large'

Copy
interactiveMap.on('map:setsize', (size) => {
  console.log('Map size changed to:', size)
})