--- title: "Popup | JavaScript maps SDK" description: "Documentation for MapTiler SDK" --- > For AI agents: a documentation index is available at [/llms.txt](https://docs.maptiler.com/llms.txt). Markdown versions of all pages are available by appending .md to any URL. # Class Popup`Maptiler` A popup component. #### Example[](#example) Create a popup ```typescript 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'); }); ``` #### Example[](#example-1) Create a popup ```typescript 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'); }); ``` #### Example[](#example-2) ```typescript 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("

Hello World!

") .setMaxWidth("300px") .addTo(map); ``` #### See[](#see) - [Display a popup](https://maplibre.org/maplibre-gl-js/docs/examples/display-a-popup/) - [Display a popup on hover](https://maplibre.org/maplibre-gl-js/docs/examples/display-a-popup-on-hover/) - [Display a popup on click](https://maplibre.org/maplibre-gl-js/docs/examples/display-a-popup-on-click/) - [Attach a popup to a marker instance](https://maplibre.org/maplibre-gl-js/docs/examples/attach-a-popup-to-a-marker-instance/) - [Show polygon information on click](https://maplibre.org/maplibre-gl-js/docs/examples/show-polygon-information-on-click/) ## Events[](#events) **Event** `open` of type [Event](https://docs.maptiler.com/sdk-js/api-reference/classes/Event/) will be fired when the popup is opened manually or programmatically. **Event** `close` of type [Event](https://docs.maptiler.com/sdk-js/api-reference/classes/Event/) will be fired when the popup is closed manually or programmatically. #### Hierarchy ([View Summary](https://docs.maptiler.com/sdk-js/api-reference/hierarchy/#Popup)) - [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/) - Popup ##### Index ### Constructors[](#constructors) [constructor](#constructor) ### Properties[](#properties) [options](#options) [remove](#remove) ### Methods[](#methods) [addClassName](#addclassname) [addTo](#addto) [fire](#fire) [getElement](#getelement) [getLngLat](#getlnglat) [getMaxWidth](#getmaxwidth) [isOpen](#isopen) [listens](#listens) [off](#off) [on](#on) [once](#once) [removeClassName](#removeclassname) [setDOMContent](#setdomcontent) [setEventedParent](#seteventedparent) [setHTML](#sethtml) [setLngLat](#setlnglat) [setMaxWidth](#setmaxwidth) [setOffset](#setoffset) [setPadding](#setpadding) [setSubpixelPositioning](#setsubpixelpositioning) [setText](#settext) [toggleClassName](#toggleclassname) [trackPointer](#trackpointer) ## Constructors[](#constructors-1) ### constructor[](#constructor) - new Popup(options?: [PopupOptions](https://docs.maptiler.com/sdk-js/api-reference/types/PopupOptions/)): Popup[](#constructorpopup) #### Parameters - `Optional`options: [PopupOptions](https://docs.maptiler.com/sdk-js/api-reference/types/PopupOptions/) the options #### Returns Popup Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[constructor](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#constructor) ## Properties[](#properties-1) ### options[](#options) options: [PopupOptions](https://docs.maptiler.com/sdk-js/api-reference/types/PopupOptions/) Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[options](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#options) ### remove[](#remove) remove: () \=> this Removes the popup from the map it has been added to. #### Example[](#example-3) ```typescript let popup = new Popup().addTo(map); popup.remove(); ``` Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[remove](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#remove) ## Methods[](#methods-1) ### addClassName[](#addclassname) - addClassName(className: string): this[](#addclassname-1) 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 this #### Example[](#example-4) ```typescript let popup = new Popup() popup.addClassName('some-class') ``` Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[addClassName](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#addclassname) ### `Maptiler`addTo[](#addto) - addTo(map: [MapLibreMap](https://docs.maptiler.com/sdk-js/api-reference/classes/MapLibreMap/) | [Map](https://docs.maptiler.com/sdk-js/api-reference/classes/Map/)): this[](#addto-1) Adds the popup to a map. #### Parameters - map: [MapLibreMap](https://docs.maptiler.com/sdk-js/api-reference/classes/MapLibreMap/) | [Map](https://docs.maptiler.com/sdk-js/api-reference/classes/Map/) The MapLibre GL JS map to add the popup to. #### Returns this #### Example[](#example-5) ```typescript new Popup() .setLngLat([0, 0]) .setHTML("

Null Island

") .addTo(map); ``` #### See[](#see-1) - [Display a popup](https://maplibre.org/maplibre-gl-js/docs/examples/display-a-popup/) - [Display a popup on hover](https://maplibre.org/maplibre-gl-js/docs/examples/display-a-popup-on-hover/) - [Display a popup on click](https://maplibre.org/maplibre-gl-js/docs/examples/display-a-popup-on-click/) - [Show polygon information on click](https://maplibre.org/maplibre-gl-js/docs/examples/show-polygon-information-on-click/) Overrides [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[addTo](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#addto) ### fire[](#fire) - fire(event: string | [Event](https://docs.maptiler.com/sdk-js/api-reference/classes/Event/), properties?: any): this[](#fire-1) #### Parameters - event: string | [Event](https://docs.maptiler.com/sdk-js/api-reference/classes/Event/) - `Optional`properties: any #### Returns this Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[fire](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#fire) ### getElement[](#getelement) - getElement(): [HTMLElement](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.HTMLElement/)[](#getelement-1) Returns the `Popup`'s HTML element. #### Returns [HTMLElement](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.HTMLElement/) element #### Example[](#example-6) Change the `Popup` element's font size ```typescript let popup = new Popup() .setLngLat([-96, 37.8]) .setHTML("

Hello World!

") .addTo(map); let popupElem = popup.getElement(); popupElem.style.fontSize = "25px"; ``` Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[getElement](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#getelement) ### getLngLat[](#getlnglat) - getLngLat(): [LngLat](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.LngLat/)[](#getlnglat-1) 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](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.LngLat/) The geographical location of the popup's anchor. Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[getLngLat](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#getlnglat) ### getMaxWidth[](#getmaxwidth) - getMaxWidth(): string[](#getmaxwidth-1) Returns the popup's maximum width. #### Returns string The maximum width of the popup. Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[getMaxWidth](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#getmaxwidth) ### isOpen[](#isopen) - isOpen(): boolean[](#isopen-1) #### Returns boolean `true` if the popup is open, `false` if it is closed. Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[isOpen](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#isopen) ### listens[](#listens) - listens(type: string): boolean[](#listens-1) 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 event type #### Returns boolean `true` if there is at least one registered listener for specified event type, `false` otherwise Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[listens](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#listens) ### off[](#off) - off(type: string, listener: [Listener](https://docs.maptiler.com/sdk-js/api-reference/types/Listener/)): this[](#off-1) Removes a previously registered event listener. #### Parameters - type: string The event type to remove listeners for. - listener: [Listener](https://docs.maptiler.com/sdk-js/api-reference/types/Listener/) The listener function to remove. #### Returns this Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[off](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#off) ### on[](#on) - on(type: string, listener: [Listener](https://docs.maptiler.com/sdk-js/api-reference/types/Listener/)): [Subscription](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Subscription/)[](#on-1) Adds a listener to a specified event type. #### Parameters - type: string The event type to add a listen for. - listener: [Listener](https://docs.maptiler.com/sdk-js/api-reference/types/Listener/) 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 [Subscription](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Subscription/) Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[on](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#on) ### once[](#once) - once(type: string, listener?: [Listener](https://docs.maptiler.com/sdk-js/api-reference/types/Listener/)): Promise | Popup[](#once-1) 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. - `Optional`listener: [Listener](https://docs.maptiler.com/sdk-js/api-reference/types/Listener/) The function to be called when the event is fired the first time. #### Returns Promise | Popup `this` or a promise if a listener is not provided Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[once](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#once) ### removeClassName[](#removeclassname) - removeClassName(className: string): this[](#removeclassname-1) 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 this #### Example[](#example-7) ```typescript let popup = new Popup() popup.removeClassName('some-class') ``` Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[removeClassName](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#removeclassname) ### setDOMContent[](#setdomcontent) - setDOMContent(htmlNode: [Node](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.Node/)): this[](#setdomcontent-1) Sets the popup's content to the element provided as a DOM node. #### Parameters - htmlNode: [Node](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.Node/) A DOM node to be used as content for the popup. #### Returns this #### Example[](#example-8) Create an element with the popup content ```typescript let div = document.createElement('div'); div.innerHTML = 'Hello, world!'; let popup = new Popup() .setLngLat(e.lngLat) .setDOMContent(div) .addTo(map); ``` Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[setDOMContent](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#setdomcontent) ### setEventedParent[](#seteventedparent) - setEventedParent(parent?: [Evented](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Evented/) | null, data?: any): this[](#seteventedparent-1) Bubble all events fired by this instance of Evented to this parent instance of Evented. #### Parameters - `Optional`parent: [Evented](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Evented/) | null - `Optional`data: any #### Returns this Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[setEventedParent](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#seteventedparent) ### setHTML[](#sethtml) - setHTML(html: string): this[](#sethtml-1) 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](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#settext) if the content is an untrusted text string. #### Parameters - html: string A string representing HTML content for the popup. #### Returns this #### Example[](#example-9) ```typescript let popup = new Popup() .setLngLat(e.lngLat) .setHTML("

Hello World!

") .addTo(map); ``` #### See[](#see-2) - [Display a popup](https://maplibre.org/maplibre-gl-js/docs/examples/display-a-popup/) - [Display a popup on hover](https://maplibre.org/maplibre-gl-js/docs/examples/display-a-popup-on-hover/) - [Display a popup on click](https://maplibre.org/maplibre-gl-js/docs/examples/display-a-popup-on-click/) - [Attach a popup to a marker instance](https://maplibre.org/maplibre-gl-js/docs/examples/attach-a-popup-to-a-marker-instance/) Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[setHTML](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#sethtml) ### setLngLat[](#setlnglat) - setLngLat(lnglat: [LngLatLike](https://docs.maptiler.com/sdk-js/api-reference/types/LngLatLike/)): this[](#setlnglat-1) Sets the geographical location of the popup's anchor, and moves the popup to it. Replaces trackPointer() behavior. #### Parameters - lnglat: [LngLatLike](https://docs.maptiler.com/sdk-js/api-reference/types/LngLatLike/) The geographical location to set as the popup's anchor. #### Returns this Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[setLngLat](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#setlnglat) ### setMaxWidth[](#setmaxwidth) - setMaxWidth(maxWidth: string): this[](#setmaxwidth-1) 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](https://developer.mozilla.org/en-US/docs/Web/CSS/max-width) #### Parameters - maxWidth: string A string representing the value for the maximum width. #### Returns this Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[setMaxWidth](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#setmaxwidth) ### setOffset[](#setoffset) - setOffset(offset?: [Offset](https://docs.maptiler.com/sdk-js/api-reference/types/Offset/)): this[](#setoffset-1) Sets the popup's offset. #### Parameters - `Optional`offset: [Offset](https://docs.maptiler.com/sdk-js/api-reference/types/Offset/) Sets the popup's offset. #### Returns this Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[setOffset](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#setoffset) ### setPadding[](#setpadding) - setPadding(padding?: [PaddingOptions](https://docs.maptiler.com/sdk-js/api-reference/types/PaddingOptions/)): void[](#setpadding-1) Sets the popup's padding constraints for positioning. #### Parameters - `Optional`padding: [PaddingOptions](https://docs.maptiler.com/sdk-js/api-reference/types/PaddingOptions/) The padding to apply as a [PaddingOptions](https://docs.maptiler.com/sdk-js/api-reference/types/PaddingOptions/) object. #### Returns void #### Example[](#example-10) ```typescript popup.setPadding({ top: 10, right: 20, bottom: 30, left: 40 }); ``` Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[setPadding](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#setpadding) ### setSubpixelPositioning[](#setsubpixelpositioning) - setSubpixelPositioning(value: boolean): void[](#setsubpixelpositioning-1) 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. #### Returns void #### Example[](#example-11) ```typescript let popup = new Popup() popup.setSubpixelPositioning(true); ``` Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[setSubpixelPositioning](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#setsubpixelpositioning) ### setText[](#settext) - setText(text: string): this[](#settext-1) Sets the popup's content to a string of text. This function creates a [Text](https://developer.mozilla.org/en-US/docs/Web/API/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 - text: string Textual content for the popup. #### Returns this #### Example[](#example-12) ```typescript let popup = new Popup() .setLngLat(e.lngLat) .setText('Hello, world!') .addTo(map); ``` Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[setText](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#settext) ### toggleClassName[](#toggleclassname) - toggleClassName(className: string): boolean | undefined[](#toggleclassname-1) Add or remove the given CSS class on the popup container, depending on whether the container currently has that class. #### Parameters - className: string Non-empty string with CSS class name to add/remove #### Returns boolean | undefined if the class was removed return false, if class was added, then return true, undefined if there is no container #### Example[](#example-13) ```typescript let popup = new Popup() popup.toggleClassName('toggleClass') ``` Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[toggleClassName](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#toggleclassname) ### trackPointer[](#trackpointer) - trackPointer(): this[](#trackpointer-1) 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[](#example-14) ```typescript let popup = new Popup({ closeOnClick: false, closeButton: false }) .setHTML("

Hello World!

") .trackPointer() .addTo(map); ``` Inherited from [Popup](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/).[trackPointer](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.Popup/#trackpointer)