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
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 thetop-rightby 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 thetop-rightby default. -
terrainControl: Shows a button to enable/disable the 3D terrain (does not tilt the map) Hidden by default, showing on thetop-rightif 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 thebottom-rightif true. -
fullscreenControl: Shows a button that toggles the map into fullscreen. Hidden by default, showing on thetop-rightif true.
MaptilerNavigationControl
src/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
(Object?)
Related examples
MaptilerGeolocateControl
src/MaptilerGeolocateControl.ts
A 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 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 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
GeolocateControlbutton. - 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 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
Example
Parameters
(Object?)
| options.positionOptions
default: {enableHighAccuracy:false,timeout:6000}
|
A Geolocation API PositionOptions object. |
|---|---|
| options.fitBoundsOptions
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
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
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
default: true
|
By default a dot will be shown on the map at the user's
location. Set to
false
to disable.
|
Methods
Events
Fired on each Geolocation API position update which returned as an error.
Properties
(PositionError):
The returned
PositionError
object from the callback in
Geolocation.getCurrentPosition()
or
Geolocation.watchPosition()
.
Example
Fired on each Geolocation API position update which returned as success.
Properties
(Position):
The returned
Position
object from the callback in
Geolocation.getCurrentPosition()
or
Geolocation.watchPosition()
.
Example
Fired on each Geolocation API position update which returned as success but user position is out of map maxBounds.
Properties
(Position):
The returned
Position
object from the callback in
Geolocation.getCurrentPosition()
or
Geolocation.watchPosition()
.
Example
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.
Example
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).
Example
Related examples
MaptilerTerrainControl
Shows a button to enable/disable the 3D terrain (does not tilt the map)
Example
Related examples
AttributionControl
src/ui/control/attribution_control.ts
An AttributionControl control presents the map's attribution information.
Example
Parameters
(Object?)(default
{})
| options.compact | 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 or strings to show in addition to any other attributions. |
ScaleControl
src/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
(Object?)
Methods
Set the scale's unit of the distance
Parameters
(Unit)Unit of the
distance (
'imperial'
,
'metric'
or
'nautical'
).
FullscreenControl
src/ui/control/fullscreen_control.ts
A FullscreenControl control contains a button for toggling the map in and out of fullscreen mode.
Example
Parameters
(Object?)
| options.container | container
is the
compatible
DOM element
which should be made full screen. By default, the map container element will be made full screen.
|
|---|
Related examples
MaptilerLogoControl
A MaptilerLogoControl replaces MaplibreLogoControl.
Can be used only with paid account
Example
Parameters
MaptilerMinimapControl
A Minimap control. Display a overview (minimap) in a user defined corner of the map
Parameters
(Object?)
| options.style
|
The map's style. This must be:
|
|---|---|
| options.zoomAdjust
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 | Set a zoom of the minimap and don't allow any future changes. |
| options.pitchAdjust
default: false
|
Adjust the pitch only if the user requests. |
| options.containerStyle | Set CSS properties of the container using object key-values. |
| options.position
default:
'bottom-left' |
Set the position of the minimap.
Valid values are
'top-left'
,
'top-right'
,
'bottom-left'
, and
'bottom-right'
.
|
| options.parentRect | Set the parentRect fill and/or line options. |
IControl
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
Optionally provide a default position for this control. If this method
is implemented and Map#addControl is called
without the position
parameter, the value returned by getDefaultPosition will be used as the
control's position.
Returns
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.
Parameters
Returns
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.
Unregister a control on the map and give it a chance to detach event listeners and resources. This method is called by Map#removeControl internally.
Parameters
Returns
undefined:
there is no required return value for this method
