Marker

Creates a marker component

Examples

let marker = new Marker()
  .setLngLat([30.5, 50.5])
  .addTo(map);

Set options

let marker = new Marker({
    color: "#FFFFFF",
    draggable: true
  }).setLngLat([30.5, 50.5])
  .addTo(map);

.maplibregl-marker-covered {
    pointer-events: none;
    cursor: default;
}

See

• Add a default marker
• Add custom icons with Markers
• Create a draggable Marker
• Animate a marker
• Attach a popup to a marker instance

Events

Event dragstart of type MarkerDragEvent will be fired when dragging starts.

Event drag of type MarkerDragEvent will be fired while dragging.

Event dragend of type MarkerDragEvent will be fired when the marker is finished being dragged.

Event click of type MarkerClickEvent will be fired when the marker is clicked.

CSS Classes

CSS class maplibregl-marker-covered is toggled on the marker element when the marker is hidden behind 3D terrain or on the back of a globe. Use this class to apply custom styles to covered markers.

Extends

• Evented<MarkerEventType>

Constructors

Constructor

new Marker(options?: MarkerOptions): Marker

Parameters

Returns

Marker

Overrides

Evented<MarkerEventType>.constructor

Methods

_onKeyDown()

_onKeyDown(e: KeyboardEvent): void

Move a focused draggable default marker with the arrow keys (1 screen pixel per keydown; 10 with Shift). Mirrors the pointer drag gesture: the position updates before dragstart fires on the first movement, every movement fires drag, and releasing the arrow key (or losing focus) fires dragend. Holding a key down produces repeated drag events within a single gesture.

Parameters

Returns

void

_updateAccessibilityRole()

_updateAccessibilityRole(): void

Keep the default marker role aligned with interactivity. Default markers need a role because aria-label is set in Marker.addTo. Non-interactive markers use role=img; interactive ones (draggable or with a popup) use role=button. Click listeners are application-owned and do not automatically change the role. Custom marker elements are left alone so applications own their a11y tree. Explicit roles set by the application are preserved.

Returns

void

_updateTabIndex()

_updateTabIndex(): void

Keep the marker element focusable while it has built-in keyboard behavior. A popup makes any marker element interactive; dragging only manages focusability for the default marker so custom elements stay application-owned (#7790). A tabindex supplied by the application is never added, changed, or removed here.

Returns

void

addClassName()

addClassName(className: string): void

Adds a CSS class to the marker element.

Parameters

Returns

void

Example

let marker = new Marker()
marker.addClassName('some-class')

addTo()

addTo(map: Map): this

Attaches the Marker to a Map object.

Parameters

Returns

this

Example

let marker = new Marker()
  .setLngLat([30.5, 50.5])
  .addTo(map); // add the marker to the map

fire()

Call Signature

fire(event: MarkerDragEvent | MarkerClickEvent): this

Calls every listener registered for the event's type.

Parameters

Returns

this

Inherited from

Evented.fire

Call Signature

fire(type: keyof MarkerEventType, properties?: object): this

Compatibility with the (type: string, properties: Object) signature from previous versions. See https://github.com/mapbox/mapbox-gl-js/issues/6522, https://github.com/mapbox/mapbox-gl-draw/issues/766

Parameters

Returns

this

Inherited from

Evented.fire

getElement()

getElement(): HTMLElement

Returns the Marker's HTML element.

Returns

HTMLElement

element

getLngLat()

getLngLat(): LngLat

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

// Store the marker's longitude and latitude coordinates in a variable
let lngLat = marker.getLngLat();
// Print the marker's longitude and latitude values in the console
console.log('Longitude: ' + lngLat.lng + ', Latitude: ' + lngLat.lat )

See

Create a draggable Marker

getOffset()

getOffset(): Point

Get the marker's offset.

Returns

Point

The marker's screen coordinates in pixels.

getPitchAlignment()

getPitchAlignment(): Alignment

Returns the current pitchAlignment property of the marker.

Returns

Alignment

The current pitch alignment of the marker in degrees.

getPopup()

getPopup(): Popup

Returns the Popup instance that is bound to the Marker.

Returns

Popup

popup

Example

let marker = new Marker()
 .setLngLat([0, 0])
 .setPopup(new Popup().setHTML("<h1>Hello World!</h1>"))
 .addTo(map);

console.log(marker.getPopup()); // return the popup instance

getRotation()

getRotation(): number

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

Returns

number

The current rotation angle of the marker.

getRotationAlignment()

getRotationAlignment(): Alignment

Returns the current rotationAlignment property of the marker.

Returns

Alignment

The current rotational alignment of the marker.

isDraggable()

isDraggable(): boolean

Returns true if the marker can be dragged

Returns

boolean

True if the marker is draggable.

listens()

listens(type: keyof MarkerEventType): boolean

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

Parameters

Returns

boolean

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

Inherited from

Evented.listens

off()

off<T extends keyof MarkerEventType>(type: T, listener: (event: MarkerEventType[T]) => void): this

Removes a previously registered event listener.

Type Parameters

Parameters

Returns

this

Inherited from

Evented.off

on()

on<T extends keyof MarkerEventType>(type: T, listener: (event: MarkerEventType[T]) => void): Subscription

Adds a listener to a specified event type.

Type Parameters

Parameters

Returns

Subscription

Inherited from

Evented.on

once()

Call Signature

once<T extends keyof MarkerEventType>(type: T): Promise<MarkerEventType[T]>

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.

Type Parameters

Parameters

Returns

Promise<MarkerEventType[T]>

a promise that resolves with the event

Inherited from

Evented.once

Call Signature

once<T extends keyof MarkerEventType>(type: T, listener: (event: MarkerEventType[T]) => void): this

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.

Type Parameters

Parameters

Returns

this

this when a listener is provided

Inherited from

Evented.once

remove()

remove(): this

Removes the marker from a map

Returns

this

Example

let marker = new Marker().addTo(map);
marker.remove();

removeClassName()

removeClassName(className: string): void

Removes a CSS class from the marker element.

Parameters

Returns

void

Example

let marker = new Marker()
marker.removeClassName('some-class')

setDraggable()

setDraggable(shouldBeDraggable?: boolean): this

Sets the draggable property and functionality of the marker. A draggable default marker is also keyboard focusable and movable with the arrow keys (see MarkerOptions.draggable); custom marker elements keep their focusability and keyboard behavior application-owned.

Parameters

Returns

this

setEventedParent()

setEventedParent(parent?: Evented<EventTypeMap>, data?: EventedParentData | (() => EventedParentData)): this

Bubble all events fired by this instance of Evented to this parent instance of Evented.

Parameters

Returns

this

Inherited from

Evented.setEventedParent

setLngLat()

setLngLat(lnglat: LngLatLike): this

Set the marker's geographical position and move it.

Parameters

Returns

this

Example

Create a new marker, set the longitude and latitude, and add it to the map

new Marker()
  .setLngLat([-65.017, -16.457])
  .addTo(map);

See

• Add custom icons with Markers
• Create a draggable Marker

setOffset()

setOffset(offset: PointLike): this

Sets the offset of the marker

Parameters

Returns

this

setOpacity()

setOpacity(opacity?: string | number, opacityWhenCovered?: string | number): this

Sets the opacity and opacityWhenCovered properties of the marker. When called without arguments, resets opacity and opacityWhenCovered to defaults

Parameters

Returns

this

setPitchAlignment()

setPitchAlignment(alignment?: Alignment): this

Sets the pitchAlignment property of the marker.

Parameters

Returns

this

setPopup()

setPopup(popup?: Popup): this

Binds a Popup to the Marker.

Parameters

Returns

this

Example

let marker = new Marker()
 .setLngLat([0, 0])
 .setPopup(new Popup().setHTML("<h1>Hello World!</h1>")) // add popup
 .addTo(map);

See

Attach a popup to a marker instance

setRotation()

setRotation(rotation?: number): this

Sets the rotation property of the marker.

Parameters

Returns

this

setRotationAlignment()

setRotationAlignment(alignment?: Alignment): this

Sets the rotationAlignment property of the marker.

Parameters

Returns

this

setSubpixelPositioning()

setSubpixelPositioning(value: boolean): this

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

Parameters

Returns

this

Example

let marker = new Marker()
marker.setSubpixelPositioning(true);

toggleClassName()

toggleClassName(className: string): boolean

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

Parameters

Returns

boolean

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

Example

let marker = new Marker()
marker.toggleClassName('toggleClass')

togglePopup()

togglePopup(): this

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

Returns

this

Example

let marker = new Marker()
 .setLngLat([0, 0])
 .setPopup(new Popup().setHTML("<h1>Hello World!</h1>"))
 .addTo(map);

marker.togglePopup(); // toggle popup open or closed