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.

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.

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