Controls

The term "control" is commonly used for all sorts of buttons and information display that take place in one of the corner of the map area. The most well know are probably the [+] and [-] zoom buttons as well as the attribution information.

User interface elements that can be added to the map. The items in this section exist outside of the map's canvas element.

Easy to add controls MapTiler logo

The easiest way to add the most used controls is through the Map constructor options.

To add a control in the map constructor, you must indicate the name of the control and one of these values: true to add the control or false to hide the control. You can also indicate in which position we are going to add the control: top-left top-right bottom-left bottom-right

Example

These are the controls that are directly accessible in the map constructor:

  • navigationControl: Shows the [+], [-] zoom buttons and tilt/bearing/compass buttons. Showing on the top-right by default.
  • geolocateControl: Shows a arrow-shaped locate button. When clicked, it adds a marker and center the map. If clicked again, the marker disapears (unless the map was moved since first clicked). Showing on the top-right by default.
  • terrainControl: Shows a button to enable/disable the 3D terrain (does not tilt the map) Hidden by default, showing on the top-right if true.
  • scaleControl: Shows a distance scale. The unit ("metric", "imperial" or "nautical") can be set in the config object config.unit (default: "metric"). Hidden by default, showing on the bottom-right if true.
  • fullscreenControl: Shows a button that toggles the map into fullscreen. Hidden by default, showing on the top-right if true.

Custom controls MapTiler logo

MapTiler SDK JS supports two flexible ways to add custom controls to your map interface, depending on the level of control and flexibility you need.

Programmatic Controls

Programmatic controls allow developers to have more control and register custom control elements manually by calling map.addControl() and providing a control implementation. This method is ideal for applications that require dynamic logic, event-based behaviour, or a deeper integration with a framework like React.

Custom controls are instantiated using the MaptilerCustomControl class. The element that should be used can be provided either as the element itself, or as its CSS selector. Optionally, two callback functions can be provided:

  • onClickfunction that is called when the element is clicked, and
  • onRenderfunction that is called every time the map renders a new state.

Both callbacks receive the active Map instance, the associated control element itself, and an event object associated with the original event (PointerEvent and MapLibreEvent respectively).

Example

Behaviour Overview

  • Upon adding, the control element is removed from its original DOM position and inserted into the map UI.
  • The onClick callback binds an action to user interaction.
  • The onRender callback can be used for state-based updates, styling, or other custom logic.
  • The control is treated as a native part of the map UI but maintains its own DOM context.
  • Upon removing, the control element is moved back into its original DOM position (if any) to not interfere with DOM handling of frameworks like React.

Declarative Controls

Declarative controls offer a simple way to add interactive UI elements to the map by using HTML attributes alone. Instead of instantiating controls through JavaScript, developers annotate DOM elements and allow the SDK to discover and wire them automatically.

Declarative controls are instantiated under the hood using the MaptilerExternalControl class.

Enabling Detection

To activate declarative control detection:

  • Set the customControls option to true in the map initialization configuration, to enable detection globally.
  • Alternatively, customControls may be set to a CSS selector string, to scope the autodetection to:
    • Elements matching the selector directly
    • Or elements whose ancestor matches the selector

Declaring a Control

To declare a control element, use the data-maptiler-control attribute:

The attribute’s value must be one of the predefined keywords, or an empty value. The element is automatically registered as a control and moved into the map UI. Supported values:

Value Description
zoom-in zooms the map in
zoom-out zooms the map out
toggle-projection toggles between Mercator and Globe projections
toggle-terrain turns Terrain layer on and off
reset-view resets bearing, pitch, and roll to 0 (heading north, no pitch, no roll)
reset-bearing resets bearing to 0 (heading north)
reset-pitch resets pitch to 0 (no pitch)
reset-roll resets roll to 0 (no roll)
empty value registers the element as control but does not add any functionality automatically
An Error is thrown when an unrecognized value is used.

Grouping Controls

For grouping related controls together, use the data-maptiler-control-group attribute. This approach is ideal for styling multiple buttons as a single floating UI block.

  • The group container (data-maptiler-control-group) is registered as a control and moved into the map UI.
  • It does not receive any automatic functionality.
  • Functional behaviour is attached to valid descendant elements with data-maptiler-control.

Positioning Controls

To set a specific position for a control or group, use the data-maptiler-position. The allowed values are the same as in addControl method.

State Styling via CSS

To support dynamic styling based on map state (without relying on JavaScript), custom CSS variables are set directly on the map container when declarative controls are enabled. Available CSS properties:

Property Description Data type
--maptiler-center-lng Longitude of map center unitless number
--maptiler-center-lat Latitude of map center unitless number
--maptiler-zoom Current zoom level unitless number
--maptiler-bearing Current map bearing (rotation) unitless number
--maptiler-pitch Pitch angle unitless number
--maptiler-roll Roll angle unitless number
--maptiler-is-globe-projection true if globe view is enabled, false otherwise string
--maptiler-has-terrain true if terrain is active, false otherwise string

This enables responsive UI tweaks via pure CSS, for example:

MaptilerNavigationControl MapTiler logo

GitHubLogosrc/MaptilerNavigationControl.ts

A MaptilerNavigationControl control contains zoom buttons and a compass.

Behavior changes

  • When enabled, the pitch button is always present
  • The pitch button now pitches the map if it ws not (and as before, unpitches the map if pitched)
  • The compass icon on the pitch button has a capped “squeeziness” factor to prevent it from looking extra flat and wide when pitch is set higher than 60

Example

Parameters

options(Object?)
options.showCompass
Boolean
default: true
 If true the compass button is included.
options.showZoom
Boolean
default: true
 If true the zoom-in and zoom-out buttons are included.
options.visualizePitch
Boolean
default: false
 If true the pitch is visualized by rotating X-axis of compass.

MaptilerGeolocateControl MapTiler logo

GitHubLogosrc/MaptilerGeolocateControl.ts

A MaptilerGeolocateControl control provides a button that uses the browser's geolocation API to locate the user on the map.

Not all browsers support geolocation, and some users may disable the feature. Geolocation support for modern browsers including Chrome requires sites to be served over HTTPS. If geolocation support is not available, the MaptilerGeolocateControl will show as disabled.

The zoom level applied will depend on the accuracy of the geolocation provided by the device.

The MaptilerGeolocateControl has two modes. If trackUserLocation is false (default) the control acts as a button, which when pressed will set the map's camera to target the user location. If the user moves, the map won't update. This is most suited for the desktop. If trackUserLocation is true the control acts as a toggle button that when active the user's location is actively monitored for changes. In this mode the MaptilerGeolocateControl has three interaction states:

  • active - the map's camera automatically updates as the user's location changes, keeping the location dot in the center. Initial state and upon clicking the MaptilerGeolocateControl button.
  • passive - the user's location dot automatically updates, but the map's camera does not. Occurs upon the user initiating a map movement.
  • disabled - occurs if Geolocation is not available, disabled or denied.

These interaction states can't be controlled programmatically, rather they are set based on user interactions.

Behavior changes

  • Now with these defaults:
    • enableHighAccuracy: true (uses browser location, probably GPS)
    • maximumAge: 0 (not using any cached location)
    • Timeout: 6000 (6 seconds)
    • trackUserLocation: true
  • When geolocate is “active”, zooming/rotating/pitching the map no longer changes the status to “background” because it does not change the center of the map. The center of the map must move of at least 1 m (world) from the active locked position in order for the status to change to “background” (note: the “background” status means the location is still refreshed but if the user moves, the map will no longer continue to be centered on them)
  • The method to update the blue disc (location precision radius) has been improved as we zoom in. It is now less shaky and behave according to perspective when the camera is tilted
Extends Evented.

Example

Parameters

options(Object?)
options.positionOptions
Object
default: {enableHighAccuracy:false,timeout:6000}
 A Geolocation API PositionOptions object.
options.fitBoundsOptions
Object
default: {maxZoom:15}
 A Map#fitBounds options object to use when the map is panned and zoomed to the user's location. The default is to use a maxZoom of 15 to limit how far the map will zoom in for very accurate locations.
options.trackUserLocation
Object
default: false
 If true the Geolocate Control becomes a toggle button and when active the map will receive updates to the user's location as it changes.
options.showAccuracyCircle
Object
default: true
 By default, if showUserLocation is true , a transparent circle will be drawn around the user location indicating the accuracy (95% confidence level) of the user's location. Set to false to disable. Always disabled when showUserLocation is false .
options.showUserLocation
Object
default: true
 By default a dot will be shown on the map at the user's location. Set to false to disable.

Methods

Events

MaptilerTerrainControl MapTiler logo

GitHubLogosrc/MaptilerTerrainControl.ts

The MaptilerTerrainControl shows a button to enable/disable the 3D terrain (does not tilt the map)

Example

AttributionControl

GitHubLogosrc/ui/control/attribution_control.ts

An AttributionControl control presents the map's attribution information. By default, the attribution control is expanded (regardless of map width).

Example

Parameters

options(Object?)(default {})
options.compact
boolean?
If true , force a compact attribution that shows the full attribution on mouse hover. If false , force the full attribution control. The default is a responsive attribution that collapses when the map is less than 640 pixels wide. Attribution should not be collapsed if it can comfortably fit on the map. compact should only be used to modify default attribution when map size makes it impossible to fit default attribution and when the automatic compact resizing for default settings are not sufficient.
options.customAttribution
(string | Array<string>)?
String or strings to show in addition to any other attributions.

ScaleControl

GitHubLogosrc/ui/control/scale_control.ts

A ScaleControl control displays the ratio of a distance on the map to the corresponding distance on the ground.

Example

Parameters

options(Object?)
options.maxWidth
number
default: '100'
 The maximum length of the scale control in pixels.
options.unit
string
default: 'metric'
 Unit of the distance ( 'imperial' , 'metric' or 'nautical' ).

Methods

FullscreenControl

GitHubLogosrc/ui/control/fullscreen_control.ts

A FullscreenControl control contains a button for toggling the map in and out of fullscreen mode.

Example

Parameters

options(Object?)
options.container
HTMLElement?
 container is the compatible DOM element which should be made full screen. By default, the map container element will be made full screen.

MaptilerLogoControl MapTiler logo

GitHubLogosrc/MaptilerLogoControl.ts

A MaptilerLogoControl replaces MaplibreLogoControl.

Can be used only with paid account

Example

Parameters

options(Object?)
options.logoURL
string
default: ""
 Image logo URL.
options.linkURL
string
default: ""
 Logo link URL

MaptilerMinimapControl MapTiler logo

GitHubLogosrc/Minimap.ts

A MaptilerMinimapControl control. Display a overview (minimap) in a user defined corner of the map

Parameters

options(Object?)
options.style MapTiler logo
(ReferenceMapStyle | MapStyleVariant | string | StyleSpecification)?
The map's style. This must be:
  • ReferenceMapStyle (e.g. MapStyle.STREETS)
  • MapStyleVariant (e.g. MapStyle.STREETS.DARK)
  • MapTIler Style ID (e.g. “streets-v2”)
  • uuid of custom style
  • an a JSON object conforming to the schema described in the GL Style Specification
  • a URL to such JSON.
options.zoomAdjust
number?
default: -4
 Set the zoom difference between the parent and the minimap. If the parent is zoomed to 10 and the minimap is zoomed to 8, the zoomAdjust should be 2.
options.lockZoom
number?
Set a zoom of the minimap and don't allow any future changes.
options.pitchAdjust
boolean?
default: false
 Adjust the pitch only if the user requests.
options.containerStyle
Record<string, string>?
Set CSS properties of the container using object key-values.
options.position
string?
default: 'bottom-left'
 Set the position of the minimap. Valid values are 'top-left' , 'top-right' , 'bottom-left' , and 'bottom-right' .
options.parentRect
ParentRect?
Set the parentRect fill and/or line options.

MaptilerProjectionControl

GitHubLogosrc/ui/control/globe_control.ts

A MaptilerProjectionControl control contains a button for toggling the map projection between "mercator" and "globe".

Example

MaptilerExternalControl MapTiler logo

GitHubLogosrc/controls/MaptilerExternalControl.ts

The MaptilerExternalControl allows any existing element to automatically become a map control. Used for detected controls if customControls config is turned on.

Example

Parameters

controlElement (HTMLElement): Element to be used as control, specified as either reference to element itself or a CSS selector to find the element in DOM
controlType (MaptilerExternalControlType): One of the predefined types of functionality. Allowed values: zoom-in | zoom-out | toggle-projection | toggle-terrain | reset-view | reset-bearing | reset-pitch | reset-roll

MaptilerCustomControl MapTiler logo

GitHubLogosrc/controls/MaptilerCustomControl.ts

The MaptilerCustomControl allows any existing element to become a map control.

Example

Parameters

selectorOrElement (string | HTMLElement): Element to be used as control, specified as either reference to element itself or a CSS selector to find the element in DOM
onClick (MaptilerCustomControlCallback<PointerEvent>?): Function called when the element is clicked
onRender (MaptilerCustomControlCallback<MapLibreEvent>?): Function called every time the underlying map renders a new state
Both callbacks receive the active Map instance, the associated control element itself, and an event object associated with the original event (PointerEvent and MapLibreEvent respectively).

IControl

GitHubLogosrc/ui/control/control.ts

Interface for interactive controls added to the map. This is a specification for implementers to model: it is not an exported method or class. This interface is the one to use to create custom controls.

Controls must implement onAdd and onRemove, and must own an element, which is often a div element. To use MapLibre GL JS's default control styling, add the maplibregl-ctrl class to your control's node.

Example

Methods

Reference documentation of MapTiler SDK JS, an extension of MapLibre GL JS