# Class: Overlay

This documentation is for OpenLayers v10.9.0. The latest is v.

## ol/Overlay~Overlay

    import Overlay from 'ol/Overlay.js';

An element to be displayed over the map and attached to a single map location. Like `Control`, Overlays are visible widgets. Unlike Controls, they are not in a fixed position on the screen, but are tied to a geographical coordinate, so panning the map will move an Overlay but not a Control.

Example:

    import Overlay from 'ol/Overlay.js';

    // ...
    const popup = new Overlay({
      element: document.getElementById('popup'),
    });
    popup.setPosition(coordinate);
    map.addOverlay(popup);

#### new Overlay(options)

Overlay.js, line 112

  Name | Type | Description
  --- | --- | ---
  `id` | number | string | undefined | Set the overlay id. The overlay id can be used with the `getOverlayById` method.
  `element` | HTMLElement | undefined | The overlay element.
  `offset` | Array.<number> (defaults to [0, 0]) | Offsets in pixels used when positioning the overlay. The first element in the array is the horizontal offset. A positive value shifts the overlay right. The second element in the array is the vertical offset. A positive value shifts the overlay down.
  `position` | Coordinate | undefined | The overlay position in map projection.
  `positioning` | Positioning (defaults to 'top-left') | Defines how the overlay is actually positioned with respect to its `position` property. Possible values are `'bottom-left'`, `'bottom-center'`, `'bottom-right'`, `'center-left'`, `'center-center'`, `'center-right'`, `'top-left'`, `'top-center'`, and `'top-right'`.
  `stopEvent` | boolean (defaults to true) | Whether event propagation to the map viewport should be stopped. If `true` the overlay is placed in the same container as that of the controls (CSS class name `ol-overlaycontainer-stopevent`); if `false` it is placed in the container with CSS class name specified by the `className` property.
  `insertFirst` | boolean (defaults to true) | Whether the overlay is inserted first in the overlay container, or appended. If the overlay is placed in the same container as that of the controls (see the `stopEvent` option) you will probably set `insertFirst` to `true` so the overlay is displayed below the controls.
  `autoPan` | PanIntoViewOptions | boolean (defaults to false) | Pan the map when calling `setPosition`, so that the overlay is entirely visible in the current viewport.
  `className` | string (defaults to 'ol-overlay-container ol-selectable') | CSS class name.

  ##### Fires:

  - `change` (BaseEvent) - Generic change event. Triggered when the revision counter is increased.
  - `change:element` (ObjectEvent)
  - `change:map` (ObjectEvent)
  - `change:offset` (ObjectEvent)
  - `change:position` (ObjectEvent)
  - `change:positioning` (ObjectEvent)
  - `error` (BaseEvent) - Generic error event. Triggered when an error occurs.
  - `propertychange` (ObjectEvent) - Triggered when a property is changed.

### Extends

- BaseObject

### Observable Properties

Name | Type | Settable | ObjectEvent type | Description
--- | --- | --- | --- | ---
`element` | HTMLElement | undefined | yes | `change:element` | The Element containing the overlay.
`map` | Map | null | yes | `change:map` | The map that the overlay is part of.
`offset` | Array.<number> | yes | `change:offset` | The offset.
`position` | Coordinate | undefined | yes | `change:position` | The spatial point that the overlay is anchored at.
`positioning` | Positioning | yes | `change:positioning` | How the overlay is positioned relative to its point on the map.

### Methods

#### changed() inherited

Observable.js, line 68

  Increases the revision counter and dispatches a 'change' event.

#### dispatchEvent(event){boolean | undefined} inherited

events/Target.js, line 85

  Dispatches an event and calls all listeners listening for events of this type. The event parameter can either be a string or an Object with a `type` property.

  Name | Type | Description
  --- | --- | ---
  `event` | BaseEvent | string | Event object.

  ##### Returns:

  `false` if anyone called preventDefault on the event object or if any of the listeners returned false.

#### get(key){*} inherited

Object.js, line 136

  Gets a value.

  Name | Type | Description
  --- | --- | ---
  `key` | string | Key name.

  ##### Returns:

  Value.

#### getElement(){HTMLElement | undefined}

Overlay.js, line 218

  Get the DOM element of this overlay.

  ##### Returns:

  The Element containing the overlay.

#### getId(){number | string | undefined}

Overlay.js, line 227

  Get the overlay identifier which is set on constructor.

  ##### Returns:

  Id.

#### getKeys(){Array.<string>} inherited

Object.js, line 149

  Get a list of object property names.

  ##### Returns:

  List of property names.

#### getMap(){Map | null}

Overlay.js, line 238

  Get the map associated with this overlay.

  ##### Returns:

  The map that the overlay is part of.

#### getOffset(){Array.<number>}

Overlay.js, line 250

  Get the offset of this overlay.

  ##### Returns:

  The offset.

#### getPosition(){Coordinate | undefined}

Overlay.js, line 261

  Get the current position of this overlay.

  ##### Returns:

  The spatial point that the overlay is anchored at.

#### getPositioning(){Positioning}

Overlay.js, line 274

  Get the current positioning of this overlay.

  ##### Returns:

  How the overlay is positioned relative to its point on the map.

#### getProperties(){NoInfer.<Properties>} inherited

Object.js, line 158

  Get an object of all property names and values.

  ##### Returns:

  Object.

#### getRevision(){number} inherited

Observable.js, line 79

  Get the version number for this object. Each time the object is modified, its version number will be incremented.

  ##### Returns:

  Revision.

#### on(type, listener){EventsKey | Array<EventsKey>} inherited

Observable.js, line 152

  Listen for a certain type of event.

  Name | Type | Description
  --- | --- | ---
  `type` | string | Array.<string> | The event type or array of event types.
  `listener` | function | The listener function.

  ##### Returns:

  Unique key for the listener. If called with an array of event types as the first argument, the return will be an array of keys.

#### once(type, listener){EventsKey | Array<EventsKey>} inherited

Observable.js, line 164

  Listen once for a certain type of event.

  Name | Type | Description
  --- | --- | ---
  `type` | string | Array.<string> | The event type or array of event types.
  `listener` | function | The listener function.

  ##### Returns:

  Unique key for the listener. If called with an array of event types as the first argument, the return will be an array of keys.

#### panIntoView(panIntoViewOptions)

Overlay.js, line 408

  Pan the map so that the overlay is entirely visible in the current viewport (if necessary).

  Name | Type | Description
  --- | --- | ---
  `panIntoViewOptions` | Options for the pan action
  Name | Type | Description
  --- | --- | ---
  `animation` | PanOptions (defaults to {}) | The animation parameters for the pan
  `margin` | number (defaults to 20) | The margin (in pixels) between the overlay and the borders of the map when panning into view.

#### set(key, value, silent) inherited

Object.js, line 218

  Sets a value.

  Name | Type | Description
  --- | --- | ---
  `key` | string | Key name.
  `value` | * | Value.
  `silent` | boolean | undefined | Update without triggering an event.

#### setElement(element)

Overlay.js, line 354

  Set the DOM element to be associated with this overlay.

  Name | Type | Description
  --- | --- | ---
  `element` | HTMLElement | undefined | The Element containing the overlay.

#### setMap(map)

Overlay.js, line 365

  Set the map to be associated with this overlay.

  Name | Type | Description
  --- | --- | ---
  `map` | Map | null | The map that the overlay is part of. Pass `null` to just remove the overlay from the current map.

#### setOffset(offset)

Overlay.js, line 375

  Set the offset for this overlay.

  Name | Type | Description
  --- | --- | ---
  `offset` | Array.<number> | Offset.

#### setPosition(position)

Overlay.js, line 387

  Set the position for this overlay. If the position is `undefined` the overlay is hidden.

  Name | Type | Description
  --- | --- | ---
  `position` | Coordinate | undefined | The spatial point that the overlay is anchored at.

#### setPositioning(positioning)

Overlay.js, line 490

  Set the positioning for this overlay.

  Name | Type | Description
  --- | --- | ---
  `positioning` | Positioning | how the overlay is positioned relative to its point on the map.

#### setProperties(values, silent) inherited

Object.js, line 238

  Sets a collection of key-value pairs. Note that this changes any existing properties and adds new ones (it does not remove any existing properties).

  Name | Type | Description
  --- | --- | ---
  `values` | Partial.<NoInfer.<Properties>> | Values.
  `silent` | boolean | undefined | Update without triggering an event.

#### un(type, listener) inherited

Observable.js, line 173

  Unlisten for a certain type of event.

  Name | Type | Description
  --- | --- | ---
  `type` | string | Array.<string> | The event type or array of event types.
  `listener` | function | The listener function.

#### unset(key, silent) inherited

Object.js, line 262

  Unsets a property.

  Name | Type | Description
  --- | --- | ---
  `key` | string | Key name.
  `silent` | boolean | undefined | Unset without triggering an event.