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
[-] 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
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:
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
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
terrainControl: Shows a button to enable/disable the 3D terrain (does not tilt the map) Hidden by default, showing on the
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
fullscreenControl: Shows a button that toggles the map into fullscreen. Hidden by default, showing on the
MaptilerNavigationControl control contains zoom buttons and a compass.
- 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
GeolocateControl 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 GeolocateControl will show as disabled.
The zoom level applied will depend on the accuracy of the geolocation provided by the device.
The GeolocateControl has two modes. If
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
true the control acts as a toggle button that when active the user's location is actively monitored
for changes. In this mode the GeolocateControl 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
- 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.
- 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 1m (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 (lation precision radius) has been improved as we zoom in. It is now less shaky and behave according to perspective when the camera is tilted
|A Geolocation API PositionOptions object.|
options object to use when the map is panned and zoomed to the user's location. The default is to use
|By default, if showUserLocation is
|By default a dot will be shown on the map at the user's
location. Set to
Fired when the Geolocate Control changes to the background state, which happens when a user changes the camera during an active position lock. This only applies when trackUserLocation is true. In the background state, the dot on the map will update with location updates but the camera will not.
Fired when the Geolocate Control changes to the active lock state, which happens either upon first obtaining a successful Geolocation API position for the user (a geolocate event will follow), or the user clicks the geolocate button when in the background state which uses the last known position to recenter the map and enter active lock state (no geolocate event will follow unless the users's location changes).
Shows a button to enable/disable the 3D terrain (does not tilt the map)
AttributionControl control presents the map's attribution information.
|options.customAttribution||String or strings to show in addition to any other attributions.|
ScaleControl control displays the ratio of a distance on the map to the corresponding distance
on the ground.
FullscreenControl control contains a button for toggling the map in and out of fullscreen mode.
MaptilerLogoControl replaces MaplibreLogoControl.
Can be used only with paid account
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
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
Optionally provide a default position for this control. If this method
is implemented and Map#addControl is called
parameter, the value returned by getDefaultPosition will be used as the
ControlPosition: a control position, one of the values valid in addControl.
Register a control on the map and give it a chance to register event listeners and resources. This method is called by Map#addControl internally.
(Map)the Map this control will be added to
HTMLElement: The control's container element. This should be created by the control and returned by onAdd without being attached to the DOM: the map will insert the control's element into the DOM as necessary.