OpenLayers v4.0.1 API - Class: Overlay

# Class: Overlay

This documentation is for OpenLayers v4.0.1. The latest is v.

## ol.Overlay

An element to be displayed over the map and attached to a single map location. Like `ol.control.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:

    var popup = new ol.Overlay({
      element: document.getElementById('popup')
    });
    popup.setPosition(coordinate);
    map.addOverlay(popup);

#### new ol.Overlay(options)

src/ol/overlay.js, line 33

  Name | Type | Description
  --- | --- | ---

  `options`

  Overlay options.

  Name | Type | Description
  --- | --- | ---
  `id` | number | string | undefined | Set the overlay id. The overlay id can be used with the `ol.Map#getOverlayById` method.
  `element` | Element | undefined | The overlay element.
  `offset` | Array.<number> | undefined | 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. Default is `[0, 0]`.
  `position` | ol.Coordinate | undefined | The overlay position in map projection.
  `positioning` | ol.OverlayPositioning | string | undefined | 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'`. Default is `'top-left'`.
  `stopEvent` | boolean | undefined | Whether event propagation to the map viewport should be stopped. Default is `true`. 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 `ol-overlaycontainer`.
  `insertFirst` | boolean | undefined | Whether the overlay is inserted first in the overlay container, or appended. Default is `true`. 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` | boolean | undefined | If set to `true` the map is panned when calling `setPosition`, so that the overlay is entirely visible in the current viewport. The default is `false`.
  `autoPanAnimation` | olx.OverlayPanOptions | undefined | The animation options used to pan the overlay into view. This animation is only used when `autoPan` is enabled. A `duration` and `easing` may be provided to customize the animation.
  `autoPanMargin` | number | undefined | The margin (in pixels) between the overlay and the borders of the map when autopanning. The default is `20`.

  ##### Fires:

  - `change` (ol.events.Event) - Generic change event. Triggered when the revision counter is increased.
  - `change:element` (ol.Object.Event)
  - `change:map` (ol.Object.Event)
  - `change:offset` (ol.Object.Event)
  - `change:position` (ol.Object.Event)
  - `change:positioning` (ol.Object.Event)
  - `propertychange` (ol.Object.Event) - Triggered when a property is changed.

### Extends

- ol.Object

### Observable Properties

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

### Methods

#### changed() inherited

src/ol/observable.js, line 58

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

#### dispatchEvent(event) inherited

src/ol/observable.js, line 75

  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` | Object | ol.events.Event | string | Event object.

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

src/ol/object.js, line 101

  Gets a value.

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

  ##### Returns:

  Value.

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

src/ol/overlay.js, line 150

  Get the DOM element of this overlay.

  ##### Returns:

  The Element containing the overlay.

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

src/ol/overlay.js, line 161

  Get the overlay identifier which is set on constructor.

  ##### Returns:

  Id.

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

src/ol/object.js, line 115

  Get a list of object property names.

  ##### Returns:

  List of property names.

#### getMap(){ol.Map|undefined}

src/ol/overlay.js, line 172

  Get the map associated with this overlay.

  ##### Returns:

  The map that the overlay is part of.

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

src/ol/overlay.js, line 184

  Get the offset of this overlay.

  ##### Returns:

  The offset.

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

src/ol/overlay.js, line 197

  Get the current position of this overlay.

  ##### Returns:

  The spatial point that the overlay is anchored at.

#### getPositioning(){ol.OverlayPositioning}

src/ol/overlay.js, line 210

  Get the current positioning of this overlay.

  ##### Returns:

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

#### getProperties(){Object.<string, *>} inherited

src/ol/object.js, line 125

  Get an object of all property names and values.

  ##### Returns:

  Object.

#### getRevision(){number} inherited

src/ol/observable.js, line 84

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

  ##### Returns:

  Revision.

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

src/ol/observable.js, line 99

  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.
  `this` | Object | The object to use as `this` in `listener`.

  ##### 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, opt_this){ol.EventsKey|Array.<ol.EventsKey>} inherited

src/ol/observable.js, line 124

  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.
  `this` | Object | The object to use as `this` in `listener`.

  ##### 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.

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

src/ol/object.js, line 150

  Sets a value.

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

#### setElement(element)

src/ol/overlay.js, line 294

  Set the DOM element to be associated with this overlay.

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

#### setMap(map)

src/ol/overlay.js, line 305

  Set the map to be associated with this overlay.

  Name | Type | Description
  --- | --- | ---
  `map` | ol.Map | undefined | The map that the overlay is part of.

#### setOffset(offset)

src/ol/overlay.js, line 316

  Set the offset for this overlay.

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

#### setPosition(position)

src/ol/overlay.js, line 329

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

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

#### setPositioning(positioning)

src/ol/overlay.js, line 420

  Set the positioning for this overlay.

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

#### setProperties(values, opt_silent) inherited

src/ol/object.js, line 170

  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` | Object.<string, *> | Values.
  `silent` | boolean | Update without triggering an event.

#### un(type, listener, opt_this) inherited

src/ol/observable.js, line 147

  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.
  `this` | Object | The object which was used as `this` by the `listener`.

#### unset(key, opt_silent) inherited

src/ol/object.js, line 184

  Unsets a property.

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