API reference

InteractiveMap is a customisable mapping interface, designed for specific use cases and with a focus on accessibiity. It is provided as a high-level API that works in conjunction with a mapping framework such as MapLibre. Alternative mapping frameworks are catered for through the development of a custom provider.

The InteractiveMap object represents an instance of an InteractiveMap on your page. It emits events and provides methods that allow you to programmatically modify the map and trigger behaviour as users interact with it.

You create an instance of a InteractiveMap by specifying a container and options in the constructor. An InteractiveMap is then initialized on the page and returns an instance of an InteractiveMap object.

Getting started

For installation and setup instructions, see the Getting started guide.

Constructor

Copy
const interactiveMap = new InteractiveMap(container, options)

Parameters:

container

Type: string Required

The id of a container element where the map will be rendered.

options

Type: Object

Configuration object specifying map provider, map style, behaviour, and other settings. See Options below.

Options

appColorScheme

Type: string Default: 'light'

Colour scheme used by the application. Determines the colours of panels, buttons and controls.

Possible values

autoColorScheme

Type: boolean Default: false

Whether to automatically determine the colour scheme based on the user's system preferences.

backgroundColor

Type: string | Object<string, string> Default: var(--background-color)

Background colour applied to the map container. Allows application background colour to compliment the map style.

May be provided as:

• A single CSS colour value applied to all map styles
• An object keyed by map style ID, where each value is a valid CSS colour

behaviour

Type: string Default: 'buttonFirst'

Determines how and when the map is displayed.

Possible values

bounds

Type: [number, number, number, number]

Initial bounds [west, south, east, north]. Equivalent to extent; use whichever matches your map provider's terminology.

Passed directly to the underlying map engine.

buttonClass

Type: string Default: 'im-c-open-map-button'

CSS class applied to the button used to open the map. The button is only displayed when the 'behaviour' is hybrid or buttonFirst.

buttonText

Type: string Default: 'Map view'

Text content displayed inside the button used to open the map. The button is only displayed when the behaviour is hybrid or buttonFirst.

center

Type: [number, number]

Initial center [lng, lat] or [easting, northing] depending on the crs of the map provider.

Passed directly to the underlying map engine.

containerHeight

Type: string Default: '600px'

CSS height applied to the map container when the map is inline.

deviceNotSupportedText

Type: string

Message displayed when the user's device or browser is not supported.

enableFullscreen

Type: boolean Default: false

Whether a toggle button is displayed to allow the map to enter fullscreen mode. The button is only displayed when the map is inline.

enableZoomControls

Type: boolean Default: false

Whether zoom control buttons are displayed. Zoom controls are not diplayed when the interface type is touch.

extent

Type: [number, number, number, number]

Initial extent [minX, minY, maxX, maxY]. Equivalent to bounds; use whichever matches your map provider's terminology.

Passed directly to the underlying map engine.

genericErrorText

Type: string

Fallback error message shown when the map fails to load.

hasExitButton

Type: boolean Default: false

Whether an exit button is displayed. The exit button is only displayed when the behavour is buttonFirst or hybrid and the map is fullscreen.

hybridWidth

Type: number | null Default: null

Optional viewport width breakpoint (in pixels) used by the 'hybrid' behaviour. When not set, defaults to maxMobileWidth.

keyboardHintText

Type: string

HTML string providing keyboard shortcut instructions for assistive technology users. The hint text is displayed as a popup label when the viewport has focus.

mapLabel

Type: string Required

Accessible label describing the purpose of the map. This value is announced to screen readers.

mapProvider

Type: function Required

A factory function that returns a map provider instance, e.g., maplibreProvider().

mapSize

Type: string Default: 'small'

Visual size of text and features in the map itself.

Possible values

mapStyle

Type: MapStyleConfig Required

Map style configuration.

See MapStyleConfig for full details.

mapViewParamKey

Type: string Default: 'mv'

URL query parameter key used to persist map visibility state.

markerColor

Type: string | Object<string, string> Default: '#ff0000'

Default colour for map markers. Can be overridden per marker when calling addMarker().

May be provided as:

• A single colour value applied to all map styles
• An object keyed by map style ID, allowing different colours per style

markers

Type: MarkerConfig[]

Initial markers to display on the map.

See MarkerConfig for full details.

markerShape

Type: string Default: 'pin'

Default shape for map markers. Can be overridden per marker when calling addMarker().

maxExtent

Type: [number, number, number, number]

Maximum viewable extent [west, south, east, north]. Passed directly to the map engine; implementation varies.

maxMobileWidth

Type: number Default: 640

Maximum viewport width (in pixels) considered to be a mobile device.

maxZoom

Type: number

Maximum zoom level.

Passed directly to the underlying map engine.

minDesktopWidth

Type: number Default: 835

Minimum viewport width (in pixels) considered to be a desktop device.

minZoom

Type: number

Minimum zoom level.

Passed directly to the underlying map engine.

mode

Type: string | null Default: null

Initial application mode. Modes facilitate attaching behaviour to certain states, enabling short user journey steps within the map interface. Plugins can be configured to respect modes, only rendering content when the app is in a specific mode.

See also: setMode() method.

nudgePanDelta

Type: number Default: 5

Smaller pan distance (in pixels) used for fine-grained panning interactions.

nudgeZoomDelta

Type: number Default: 0.1

Smaller zoom increment used for fine-grained zoom adjustments.

pageTitle

Type: string

Supplementary text appended to the existing page title. Only used when the beahviour is buttonFirst or hybrid and the map is displayed in fullscreen mode.

panDelta

Type: number Default: 100

Distance (in pixels) the map pans during standard pan interactions.

plugins

Type: PluginDescriptor[]

Plugins to load.

See PluginDescriptor for full details.

preserveStateOnClose

Type: boolean
Default: false

Controls whether closing the map (via the browser back button or the exit map button when hasExitButton is true and the map is fullscreen) destroys the map instance or hides it while preserving its current state. Set to true to keep the map state intact, which is useful for implementations like a toggle map view list view pattern.

readMapText

Type: boolean Default: false

Whether map text labels can be selected and read aloud by assistive technologies.

reverseGeocodeProvider

Type: function | null

A factory function that returns a reverse geocode provider instance, e.g., openNamesProvider().

transformRequest

Type: function

Function to transform outgoing requests (e.g., to add authentication headers). Passed directly to MapLibre; other map engines may have their own equivalent. For ESRI SDK, this is handled in the EsriMapProvider configuration.

Copy
(url, resourceType) => { url, headers, credentials }

See the MapLibre documentation for full details.

zoom

Type: number

Initial zoom level.

Passed directly to the underlying map engine.

zoomDelta

Type: number Default: 1

Amount to change the zoom level for standard zoom interactions.

Methods

on(eventName, handler)

Subscribe to an event.

Copy
interactiveMap.on('app:ready', () => {
  console.log('Map is ready')
})

See Events for available event names.

off(eventName, handler)

Unsubscribe from an event.

Copy
const handler = () => console.log('Ready')
interactiveMap.on('app:ready', handler)
interactiveMap.off('app:ready', handler)

addMarker(id, coords, options)

Add a marker to the map.

Copy
interactiveMap.addMarker('home', [-0.1276, 51.5074], { color: '#0000ff' })

removeMarker(id)

Remove a marker from the map.

Copy
interactiveMap.removeMarker('home')

addButton(id, config)

Add a button to the UI at runtime.

See ButtonDefinition for configuration options.

Copy
// Simple button
interactiveMap.addButton('my-button', {
  label: 'Click me',
  iconId: 'info',
  onClick: (event, context) => console.log('Clicked'),
  mobile: { slot: 'top-right' },
  tablet: { slot: 'top-right' },
  desktop: { slot: 'top-right' }
})

// Button with a popup menu (experimental: only reliable when centred in the action bar)
interactiveMap.addButton('my-menu', {
  label: 'Options',
  iconId: 'menu',
  mobile: { slot: 'top-right' },
  tablet: { slot: 'top-right' },
  desktop: { slot: 'top-right' },
  menuItems: [
    { id: 'opt-a', label: 'Option A', onClick: () => console.log('A') },
    { id: 'opt-b', label: 'Option B', onClick: () => console.log('B') }
  ]
})

addPanel(id, config)

Add a panel to the UI at runtime.

See PanelDefinition for configuration options. When using this method, provide content via the html property.

Copy
interactiveMap.addPanel('info-panel', {
  label: 'Information',
  html: '<p>Panel content here</p>',
  mobile: { slot: 'bottom' },
  tablet: { slot: 'left' },
  desktop: { slot: 'left' }
})

removePanel(id)

Remove a panel from the UI.

Copy
interactiveMap.removePanel('info-panel')

showPanel(id)

Show a panel.

Copy
interactiveMap.showPanel('info-panel')

hidePanel(id)

Hide a panel.

Copy
interactiveMap.hidePanel('info-panel')

addControl(id, config)

Add a custom control to the UI at runtime.

See ControlDefinition for configuration options.

setMode(mode)

Set the application mode.

Copy
interactiveMap.setMode('fullscreen')

toggleButtonState(id, prop, value)

Set or toggle a button state.

Copy
// Toggle the pressed state
interactiveMap.toggleButtonState('my-button', 'pressed')

// Explicitly disable a button
interactiveMap.toggleButtonState('my-button', 'disabled', true)

// Hide a button
interactiveMap.toggleButtonState('my-button', 'hidden', true)

// Set expanded state (e.g. for a button controlling collapsible content)
interactiveMap.toggleButtonState('my-button', 'expanded', true)

// Control a menu item's state using its id
interactiveMap.toggleButtonState('opt-a', 'pressed', true)

fitToBounds(bounds)

Fit the map view to a bounding box or GeoJSON geometry. Safe zone padding is automatically applied so the content remains fully visible.

Copy
// Flat bbox
interactiveMap.fitToBounds([-0.489, 51.28, 0.236, 51.686])

// GeoJSON Feature
interactiveMap.fitToBounds({
  type: 'Feature',
  geometry: { type: 'Point', coordinates: [-0.1276, 51.5074] },
  properties: {}
})

// GeoJSON FeatureCollection
interactiveMap.fitToBounds({
  type: 'FeatureCollection',
  features: [featureA, featureB]
})

setView(opts)

Set the map center and zoom. Safe zone padding is automatically applied.

Copy
interactiveMap.setView({ center: [-0.1276, 51.5074], zoom: 12 })

Events

Subscribe to events using interactiveMap.on() and unsubscribe with interactiveMap.off().

Copy
// Subscribe to an event
interactiveMap.on('app:ready', () => {
  console.log('Map is ready!')
})

// Unsubscribe from an event
const handler = ({ panelId }) => console.log('Panel opened:', panelId)
interactiveMap.on('app:panelopened', handler)
interactiveMap.off('app:panelopened', handler)

app:ready

Emitted when the app is ready—layout and padding have been calculated and the map is about to be rendered. Emitted before map:ready.

Payload: None

Copy
interactiveMap.on('app:ready', () => {
  console.log('App is ready')
})

map:ready

Emitted when the underlying map is ready and initial app state (style and size) has settled.

Payload:

Copy
interactiveMap.on('map:ready', ({ map, mapStyleId, mapSize }) => {
  console.log('Active style:', mapStyleId, 'Size:', mapSize)
})

map:stylechange

Emitted when the map style finishes loading after a style change.

Payload: { mapStyleId: string }

Copy
interactiveMap.on('map:stylechange', ({ mapStyleId }) => {
  console.log('Style changed to', mapStyleId)
})

map:sizechange

Emitted when the map size changes.

Payload: { mapSize: string }

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

app:panelopened

Emitted when a panel is opened.

Payload: { panelId: string }

Copy
interactiveMap.on('app:panelopened', ({ panelId }) => {
  console.log('Panel opened:', panelId)
})

app:panelclosed

Emitted when a panel is closed.

Payload: { panelId: string }

Copy
interactiveMap.on('app:panelclosed', ({ panelId }) => {
  console.log('Panel closed:', panelId)
})