Hello World!

> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/mapbox-gl-js/llms.txt)

# Markers and controls

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

## AttributionControl

[Source Code](https://github.com/mapbox/mapbox-gl-js/blob/29a082c40985763b038163d555f9305cb39233ad/src/ui/control/attribution_control.ts#L30-L208)

An `AttributionControl` control presents the map's [attribution information](https://docs.mapbox.com/help/how-mapbox-works/attribution/). Add this control to a map using [Map#addControl](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map#addcontrol).

> new AttributionControl(options: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>?)

### Parameters

| Name | Description |
| --- | --- |
| **options** [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)? (default `{}`) |  |
| **options.compact** [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?  | 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](https://docs.mapbox.com/help/how-mapbox-works/attribution/) and when the automatic compact resizing for default settings are not sufficient** . |
| **options.customAttribution** ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>)?  | String or strings to show in addition to any other attributions. You can also set a custom attribution when initializing your map with [the customAttribution option](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-parameters) . |

### Example

```js
const map = new mapboxgl.Map({attributionControl: false})
    .addControl(new mapboxgl.AttributionControl({
        customAttribution: 'Map design by me'
    }));
```

## FullscreenControl

[Source Code](https://github.com/mapbox/mapbox-gl-js/blob/29a082c40985763b038163d555f9305cb39233ad/src/ui/control/fullscreen_control.ts#L32-L137)

A `FullscreenControl` control contains a button for toggling the map in and out of fullscreen mode. See the `requestFullScreen` [compatibility table](https://developer.mozilla.org/en-US/docs/Web/API/Element/requestFullScreen#browser_compatibility) for supported browsers. Add this control to a map using [Map#addControl](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map#addcontrol).

> new FullscreenControl(options: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>?)

### Parameters

| Name | Description |
| --- | --- |
| **options** [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)? (default `{}`) |  |
| **options.container** [HTMLElement](https://developer.mozilla.org/docs/Web/HTML/Element)?  | `container` is the [compatible DOM element](https://developer.mozilla.org/en-US/docs/Web/API/Element/requestFullScreen#Compatible_elements) which should be made full screen. By default, the map container element will be made full screen. |

### Example

```js
map.addControl(new mapboxgl.FullscreenControl({container: document.querySelector('body')}));
```

### Related

-   [Example: View a fullscreen map](https://www.mapbox.com/mapbox-gl-js/example/fullscreen/)

## GeolocateControl

[Source Code](https://github.com/mapbox/mapbox-gl-js/blob/29a082c40985763b038163d555f9305cb39233ad/src/ui/control/geolocate_control.ts#L137-L901)

A `GeolocateControl` control provides a button that uses the browser's geolocation API to locate the user on the map. Add this control to a map using [Map#addControl](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map#addcontrol).

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](https://docs.mapbox.com/help/glossary/zoom-level/) applied depends 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. This is the initial state, and the state upon clicking the `GeolocateControl` button.
-   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. Instead, they are set based on user interactions.

Extends [Evented](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/events/#evented).

> new GeolocateControl(options: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>?)

### Parameters

| Name | Description |
| --- | --- |
| **options** [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)? (default `{}`) |  |
| **options.fitBoundsOptions** EasingOptions (default `{maxZoom:15}`) | A [Map#fitBounds](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#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.followUserLocation** [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean) (default `true`) | If `true` , the camera centers on the user's location. If `false` , the location dot will be shown without moving the camera. Clicking the control still centers on the user's location. |
| **options.geolocation** Geolocation (default `window.navigator.geolocation`) | `window.navigator.geolocation` by default; you can provide an object with the same shape to customize geolocation handling. |
| **options.positionOptions** [PositionOptions](https://developer.mozilla.org/docs/Web/API/PositionOptions) (default `{enableHighAccuracy:false,timeout:6000}`) | A Geolocation API [PositionOptions](https://developer.mozilla.org/en-US/docs/Web/API/PositionOptions) object. |
| **options.showAccuracyCircle** [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean) (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.showButton** [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean) (default `true`) | If `false` , the control button will be hidden. The user location dot can still be shown by setting `showUserLocation` to `true` and calling [GeolocateControl#trigger](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#geolocatecontrol#trigger) programmatically. |
| **options.showUserHeading** [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean) (default `false`) | If `true` an arrow will be drawn next to the user location dot indicating the device's heading. This only has affect when `trackUserLocation` is `true` . |
| **options.showUserLocation** [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean) (default `true`) | By default a dot will be shown on the map at the user's location. Set to `false` to disable. |
| **options.trackUserLocation** [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean) (default `false`) | If `true` the `GeolocateControl` becomes a toggle button and when active the map will receive updates to the user's location as it changes. |

### Example

```js
map.addControl(new mapboxgl.GeolocateControl({
    positionOptions: {
        enableHighAccuracy: true
    },
    trackUserLocation: true,
    showUserHeading: true
}));
```

```js
// Tracking without visible button - call trigger() to start
const geolocate = new mapboxgl.GeolocateControl({
    trackUserLocation: true,
    showUserLocation: true,
    showButton: false
});
map.addControl(geolocate);
geolocate.trigger();
```

```js
// Show user location without moving the camera
const geolocate = new mapboxgl.GeolocateControl({
    trackUserLocation: true,
    showUserLocation: true,
    followUserLocation: false
});
map.addControl(geolocate);
geolocate.trigger();
```

### Instance Members

#### trigger()

Trigger a geolocation event.

##### Returns

[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean): Returns `false` if called before control was added to a map, otherwise returns `true` .

##### Example

```js
// Initialize the geolocate control.
const geolocate = new mapboxgl.GeolocateControl({
    positionOptions: {
        enableHighAccuracy: true
    },
    trackUserLocation: true
});
// Add the control to the map.
map.addControl(geolocate);
// Wait until the control is set up before triggering it.
geolocate.once('ready', () => {
    geolocate.trigger();
});
```

#### setFollowUserLocation()

Sets whether the camera follows the user's location.

Fires [GeolocateControl#trackuserlocationstart](GeolocateControl#trackuserlocationstart) when enabling, [GeolocateControl#trackuserlocationend](GeolocateControl#trackuserlocationend) when disabling.

##### Parameters

| Name | Description |
| --- | --- |
| **follow** [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?  | Whether to follow the user's location. |

##### Returns

[GeolocateControl](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#geolocatecontrol): `this` .

##### Example

```js
geolocate.setFollowUserLocation(false); // stop following
geolocate.setFollowUserLocation(true);  // resume and center
```

#### setShowAccuracyCircle()

Sets whether a transparent accuracy circle is drawn around the user location dot.

Has no effect if the control was constructed with `showUserLocation: false`, because the underlying marker is only created when user-location rendering is enabled. Call `setShowUserLocation(true)` first if you need the circle after construction.

##### Parameters

| Name | Description |
| --- | --- |
| **show** [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?  | Whether to draw the accuracy circle. |

##### Returns

[GeolocateControl](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#geolocatecontrol): `this` .

##### Example

```js
geolocate.setShowAccuracyCircle(false);
```

#### setShowUserHeading()

Sets whether an arrow next to the user location dot indicates the device's heading.

Only takes effect when `trackUserLocation` is `true` (heading is only meaningful while a geolocation watch is active).

##### Parameters

| Name | Description |
| --- | --- |
| **show** [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?  | Whether to show the heading arrow. |

##### Returns

[GeolocateControl](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#geolocatecontrol): `this` .

##### Example

```js
geolocate.setShowUserHeading(true);
```

#### setFitBoundsOptions()

Sets the [Map#fitBounds](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map#fitbounds) options used when the map is panned and zoomed to the user's location. Takes effect on the next geolocation event or the next call to [GeolocateControl#trigger](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#geolocatecontrol#trigger).

##### Parameters

| Name | Description |
| --- | --- |
| **opts** EasingOptions?  | The new `fitBounds` options. |

##### Returns

[GeolocateControl](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#geolocatecontrol): `this` .

##### Example

```js
geolocate.setFitBoundsOptions({maxZoom: 17, duration: 0});
```

#### setShowUserLocation()

Sets whether the user location dot (and, when enabled, the accuracy circle and heading arrow) is rendered on the map.

When called with `true` on a control that was constructed with `showUserLocation: false`, the location markers are created lazily.

##### Parameters

| Name | Description |
| --- | --- |
| **show** [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?  | Whether to render the user location dot. |

##### Returns

[GeolocateControl](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#geolocatecontrol): `this` .

##### Example

```js
geolocate.setShowUserLocation(false); // hide the puck
geolocate.setShowUserLocation(true);  // show it again
```

### Events

#### geolocate

Fired on each Geolocation API position update that returned as success.

##### Properties

| Name | Description |
| --- | --- |
| **data** GeolocationPosition  | The returned [Position](https://developer.mozilla.org/en-US/docs/Web/API/Position) object from the callback in [Geolocation.getCurrentPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/getCurrentPosition) or [Geolocation.watchPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/watchPosition) . |

##### Example

```js
// Initialize the GeolocateControl.
const geolocate = new mapboxgl.GeolocateControl({
    positionOptions: {
        enableHighAccuracy: true
    },
    trackUserLocation: true
});
// Add the control to the map.
map.addControl(geolocate);
// Set an event listener that fires
// when a geolocate event occurs.
geolocate.on('geolocate', () => {
    console.log('A geolocate event has occurred.');
});
```

#### error

Fired on each Geolocation API position update that returned as an error.

##### Properties

| Name | Description |
| --- | --- |
| **data** GeolocationPositionError  | The returned [PositionError](https://developer.mozilla.org/en-US/docs/Web/API/PositionError) object from the callback in [Geolocation.getCurrentPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/getCurrentPosition) or [Geolocation.watchPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/watchPosition) . |

##### Example

```js
// Initialize the GeolocateControl.
const geolocate = new mapboxgl.GeolocateControl({
    positionOptions: {
        enableHighAccuracy: true
    },
    trackUserLocation: true
});
// Add the control to the map.
map.addControl(geolocate);
// Set an event listener that fires
// when an error event occurs.
geolocate.on('error', () => {
    console.log('An error event has occurred.');
});
```

#### outofmaxbounds

Fired on each Geolocation API position update that returned as success but user position is out of map `maxBounds`.

##### Properties

| Name | Description |
| --- | --- |
| **data** GeolocationPosition  | The returned [Position](https://developer.mozilla.org/en-US/docs/Web/API/Position) object from the callback in [Geolocation.getCurrentPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/getCurrentPosition) or [Geolocation.watchPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/watchPosition) . |

##### Example

```js
// Initialize the GeolocateControl.
const geolocate = new mapboxgl.GeolocateControl({
    positionOptions: {
        enableHighAccuracy: true
    },
    trackUserLocation: true
});
// Add the control to the map.
map.addControl(geolocate);
// Set an event listener that fires
// when an outofmaxbounds event occurs.
geolocate.on('outofmaxbounds', () => {
    console.log('An outofmaxbounds event has occurred.');
});
```

#### trackuserlocationstart

Fired when the `GeolocateControl` 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 when 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

```js
// Initialize the GeolocateControl.
const geolocate = new mapboxgl.GeolocateControl({
    positionOptions: {
        enableHighAccuracy: true
    },
    trackUserLocation: true
});
// Add the control to the map.
map.addControl(geolocate);
// Set an event listener that fires
// when a trackuserlocationstart event occurs.
geolocate.on('trackuserlocationstart', () => {
    console.log('A trackuserlocationstart event has occurred.');
});
```

#### ready

Fired once when the `GeolocateControl` has finished initializing and is ready to be triggered. Because geolocation support is determined asynchronously (via the Permissions API on supporting browsers), this event provides a reliable signal that [GeolocateControl#trigger](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#geolocatecontrol#trigger) can be called without warning.

##### Example

```js
// Initialize the GeolocateControl.
const geolocate = new mapboxgl.GeolocateControl({
    trackUserLocation: true
});
// Add the control to the map.
map.addControl(geolocate);
// Trigger the control as soon as it is ready.
geolocate.once('ready', () => {
    geolocate.trigger();
});
```

#### trackuserlocationend

Fired when the `GeolocateControl` 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

```js
// Initialize the GeolocateControl.
const geolocate = new mapboxgl.GeolocateControl({
    positionOptions: {
        enableHighAccuracy: true
    },
    trackUserLocation: true
});
// Add the control to the map.
map.addControl(geolocate);
// Set an event listener that fires
// when a trackuserlocationend event occurs.
geolocate.on('trackuserlocationend', () => {
    console.log('A trackuserlocationend event has occurred.');
});
```

### Related

-   [Example: Locate the user](https://www.mapbox.com/mapbox-gl-js/example/locate-user/)

## IControl

[Source Code](https://github.com/mapbox/mapbox-gl-js/blob/29a082c40985763b038163d555f9305cb39233ad/src/ui/map.ts#L460-L5354)

Interface for interactive controls added to the map. This is a specification for implementers to model: it is not an exported method or class.

Controls must implement `onAdd` and `onRemove`, and must own an element, which is often a `div` element. To use Mapbox GL JS's default control styling, add the `mapboxgl-ctrl` class to your control's node.

### Example

```js
// Control implemented as ES6 class
class HelloWorldControl {
    onAdd(map) {
        this._map = map;
        this._container = document.createElement('div');
        this._container.className = 'mapboxgl-ctrl';
        this._container.textContent = 'Hello, world';
        return this._container;
    }

    onRemove() {
        this._container.parentNode.removeChild(this._container);
        this._map = undefined;
    }
}
```

```js
// Control implemented as ES5 prototypical class
function HelloWorldControl() { }

HelloWorldControl.prototype.onAdd = function(map) {
    this._map = map;
    this._container = document.createElement('div');
    this._container.className = 'mapboxgl-ctrl';
    this._container.textContent = 'Hello, world';
    return this._container;
};

HelloWorldControl.prototype.onRemove = function () {
    this._container.parentNode.removeChild(this._container);
    this._map = undefined;
};
```

### Instance Members

#### onAdd()

Register a control on the map and give it a chance to register event listeners and resources. This method is called by [Map#addControl](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map#addcontrol) internally.

##### Parameters

| Name | Description |
| --- | --- |
| **map** [Map](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map)  | The Map this control will be added to. |

##### Returns

[HTMLElement](https://developer.mozilla.org/docs/Web/HTML/Element): 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.

#### onRemove()

Unregister a control on the map and give it a chance to detach event listeners and resources. This method is called by [Map#removeControl](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map#removecontrol) internally.

##### Parameters

| Name | Description |
| --- | --- |
| **map** [Map](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map)  | The Map this control will be removed from. |

##### Returns

[undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined): There is no required return value for this method.

#### getDefaultPosition()

Optionally provide a default position for this control. If this method is implemented and [Map#addControl](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map#addcontrol) is called without the `position` parameter, the value returned by getDefaultPosition will be used as the control's position.

##### Returns

[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String): A control position, one of the values valid in addControl.

## Marker

[Source Code](https://github.com/mapbox/mapbox-gl-js/blob/29a082c40985763b038163d555f9305cb39233ad/src/ui/marker.ts#L84-L1017)

Creates a marker component.

Extends [Evented](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/events/#evented).

> new Marker(options: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>?, legacyOptions: MarkerOptions?)

### Parameters

| Name | Description |
| --- | --- |
| **options** [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?  |  |
| **options.altitude** [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) (default `0`) | Elevation in meters above the map surface. If terrain is enabled, the marker will be elevated relative to the terrain. |
| **options.anchor** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) (default `'center'`) | A string indicating the part of the Marker that should be positioned closest to the coordinate set via [Marker#setLngLat](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker#setlnglat) . Options are `'center'` , `'top'` , `'bottom'` , `'left'` , `'right'` , `'top-left'` , `'top-right'` , `'bottom-left'` , and `'bottom-right'` . |
| **options.className** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?  | Space-separated CSS class names to add to marker element. |
| **options.clickTolerance** [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/docs/Web/HTML/Element)?  | DOM element to use as a marker. The default is a light blue, droplet-shaped SVG marker. |
| **options.occludedOpacity** [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) (default `0.2`) | The opacity of a marker that's occluded by 3D terrain. |
| **options.offset** [PointLike](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/geography/#pointlike)?  | The offset in pixels as a [PointLike](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/geography/#pointlike) object to apply relative to the element's center. Negatives indicate left and up. |
| **options.pitchAlignment** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) (default `'auto'`) | The alignment of the marker's rotation. `'map'` is aligned with the map plane, consistent with the cardinal directions as the map rotates. `'viewport'` is screenspace-aligned. `'horizon'` is aligned according to the nearest horizon, on non-globe projections it is equivalent to `'viewport'` . `'auto'` is equivalent to `'viewport'` . |
| **options.scale** [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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` . |
| **legacyOptions** MarkerOptions?  |  |

### Example

```js
// Create a new marker.
const marker = new mapboxgl.Marker()
    .setLngLat([30.5, 50.5])
    .addTo(map);
```

```js
// Set marker options.
const marker = new mapboxgl.Marker({
    color: "#FFFFFF",
    draggable: true
}).setLngLat([30.5, 50.5])
    .addTo(map);
```

### Instance Members

#### addTo()

Attaches the `Marker` to a `Map` object.

##### Parameters

| Name | Description |
| --- | --- |
| **map** [Map](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map)  | The Mapbox GL JS map to add the marker to. |

##### Returns

[Marker](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker): Returns itself to allow for method chaining.

##### Example

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

#### remove()

Removes the marker from a map.

##### Returns

[Marker](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker): Returns itself to allow for method chaining.

##### Example

```js
const marker = new mapboxgl.Marker().addTo(map);
marker.remove();
```

#### 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](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/geography/#lnglat): A [LngLat](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/geography/#lnglat) describing the marker's location.

##### Example

```js
// Store the marker's longitude and latitude coordinates in a variable
const lngLat = marker.getLngLat();
// Print the marker's longitude and latitude values in the console
console.log(`Longitude: ${lngLat.lng}, Latitude: ${lngLat.lat}`);
```

##### Related

-   [Example: Create a draggable Marker](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-marker/)

#### setLngLat()

Set the marker's geographical position and move it.

##### Parameters

| Name | Description |
| --- | --- |
| **lnglat** [LngLat](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/geography/#lnglat)  | A [LngLat](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/geography/#lnglat) describing where the marker should be located. |

##### Returns

[Marker](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker): Returns itself to allow for method chaining.

##### Example

```js
// Create a new marker, set the longitude and latitude, and add it to the map.
new mapboxgl.Marker()
    .setLngLat([-65.017, -16.457])
    .addTo(map);
```

##### Related

-   [Example: Add custom icons with Markers](https://docs.mapbox.com/mapbox-gl-js/example/custom-marker-icons/)
-   [Example: Create a draggable Marker](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-marker/)
-   [Example: Add a marker using a place name](https://docs.mapbox.com/mapbox-gl-js/example/marker-from-geocode/)

#### setAltitude()

Sets the `altitude` property of the marker.

##### Parameters

| Name | Description |
| --- | --- |
| **altitude** [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) (default `0`) | Sets the `altitude` property of the marker. |

##### Returns

[Marker](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker): Returns itself to allow for method chaining.

##### Example

```js
marker.setAltitude(100);
```

#### getAltitude()

Returns the current `altitude` of the marker.

##### Returns

[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number): The altitude of the marker.

##### Example

```js
const altitude = marker.getAltitude();
```

#### getElement()

Returns the `Marker`'s HTML element.

##### Returns

[HTMLElement](https://developer.mozilla.org/docs/Web/HTML/Element): Returns the marker element.

##### Example

```js
const element = marker.getElement();
```

#### setPopup()

Binds a [Popup](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup) to the [Marker](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker).

##### Parameters

| Name | Description |
| --- | --- |
| **popup** ([Popup](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup) \| null)  | An instance of the [Popup](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup) class. If undefined or null, any popup set on this [Marker](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker) instance is unset. |

##### Returns

[Marker](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker): Returns itself to allow for method chaining.

##### Example

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

##### Related

-   [Example: Attach a popup to a marker instance](https://docs.mapbox.com/mapbox-gl-js/example/set-popup/)

#### getPopup()

Returns the [Popup](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup) instance that is bound to the [Marker](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker).

##### Returns

[Popup](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup): Returns the popup.

##### Example

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

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

#### togglePopup()

Opens or closes the [Popup](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup) instance that is bound to the [Marker](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker), depending on the current state of the [Popup](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup).

##### Returns

[Marker](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker): Returns itself to allow for method chaining.

##### Example

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

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

#### getOffset()

Get the marker's offset.

##### Returns

[Point](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/geography/#point): The marker's screen coordinates in pixels.

##### Example

```js
const offset = marker.getOffset();
```

#### setOffset()

Sets the offset of the marker.

##### Parameters

| Name | Description |
| --- | --- |
| **offset** [PointLike](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/geography/#pointlike)  | The offset in pixels as a [PointLike](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/geography/#pointlike) object to apply relative to the element's center. Negatives indicate left and up. |

##### Returns

[Marker](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker): Returns itself to allow for method chaining.

##### Example

```js
marker.setOffset([0, 1]);
```

#### addClassName()

Adds a CSS class to the marker element.

##### Parameters

| Name | Description |
| --- | --- |
| **className** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | Non-empty string with CSS class name to add to marker element. |

##### Returns

[Marker](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker): Returns itself to allow for method chaining.

##### Example

```js
const marker = new mapboxgl.Marker();
marker.addClassName('some-class');
```

#### removeClassName()

Removes a CSS class from the marker element.

##### Parameters

| Name | Description |
| --- | --- |
| **className** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | Non-empty string with CSS class name to remove from marker element. |

##### Returns

[Marker](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker): Returns itself to allow for method chaining.

##### Example

```js
const marker = new mapboxgl.Marker({className: 'some classes'});
marker.removeClassName('some');
```

#### toggleClassName()

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

##### Parameters

| Name | Description |
| --- | --- |
| **className** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | Non-empty string with CSS class name to add/remove. |

##### Returns

[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean): If the class was removed return `false` . If the class was added, then return `true` .

##### Example

```js
const marker = new mapboxgl.Marker();
marker.toggleClassName('highlighted');
```

#### setDraggable()

Sets the `draggable` property and functionality of the marker.

##### Parameters

| Name | Description |
| --- | --- |
| **shouldBeDraggable** [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean) (default `false`) | Turns drag functionality on/off. |

##### Returns

[Marker](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker): Returns itself to allow for method chaining.

##### Example

```js
marker.setDraggable(true);
```

#### isDraggable()

Returns true if the marker can be dragged.

##### Returns

[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean): True if the marker is draggable.

##### Example

```js
const isMarkerDraggable = marker.isDraggable();
```

#### setRotation()

Sets the `rotation` property of the marker.

##### Parameters

| Name | Description |
| --- | --- |
| **rotation** [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) (default `0`) | The rotation angle of the marker (clockwise, in degrees), relative to its respective [Marker#setRotationAlignment](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker#setrotationalignment) setting. |

##### Returns

[Marker](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker): Returns itself to allow for method chaining.

##### Example

```js
marker.setRotation(45);
```

#### getRotation()

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

##### Returns

[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number): The current rotation angle of the marker.

##### Example

```js
const rotation = marker.getRotation();
```

#### setRotationAlignment()

Sets the `rotationAlignment` property of the marker.

##### Parameters

| Name | Description |
| --- | --- |
| **alignment** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) (default `'auto'`) | Sets the `rotationAlignment` property of the marker. |

##### Returns

[Marker](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker): Returns itself to allow for method chaining.

##### Example

```js
marker.setRotationAlignment('viewport');
```

#### getRotationAlignment()

Returns the current `rotationAlignment` property of the marker.

##### Returns

[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String): The current rotational alignment of the marker.

##### Example

```js
const alignment = marker.getRotationAlignment();
```

#### setPitchAlignment()

Sets the `pitchAlignment` property of the marker.

##### Parameters

| Name | Description |
| --- | --- |
| **alignment** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?  | Sets the `pitchAlignment` property of the marker. If alignment is 'auto', it will automatically match `rotationAlignment` . |

##### Returns

[Marker](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker): Returns itself to allow for method chaining.

##### Example

```js
marker.setPitchAlignment('map');
```

#### getPitchAlignment()

Returns the current `pitchAlignment` behavior of the marker.

##### Returns

[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String): The current pitch alignment of the marker.

##### Example

```js
const alignment = marker.getPitchAlignment();
```

#### setOccludedOpacity()

Sets the `occludedOpacity` property of the marker. This opacity is used on the marker when the marker is occluded by terrain.

##### Parameters

| Name | Description |
| --- | --- |
| **opacity** [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) (default `0.2`) | Sets the `occludedOpacity` property of the marker. |

##### Returns

[Marker](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker): Returns itself to allow for method chaining.

##### Example

```js
marker.setOccludedOpacity(0.3);
```

#### getOccludedOpacity()

Returns the current `occludedOpacity` of the marker.

##### Returns

[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number): The opacity of a terrain occluded marker.

##### Example

```js
const opacity = marker.getOccludedOpacity();
```

### Events

#### dragstart

Fired when dragging starts.

##### Type

[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)

##### Properties

| Name | Description |
| --- | --- |
| **marker** [Marker](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker)  | The object that is being dragged. |

#### drag

Fired while dragging.

##### Type

[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)

##### Properties

| Name | Description |
| --- | --- |
| **marker** [Marker](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker)  | The object that is being dragged. |

#### dragend

Fired when the marker is finished being dragged.

##### Type

[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)

##### Properties

| Name | Description |
| --- | --- |
| **marker** [Marker](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker)  | The object that was dragged. |

### Related

-   [Example: Add custom icons with Markers](https://www.mapbox.com/mapbox-gl-js/example/custom-marker-icons/)
-   [Example: Create a draggable Marker](https://www.mapbox.com/mapbox-gl-js/example/drag-a-marker/)

## NavigationControl

[Source Code](https://github.com/mapbox/mapbox-gl-js/blob/29a082c40985763b038163d555f9305cb39233ad/src/ui/control/navigation_control.ts#L41-L164)

A `NavigationControl` control contains zoom buttons and a compass. Add this control to a map using [Map#addControl](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map#addcontrol).

> new NavigationControl(options: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>?)

### Parameters

| Name | Description |
| --- | --- |
| **options** [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)? (default `{}`) |  |
| **options.showCompass** [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean) (default `true`) | If `true` the compass button is included. |
| **options.showZoom** [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean) (default `true`) | If `true` the zoom-in and zoom-out buttons are included. |
| **options.visualizePitch** [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean) (default `false`) | If `true` the pitch is visualized by rotating X-axis of compass. |

### Example

```js
const nav = new mapboxgl.NavigationControl();
map.addControl(nav, 'top-left');
```

```js
const nav = new mapboxgl.NavigationControl({
    visualizePitch: true
});
map.addControl(nav, 'bottom-right');
```

### Related

-   [Example: Display map navigation controls](https://www.mapbox.com/mapbox-gl-js/example/navigation/)
-   [Example: Add a third party vector tile source](https://www.mapbox.com/mapbox-gl-js/example/third-party/)

## Popup

[Source Code](https://github.com/mapbox/mapbox-gl-js/blob/29a082c40985763b038163d555f9305cb39233ad/src/ui/popup.ts#L112-L699)

A popup component.

Extends [Evented](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/events/#evented).

> new Popup(options: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>?)

### Parameters

<table class="table table--fixed table--compact" style="width:100%;table-layout:fixed"><colgroup><col width="28%"><col></colgroup><thead><tr class="bg-gray-faint"><th style="border-top-left-radius:4px">Name</th><th style="border-top-right-radius:4px">Description</th></tr></thead><tbody><tr><td><strong>options</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>?</span>&nbsp;</td><td><span></span></td></tr><tr><td><strong>options.altitude</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a></span>&nbsp;(default <code>0</code>)</td><td><span>Elevation in meters above the map surface. If terrain is enabled, the popup will be elevated relative to the terrain.</span></td></tr><tr><td><strong>options.anchor</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>?</span>&nbsp;</td><td><span>A string indicating the part of the popup that should be positioned closest to the coordinate, set via <a href="/mapbox-gl-js/api/markers/#popup#setlnglat">Popup#setLngLat</a> . Options are <code>'center'</code> , <code>'top'</code> , <code>'bottom'</code> , <code>'left'</code> , <code>'right'</code> , <code>'top-left'</code> , <code>'top-right'</code> , <code>'bottom-left'</code> , and <code>'bottom-right'</code> . If unset, the anchor will be dynamically set to ensure the popup falls within the map container with a preference for <code>'bottom'</code> .</span></td></tr><tr><td><strong>options.className</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>?</span>&nbsp;</td><td><span>Space-separated CSS class names to add to popup container.</span></td></tr><tr><td><strong>options.closeButton</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a></span>&nbsp;(default <code>true</code>)</td><td><span>If <code>true</code> , a close button will appear in the top right corner of the popup.</span></td></tr><tr><td><strong>options.closeOnClick</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a></span>&nbsp;(default <code>true</code>)</td><td><span>If <code>true</code> , the popup will close when the map is clicked.</span></td></tr><tr><td><strong>options.closeOnMove</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a></span>&nbsp;(default <code>false</code>)</td><td><span>If <code>true</code> , the popup will close when the map moves.</span></td></tr><tr><td><strong>options.focusAfterOpen</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a></span>&nbsp;(default <code>true</code>)</td><td><span>If <code>true</code> , the popup will try to focus the first focusable element inside the popup.</span></td></tr><tr><td><strong>options.maxWidth</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;(default <code>'240px'</code>)</td><td><span>A string that sets the CSS property of the popup's maximum width (for example, <code>'300px'</code> ). To ensure the popup resizes to fit its content, set this property to <code>'none'</code> . See the MDN documentation for the list of <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/max-width">available values</a> .</span></td></tr><tr><td><strong>options.offset</strong>&nbsp;<span>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a> | <a href="/mapbox-gl-js/api/geography/#pointlike">PointLike</a> | <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)?</span>&nbsp;</td><td><span>A pixel offset applied to the popup's location specified as:<ul><li>a single number specifying a distance from the popup's location</li><li>a <a href="/mapbox-gl-js/api/geography/#pointlike">PointLike</a> specifying a constant offset</li><li>an object of <a href="/mapbox-gl-js/api/geography/#point">Point</a>s specifing an offset for each anchor position.</li></ul><p>Negative offsets indicate left and up.</p></span></td></tr></tbody></table>

### Example

```js
const markerHeight = 50;
const markerRadius = 10;
const linearOffset = 25;
const 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]
};
const popup = new mapboxgl.Popup({offset: popupOffsets, className: 'my-class'})
    .setLngLat(e.lngLat)
    .setHTML("<h1>Hello World!</h1>")
    .setMaxWidth("300px")
    .addTo(map);
```

### Instance Members

#### addTo()

Adds the popup to a map.

##### Parameters

| Name | Description |
| --- | --- |
| **map** [Map](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map)  | The Mapbox GL JS map to add the popup to. |

##### Returns

[Popup](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup): Returns itself to allow for method chaining.

##### Example

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

##### Related

-   [Example: Display a popup](https://docs.mapbox.com/mapbox-gl-js/example/popup/)
-   [Example: Display a popup on hover](https://docs.mapbox.com/mapbox-gl-js/example/popup-on-hover/)
-   [Example: Display a popup on click](https://docs.mapbox.com/mapbox-gl-js/example/popup-on-click/)
-   [Example: Show polygon information on click](https://docs.mapbox.com/mapbox-gl-js/example/polygon-popup-on-click/)

#### isOpen()

Checks if a popup is open.

##### Returns

[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean): `true` if the popup is open, `false` if it is closed.

##### Example

```js
const isPopupOpen = popup.isOpen();
```

#### remove()

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

##### Returns

[Popup](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup): Returns itself to allow for method chaining.

##### Example

```js
const popup = new mapboxgl.Popup().addTo(map);
popup.remove();
```

#### getLngLat()

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.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/geography/#lnglat): The geographical location of the popup's anchor.

##### Example

```js
const lngLat = popup.getLngLat();
```

#### setLngLat()

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

##### Parameters

| Name | Description |
| --- | --- |
| **lnglat** [LngLatLike](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/geography/#lnglatlike)  | The geographical location to set as the popup's anchor. |

##### Returns

[Popup](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup): Returns itself to allow for method chaining.

##### Example

```js
popup.setLngLat([-122.4194, 37.7749]);
```

#### getAltitude()

Gets the altitude of the popup.

##### Returns

[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number): The altitude of the popup.

##### Example

```js
const altitude = popup.getAltitude();
```

#### setAltitude()

Sets the altitude of the popup.

##### Parameters

| Name | Description |
| --- | --- |
| **altitude** [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)  | The altitude of the popup. |

##### Returns

[Popup](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup): Returns itself to allow for method chaining.

##### Example

```js
popup.setAltitude(10);
```

#### trackPointer()

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

[Popup](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup): Returns itself to allow for method chaining.

##### Example

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

#### getElement()

Returns the `Popup`'s HTML element.

##### Returns

[HTMLElement](https://developer.mozilla.org/docs/Web/HTML/Element): Returns container element.

##### Example

```js
// Change the `Popup` element's font size
const popup = new mapboxgl.Popup()
    .setLngLat([-96, 37.8])
    .setHTML("<p>Hello World!</p>")
    .addTo(map);
const popupElem = popup.getElement();
popupElem.style.fontSize = "25px";
```

#### setText()

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

| Name | Description |
| --- | --- |
| **text** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | Textual content for the popup. |

##### Returns

[Popup](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup): Returns itself to allow for method chaining.

##### Example

```js
const popup = new mapboxgl.Popup()
    .setLngLat(e.lngLat)
    .setText('Hello, world!')
    .addTo(map);
```

#### setHTML()

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.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup#settext) if the content is an untrusted text string.

##### Parameters

| Name | Description |
| --- | --- |
| **html** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | A string representing HTML content for the popup. |

##### Returns

[Popup](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup): Returns itself to allow for method chaining.

##### Example

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

##### Related

-   [Example: Display a popup](https://docs.mapbox.com/mapbox-gl-js/example/popup/)
-   [Example: Display a popup on hover](https://docs.mapbox.com/mapbox-gl-js/example/popup-on-hover/)
-   [Example: Display a popup on click](https://docs.mapbox.com/mapbox-gl-js/example/popup-on-click/)
-   [Example: Attach a popup to a marker instance](https://docs.mapbox.com/mapbox-gl-js/example/set-popup/)

#### getMaxWidth()

Returns the popup's maximum width.

##### Returns

[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String): The maximum width of the popup.

##### Example

```js
const maxWidth = popup.getMaxWidth();
```

#### setMaxWidth()

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

| Name | Description |
| --- | --- |
| **maxWidth** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | A string representing the value for the maximum width. |

##### Returns

[Popup](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup): Returns itself to allow for method chaining.

##### Example

```js
popup.setMaxWidth('50');
```

#### setDOMContent()

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

##### Parameters

| Name | Description |
| --- | --- |
| **htmlNode** [Element](https://developer.mozilla.org/docs/Web/API/Element)  | A DOM node to be used as content for the popup. |

##### Returns

[Popup](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup): Returns itself to allow for method chaining.

##### Example

```js
// create an element with the popup content
const div = window.document.createElement('div');
div.innerHTML = 'Hello, world!';
const popup = new mapboxgl.Popup()
    .setLngLat(e.lngLat)
    .setDOMContent(div)
    .addTo(map);
```

#### addClassName()

Adds a CSS class to the popup container element.

##### Parameters

| Name | Description |
| --- | --- |
| **className** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | Non-empty string with CSS class name to add to popup container. |

##### Returns

[Popup](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup): Returns itself to allow for method chaining.

##### Example

```js
const popup = new mapboxgl.Popup();
popup.addClassName('some-class');
```

#### removeClassName()

Removes a CSS class from the popup container element.

##### Parameters

| Name | Description |
| --- | --- |
| **className** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | Non-empty string with CSS class name to remove from popup container. |

##### Returns

[Popup](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup): Returns itself to allow for method chaining.

##### Example

```js
const popup = new mapboxgl.Popup({className: 'some classes'});
popup.removeClassName('some');
```

#### setOffset()

Sets the popup's offset.

##### Parameters

| Name | Description |
| --- | --- |
| **offset** ([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [PointLike](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/geography/#pointlike) \| [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object))  | Sets the popup's offset. The `Object` is of the following structure { 'center': ?PointLike, 'top': ?PointLike, 'bottom': ?PointLike, 'left': ?PointLike, 'right': ?PointLike, 'top-left': ?PointLike, 'top-right': ?PointLike, 'bottom-left': ?PointLike, 'bottom-right': ?PointLike }. |

##### Returns

[Popup](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup): `this` .

##### Example

```js
popup.setOffset(10);
```

#### toggleClassName()

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

##### Parameters

| Name | Description |
| --- | --- |
| **className** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | Non-empty string with CSS class name to add/remove. |

##### Returns

[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean): If the class was removed return `false` . If the class was added, then return `true` .

##### Example

```js
const popup = new mapboxgl.Popup();
popup.toggleClassName('highlighted');
```

### Events

#### open

Fired when the popup is opened manually or programatically.

##### Type

[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)

##### Properties

| Name | Description |
| --- | --- |
| **popup** [Popup](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup)  | Object that was opened. |

##### Example

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

#### close

Fired when the popup is closed manually or programatically.

##### Type

[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)

##### Properties

| Name | Description |
| --- | --- |
| **popup** [Popup](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup)  | Object that was closed. |

##### Example

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

### Related

-   [Example: Display a popup](https://www.mapbox.com/mapbox-gl-js/example/popup/)
-   [Example: Display a popup on hover](https://www.mapbox.com/mapbox-gl-js/example/popup-on-hover/)
-   [Example: Display a popup on click](https://www.mapbox.com/mapbox-gl-js/example/popup-on-click/)
-   [Example: Attach a popup to a marker instance](https://www.mapbox.com/mapbox-gl-js/example/set-popup/)

## ScaleControl

[Source Code](https://github.com/mapbox/mapbox-gl-js/blob/29a082c40985763b038163d555f9305cb39233ad/src/ui/control/scale_control.ts#L43-L144)

A `ScaleControl` control displays the ratio of a distance on the map to the corresponding distance on the ground. Add this control to a map using [Map#addControl](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map#addcontrol).

> new ScaleControl(options: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>?)

### Parameters

| Name | Description |
| --- | --- |
| **options** [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)? (default `{}`) |  |
| **options.maxWidth** [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) (default `'100'`) | The maximum length of the scale control in pixels. |
| **options.unit** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) (default `'metric'`) | Unit of the distance ( `'imperial'` , `'metric'` or `'nautical'` ). |

### Example

```js
const scale = new mapboxgl.ScaleControl({
    maxWidth: 80,
    unit: 'imperial'
});
map.addControl(scale);

scale.setUnit('metric');
```

### Instance Members

#### setUnit()

Set the scale's unit of the distance.

##### Parameters

| Name | Description |
| --- | --- |
| **unit** (`"imperial"` \| `"metric"` \| `"nautical"`)  | Unit of the distance ( `'imperial'` , `'metric'` or `'nautical'` ). |
Name	Description
options Object?
options.altitude number (default `0`)	Elevation in meters above the map surface. If terrain is enabled, the popup will be elevated relative to the terrain.
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.className string?	Space-separated CSS class names to add to popup container.
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 close when the map is clicked.
options.closeOnMove boolean (default `false`)	If `true` , the popup will close 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.maxWidth string (default `'240px'`)	A string that sets the CSS property of the popup's maximum width (for example, `'300px'` ). To ensure the popup resizes to fit its content, set this property to `'none'` . See the MDN documentation for the list of available values .
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.