Markers and popups

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

Marker

src/ui/marker.ts

Creates a marker component

Extends Evented.

options.anchor string default: 'center'	A string indicating the part of the Marker that should be positioned closest to the coordinate set via Marker#setLngLat . Options are `'center'` , `'top'` , `'bottom'` , `'left'` , `'right'` , `'top-left'` , `'top-right'` , `'bottom-left'` , and `'bottom-right'` .
options.className string	Space-separated CSS class names to add to marker element.
options.clickTolerance number default: 0	The max number of pixels a user can shift the mouse pointer during a click on the marker for it to be considered a valid click (as opposed to a marker drag). The default is to inherit map's clickTolerance.
options.color string default: '#3FB1CE'	The color to use for the default marker if options.element is not provided. The default is light blue.
options.draggable boolean default: false	A boolean indicating whether or not a marker is able to be dragged to a new position on the map.
options.element HTMLElement	DOM element to use as a marker. The default is a light blue, droplet-shaped SVG marker.
options.offset PointLike	The offset in pixels as a PointLike object to apply relative to the element's center. Negatives indicate left and up.
options.opacity number	Marker's opacity when it's in clear view (not behind 3d terrain). The default is `1`
options.opacityWhenCovered number	Marker's opacity when it's behind 3d terrain. The default is `0.2`
options.pitchAlignment string default: 'auto'	`map` aligns the `Marker` to the plane of the map. `viewport` aligns the `Marker` to the plane of the viewport. `auto` automatically matches the value of `rotationAlignment` .
options.rotation number default: 0	The rotation angle of the marker in degrees, relative to its respective `rotationAlignment` setting. A positive value will rotate the marker clockwise.
options.rotationAlignment string default: 'auto'	`map` aligns the `Marker` 's rotation relative to the map, maintaining a bearing as the map rotates. `viewport` aligns the `Marker` 's rotation relative to the viewport, agnostic to map rotations. `auto` is equivalent to `viewport` .
options.scale number default: 1	The scale to use for the default marker if options.element is not provided. The default scale corresponds to a height of `41px` and a width of `27px` .
options.subpixelPositioning boolean default: false	If `true`, rounding is disabled for placement of the marker, allowing for subpixel positioning and smoother movement when the marker is translated.

Methods

addClassName(className)

Adds a CSS class to the marker element.

Parameters

className(string) Non-empty string with CSS class name to add to marker element.

Example

addTo(map)

Attaches the Marker to a Map object.

Parameters

map(Map)The SDK JS map to add the marker to.

Example

getElement()

Returns the Marker's HTML element.

Returns

HTMLElement: element

getLngLat()

Get the marker's geographical location.

The longitude of the result may differ by a multiple of 360 degrees from the longitude previously set by setLngLat because Marker wraps the anchor longitude across copies of the world to keep the marker on screen.

Returns

LngLat: A LngLat describing the marker's location.

Example

Create a draggable Marker

getOffset()

Get the marker's offset.

Returns

Point: The marker's screen coordinates in pixels.

getPitchAlignment()

Returns the current pitchAlignment property of the marker.

Returns

string: The current pitch alignment of the marker in degrees.

getPopup()

Returns the Popup instance that is bound to the Marker.

Returns

Popup: popup

Example

getRotation()

Returns the current rotation angle of the marker (in degrees).

Returns

number: The current rotation angle of the marker.

getRotationAlignment()

Returns the current rotationAlignment property of the marker.

Returns

string: The current rotational alignment of the marker.

isDraggable()

Returns true if the marker can be dragged

Returns

boolean: True if the marker is draggable.

listens(type)

Returns a true if this instance of Evented or any forwardeed instances of Evented have a listener for the specified type.

Parameters

type(string)The The event type.

Returns

boolean: true if there is at least one registered listener for specified event type, false otherwise

off(type, listener)

Removes a previously registered event listener.

Parameters

type(string)The event type previously used to install the listener.

listener(Function)The function previously installed as a listener.

Returns

Marker: this

on(type, layer, listener)

Adds a listener for events of a specified type, optionally limited to features in a specified style layer.

Parameters

type(string) The event type to add a listen for.

listener(Function) The function to be called when the event is fired. The listener function is called with the data object passed to fire, extended with target and type properties

Returns

Marker: this

once(type, listener?)

Adds a listener that will be called only once to a specified event type.

The listener will be called first time the event fires after the listener is registered.

Parameters

type(string?)The event type to listen for.

listener(Function) The function to be called when the event is fired the first time.

Returns

(Marker | Promise <any> ): this or a promise if a listener is not provided

remove()

Removes the marker from a map

Returns

Marker: this

Example

removeClassName(className)

Removes a CSS class from the marker element.

Parameters

className(string) Non-empty string with CSS class name to remove from marker element.

Example

setDraggable(shouldBeDraggable)

Sets the draggable property and functionality of the marker

Parameters

shouldBeDraggable(boolean)(default false)Turns drag functionality on/off

Returns

Marker: this

setLngLat(lnglat)

Set the marker's geographical position and move it.

Parameters

lnglat(LngLat)A LngLat describing where the marker should be located.

Returns

Marker: this

Example

setOffset(offset)

Sets the offset of the marker

Parameters

offset(PointLike)The offset in pixels as a PointLike object to apply relative to the element's center. Negatives indicate left and up.

Returns

Marker: this

setPitchAlignment(alignment?)

Sets the pitchAlignment property of the marker.

Parameters

alignment(string?)Sets the pitchAlignment property of the marker. If alignment is 'auto', it will automatically match rotationAlignment .

Returns

Marker: this

setPopup(popup?)

Binds a Popup to the Marker.

Parameters

popup((Popup | null)?)An instance of the Popup class. If undefined or null, any popup set on this Marker instance is unset.

Returns

Marker: this

Example

Attach a popup to a marker instance

setRotation(rotation)

Sets the rotation property of the marker.

Parameters

rotation(number)(default 0)The rotation angle of the marker (clockwise, in degrees), relative to its respective Marker#setRotationAlignment setting.

Returns

Marker: this

setRotationAlignment(alignment)

Sets the rotationAlignment property of the marker.

Parameters

alignment(string)(default 'auto')Sets the rotationAlignment property of the marker.

Returns

Marker: this

toggleClassName(className)

Add or remove the given CSS class on the marker element, depending on whether the element currently has that class.

Parameters

className(string) Non-empty string with CSS class name to add/remove.

Returns

boolean: if the class was removed return false, if class was added, then return true

Example

togglePopup()

Opens or closes the Popup instance that is bound to the Marker, depending on the current state of the Popup.

Returns

Marker: this

Example

Events

drag

Fired while dragging

Properties

marker(Marker): object that is being dragged

dragend

Fired when the marker is finished being dragged

Properties

marker(Marker): object that was dragged

dragstart

Fired when dragging starts

Properties

marker(Marker): object that is being dragged

ImageViewerMarker

src/ImageViewer/ImageViewerMarker.ts

Creates a ImageViewerMarker component. This is, for all intents and purposes, the same as Marker with the exception of working in image pixels, not lat/lon. It composes the the internal logic of the Marker class so the behaviour should be exactly the same.

Extends Evented.

Example

Methods

Lists the methods that are different or exclusive to the ImageViewerMarker class. For the complete list of methods, check out Marker.Methods

addTo(viewer)

Attaches the ImageViewerMarker to a ImageViewer instance.

Parameters

viewer(ImageViewer)The SDK JS imageViewer to add the marker to.

Returns

ImageViewerMarker: this

Example

getPosition()

Gets the position of the ImageViewerMarker. This is the equivalent of the getLngLat function of the markers on the map

Returns

PointLike: A Point or an array [number, number] of two numbers representing x and y screen coordinates in pixels.

Example

setPosition(px)

Sets the position of the ImageViewerMarker. This is the equivalent of the setLngLat function of the markers on the map

Parameters

px([number, number]) The position of the ImageViewerMarker in image pixels.

Returns

ImageViewerMarker: this

Example

Add markers to a non-georeferenced image

A popup component.

Extends Evented.

options(Object?)

options.closeButton boolean default: true	If `true` , a close button will appear in the top right corner of the popup.
options.closeOnClick boolean default: true	If `true` , the popup will closed when the map is clicked.
options.closeOnMove boolean default: false	If `true` , the popup will closed when the map moves.
options.focusAfterOpen boolean default: true	If `true` , the popup will try to focus the first focusable element inside the popup.
options.anchor string?	A string indicating the part of the Popup that should be positioned closest to the coordinate set via Popup#setLngLat . Options are `'center'` , `'top'` , `'bottom'` , `'left'` , `'right'` , `'top-left'` , `'top-right'` , `'bottom-left'` , and `'bottom-right'` . If unset the anchor will be dynamically set to ensure the popup falls within the map container with a preference for `'bottom'` .
options.offset (number \| PointLike \| Object)?	A pixel offset applied to the popup's location specified as: a single number specifying a distance from the popup's location a PointLike specifying a constant offset an object of Points specifing an offset for each anchor position Negative offsets indicate left and up.
options.className string?	Space-separated CSS class names to add to popup container
options.maxWidth string default: '240px'	A string that sets the CSS property of the popup's maximum width, eg `'300px'` . To ensure the popup resizes to fit its content, set this property to `'none'` . Available values can be found here: https://developer.mozilla.org/en-US/docs/Web/CSS/max-width

addClassName(className)

Adds a CSS class to the popup container element.

Parameters

className(string)Non-empty string with CSS class name to add to popup container

Returns

Popup: this

Example

addTo(map)

Adds the popup to a map.

Parameters

map(Map)The SDK JS map to add the popup to.

Returns

Popup: this

Example

getElement()

Returns the Popup's HTML element.

Returns

HTMLElement: element

Example

remove()

Removes the popup from the map it has been added to.

Returns

Popup: this

Example

removeClassName(className)

Removes a CSS class from the popup container element.

Parameters

className(string)Non-empty string with CSS class name to remove from popup container

Returns

Popup: this

Example

setDOMContent(htmlNode)

Sets the popup's content to the element provided as a DOM node.

Parameters

htmlNode(Node)A DOM node to be used as content for the popup.

Returns

Popup: this

Example

setHTML(html)

Sets the popup's content to the HTML provided as a string.

This method does not perform HTML filtering or sanitization, and must be used only with trusted content. Consider Popup#setText if the content is an untrusted text string.

Parameters

html(string)A string representing HTML content for the popup.

Returns

Popup: this

Example

setSubpixelPositioning(value)

Set the option to allow subpixel positioning of the popup by passing a boolean

Parameters

value(boolean)When boolean is true, subpixel positioning is enabled for the popup.

Example

setText(text)

Sets the popup's content to a string of text.

This function creates a Text node in the DOM, so it cannot insert raw HTML. Use this method for security against XSS if the popup content is user-provided.

Was this helpful?