Popup

A popup component.

Examples

Create a popup

let popup = new Popup();
// Set an event listener that will fire
// any time the popup is opened
popup.on('open', () => {
  console.log('popup was opened');
});

Create a popup

let popup = new Popup();
// Set an event listener that will fire
// any time the popup is closed
popup.on('close', () => {
  console.log('popup was closed');
});

let markerHeight = 50, markerRadius = 10, linearOffset = 25;
let popupOffsets = {
 'top': [0, 0],
 'top-left': [0,0],
 'top-right': [0,0],
 'bottom': [0, -markerHeight],
 'bottom-left': [linearOffset, (markerHeight - markerRadius + linearOffset) * -1],
 'bottom-right': [-linearOffset, (markerHeight - markerRadius + linearOffset) * -1],
 'left': [markerRadius, (markerHeight - markerRadius) * -1],
 'right': [-markerRadius, (markerHeight - markerRadius) * -1]
 };
let popup = new Popup({offset: popupOffsets, className: 'my-class'})
  .setLngLat(e.lngLat)
  .setHTML("<h1>Hello World!</h1>")
  .setMaxWidth("300px")
  .addTo(map);

See

• Display a popup
• Display a popup on hover
• Display a popup on click
• Attach a popup to a marker instance
• Show polygon information on click

Events

Event open of type PopupEvent will be fired when the popup is opened manually or programmatically.

Event close of type PopupEvent will be fired when the popup is closed manually or programmatically.

Extends

• Evented<PopupEventType>

Constructors

Constructor

new Popup(options?: PopupOptions): Popup

Parameters

Returns

Popup

Overrides

Evented<PopupEventType>.constructor

Methods

_updateOpacity()

_updateOpacity(): void

Add opacity to popup if in globe projection and location is behind view

Returns

void

addClassName()

addClassName(className: string): this

Adds a CSS class to the popup container element.

Parameters

Returns

this

Example

let popup = new Popup()
popup.addClassName('some-class')

addTo()

addTo(map: Map): this

Adds the popup to a map.

Parameters

Returns

this

Example

new Popup()
  .setLngLat([0, 0])
  .setHTML("<h1>Null Island</h1>")
  .addTo(map);

See

• Display a popup
• Display a popup on hover
• Display a popup on click
• Show polygon information on click

fire()

Call Signature

fire(event: PopupEvent): this

Calls every listener registered for the event's type.

Parameters

Returns

this

Inherited from

Evented.fire

Call Signature

fire(type: keyof PopupEventType, 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 Popup's HTML element.

Returns

HTMLElement

element

Example

Change the Popup element's font size

let popup = new Popup()
  .setLngLat([-96, 37.8])
  .setHTML("<p>Hello World!</p>")
  .addTo(map);
let popupElem = popup.getElement();
popupElem.style.fontSize = "25px";

getLngLat()

getLngLat(): LngLat

Returns the geographical location of the popup's anchor.

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

Returns

LngLat

The geographical location of the popup's anchor.

getMaxWidth()

getMaxWidth(): string

Returns the popup's maximum width.

Returns

string

The maximum width of the popup.

isOpen()

isOpen(): boolean

Returns

boolean

true if the popup is open, false if it is closed.

listens()

listens(type: keyof PopupEventType): 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 PopupEventType>(type: T, listener: (event: PopupEventType[T]) => void): this

Removes a previously registered event listener.

Type Parameters

Parameters

Returns

this

Inherited from

Evented.off

on()

on<T extends keyof PopupEventType>(type: T, listener: (event: PopupEventType[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 PopupEventType>(type: T): Promise<PopupEventType[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<PopupEventType[T]>

a promise that resolves with the event

Inherited from

Evented.once

Call Signature

once<T extends keyof PopupEventType>(type: T, listener: (event: PopupEventType[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 popup from the map it has been added to.

Returns

this

Example

let popup = new Popup().addTo(map);
popup.remove();

removeClassName()

removeClassName(className: string): this

Removes a CSS class from the popup container element.

Parameters

Returns

this

Example

let popup = new Popup()
popup.removeClassName('some-class')

setDOMContent()

setDOMContent(htmlNode: Node): this

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

Parameters

Returns

this

Example

Create an element with the popup content

let div = document.createElement('div');
div.innerHTML = 'Hello, world!';
let popup = new Popup()
  .setLngLat(e.lngLat)
  .setDOMContent(div)
  .addTo(map);

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

setHTML()

setHTML(html: string): this

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

Returns

this

Example

let popup = new Popup()
  .setLngLat(e.lngLat)
  .setHTML("<h1>Hello World!</h1>")
  .addTo(map);

See

• Display a popup
• Display a popup on hover
• Display a popup on click
• Attach a popup to a marker instance

setLngLat()

setLngLat(lnglat: LngLatLike): this

Sets the geographical location of the popup's anchor, and moves the popup to it. Replaces trackPointer() behavior.

Parameters

Returns

this

setMaxWidth()

setMaxWidth(maxWidth: string): this

Sets the popup's maximum width. This is setting the CSS property max-width. Available values can be found here: https://developer.mozilla.org/en-US/docs/Web/CSS/max-width

Parameters

Returns

this

setOffset()

setOffset(offset?: Offset): this

Sets the popup's offset.

Parameters

Returns

this

setPadding()

setPadding(padding?: PaddingOptions): void

Sets the popup's padding constraints for positioning.

Parameters

Returns

void

Example

popup.setPadding({ top: 10, right: 20, bottom: 30, left: 40 });

setSubpixelPositioning()

setSubpixelPositioning(value: boolean): void

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

Parameters

Returns

void

Example

let popup = new Popup()
popup.setSubpixelPositioning(true);

setText()

setText(text: string): this

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.

Parameters

Returns

this

Example

let popup = new Popup()
  .setLngLat(e.lngLat)
  .setText('Hello, world!')
  .addTo(map);

toggleClassName()

toggleClassName(className: string): boolean

Add or remove the given CSS class on the popup container, depending on whether the container currently has that class.

Parameters

Returns

boolean

if the class was removed return false, if class was added, then return true, undefined if there is no container

Example

let popup = new Popup()
popup.toggleClassName('toggleClass')

trackPointer()

trackPointer(): this

Tracks the popup anchor to the cursor position on screens with a pointer device (it will be hidden on touchscreens). Replaces the setLngLat behavior. For most use cases, set closeOnClick and closeButton to false.

Returns

this

Example

let popup = new Popup({ closeOnClick: false, closeButton: false })
  .setHTML("<h1>Hello World!</h1>")
  .trackPointer()
  .addTo(map);