OpenLayers v4.0.1 API - Class: Map

# Class: Map

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

## ol.Map

The map is the core component of OpenLayers. For a map to render, a view, one or more layers, and a target container are needed:

    var map = new ol.Map({
      view: new ol.View({
        center: [0, 0],
        zoom: 1
      }),
      layers: [
        new ol.layer.Tile({
          source: new ol.source.OSM()
        })
      ],
      target: 'map'
    });

The above snippet creates a map using a `ol.layer.Tile` to display `ol.source.OSM` OSM data and render it to a DOM element with the id `map`.

The constructor places a viewport container (with CSS class name `ol-viewport`) in the target element (see `getViewport()`), and then two further elements within the viewport: one with CSS class name `ol-overlaycontainer-stopevent` for controls and some overlays, and one with CSS class name `ol-overlaycontainer` for other overlays (see the `stopEvent` option of `ol.Overlay` for the difference). The map itself is placed in a further element within the viewport.

Layers are stored as a `ol.Collection` in layerGroups. A top-level group is provided by the library. This is what is accessed by `getLayerGroup` and `setLayerGroup`. Layers entered in the options are added to this group, and `addLayer` and `removeLayer` change the layer collection in the group. `getLayers` is a convenience function for `getLayerGroup().getLayers()`. Note that `ol.layer.Group` is a subclass of `ol.layer.Base`, so layers entered in the options or added with `addLayer` can be groups, which can contain further groups, and so on.

#### new ol.Map(options)

src/ol/map.js, line 136

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

  `options`

  Map options.

  Name | Type | Description
  --- | --- | ---
  `controls` | ol.Collection.<ol.control.Control> | Array.<ol.control.Control> | undefined | Controls initially added to the map. If not specified, `ol.control.defaults()` is used.
  `pixelRatio` | number | undefined | The ratio between physical pixels and device-independent pixels (dips) on the device. If `undefined` then it gets set by using `window.devicePixelRatio`.
  `interactions` | ol.Collection.<ol.interaction.Interaction> | Array.<ol.interaction.Interaction> | undefined | Interactions that are initially added to the map. If not specified, `ol.interaction.defaults()` is used.
  `keyboardEventTarget` | Element | Document | string | undefined | The element to listen to keyboard events on. This determines when the `KeyboardPan` and `KeyboardZoom` interactions trigger. For example, if this option is set to `document` the keyboard interactions will always trigger. If this option is not specified, the element the library listens to keyboard events on is the map target (i.e. the user-provided div for the map). If this is not `document` the target element needs to be focused for key events to be emitted, requiring that the target element has a `tabindex` attribute.
  `layers` | Array.<ol.layer.Base> | ol.Collection.<ol.layer.Base> | undefined | Layers. If this is not defined, a map with no layers will be rendered. Note that layers are rendered in the order supplied, so if you want, for example, a vector layer to appear on top of a tile layer, it must come after the tile layer.
  `loadTilesWhileAnimating` | boolean | undefined | When set to true, tiles will be loaded during animations. This may improve the user experience, but can also make animations stutter on devices with slow memory. Default is `false`.
  `loadTilesWhileInteracting` | boolean | undefined | When set to true, tiles will be loaded while interacting with the map. This may improve the user experience, but can also make map panning and zooming choppy on devices with slow memory. Default is `false`.
  `logo` | boolean | string | olx.LogoOptions | Element | undefined | The map logo. A logo to be displayed on the map at all times. If a string is provided, it will be set as the image source of the logo. If an object is provided, the `src` property should be the URL for an image and the `href` property should be a URL for creating a link. If an element is provided, the element will be used. To disable the map logo, set the option to `false`. By default, the OpenLayers logo is shown.
  `overlays` | ol.Collection.<ol.Overlay> | Array.<ol.Overlay> | undefined | Overlays initially added to the map. By default, no overlays are added.
  `renderer` | ol.renderer.Type | Array.<ol.renderer.Type> | undefined | Renderer. By default, Canvas and WebGL renderers are tested for support in that order, and the first supported used. Specify a `ol.renderer.Type` here to use a specific renderer. Note that the Canvas renderer fully supports vector data, but WebGL can only render Point geometries.
  `target` | Element | string | undefined | The container for the map, either the element itself or the `id` of the element. If not specified at construction time, `ol.Map#setTarget` must be called for the map to be rendered.
  `view` | ol.View | undefined | The map's view. No layer sources will be fetched unless this is specified at construction time or through `ol.Map#setView`.

  ##### Fires:

  - `change` (ol.events.Event) - Generic change event. Triggered when the revision counter is increased.
  - `change:layerGroup` (ol.Object.Event)
  - `change:size` (ol.Object.Event)
  - `change:target` (ol.Object.Event)
  - `change:view` (ol.Object.Event)
  - `click` (ol.MapBrowserEvent) - A click with no dragging. A double click will fire two of this.
  - `dblclick` (ol.MapBrowserEvent) - A true double click, with no dragging.
  - `moveend` (ol.MapEvent) - Triggered after the map is moved.
  - `pointerdrag` (ol.MapBrowserEvent) - Triggered when a pointer is dragged.
  - `pointermove` (ol.MapBrowserEvent) - Triggered when a pointer is moved. Note that on touch devices this is triggered when the map is panned, so is not the same as mousemove.
  - `postcompose` (ol.render.Event)
  - `postrender` (ol.MapEvent) - Triggered after a map frame is rendered.
  - `precompose` (ol.render.Event)
  - `propertychange` (ol.Object.Event) - Triggered when a property is changed.
  - `singleclick` (ol.MapBrowserEvent) - A true single click with no dragging and no double click. Note that this event is delayed by 250 ms to ensure that it is not a double click.

### Extends

- ol.Object

### Observable Properties

Name | Type | Settable | ol.Object.Event type | Description
--- | --- | --- | --- | ---
`layerGroup` | ol.layer.Group | yes | `change:layergroup` | A layer group containing the layers in this map.
`size` | ol.Size | undefined | yes | `change:size` | The size in pixels of the map in the DOM.
`target` | Element | string | undefined | yes | `change:target` | The Element or id of the Element that the map is rendered in.
`view` | ol.View | yes | `change:view` | The view that controls this map.

### Methods

#### addControl(control)

src/ol/map.js, line 465

  Add the given control to the map.

  Name | Type | Description
  --- | --- | ---
  `control` | ol.control.Control | Control.

#### addInteraction(interaction)

src/ol/map.js, line 475

  Add the given interaction to the map.

  Name | Type | Description
  --- | --- | ---
  `interaction` | ol.interaction.Interaction | Interaction to add.

#### addLayer(layer)

src/ol/map.js, line 487

  Adds the given layer to the top of this map. If you want to add a layer elsewhere in the stack, use `getLayers()` and the methods available on `ol.Collection`.

  Name | Type | Description
  --- | --- | ---
  `layer` | ol.layer.Base | Layer.

#### addOverlay(overlay)

src/ol/map.js, line 498

  Add the given overlay to the map.

  Name | Type | Description
  --- | --- | ---
  `overlay` | ol.Overlay | Overlay.

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

#### forEachFeatureAtPixel(pixel, callback, opt_options){T|undefined}

src/ol/map.js, line 561

  Detect features that intersect a pixel on the viewport, and execute a callback with each intersecting feature. Layers included in the detection can be configured through `opt_layerFilter`.

  Name | Type | Description
  --- | --- | ---
  `pixel` | ol.Pixel | Pixel.
  `callback` | function | Feature callback. The callback will be called with two arguments. The first argument is one `feature` or `render feature` at the pixel, the second is the `layer` of the feature and will be null for unmanaged layers. To stop detection, callback functions can return a truthy value.

  `options`

  Optional options.

  Name | Type | Description
  --- | --- | ---
  `layerFilter` | function | undefined | Layer filter function. The filter function will receive one argument, the `layer-candidate` and it should return a boolean value. Only layers which are visible and for which this function returns `true` will be tested for features. By default, all visible layers will be tested.
  `hitTolerance` | number | undefined | Hit-detection tolerance in pixels. Pixels inside the radius around the given position will be checked for features. This only works for the canvas renderer and not for WebGL. Default is `0`.

  ##### Returns:

  Callback result, i.e. the return value of last callback execution, or the first truthy callback return value.

#### forEachLayerAtPixel(pixel, callback, opt_this, opt_layerFilter, opt_this2){T|undefined}

src/ol/map.js, line 601

  Detect layers that have a color value at a pixel on the viewport, and execute a callback with each matching layer. Layers included in the detection can be configured through `opt_layerFilter`.

  Name | Type | Description
  --- | --- | ---
  `pixel` | ol.Pixel | Pixel.
  `callback` | function | Layer callback. This callback will recieve two arguments: first is the `layer`, second argument is an array representing [R, G, B, A] pixel values (0 - 255) and will be `null` for layer types that do not currently support this argument. To stop detection, callback functions can return a truthy value.
  `this` | S | Value to use as `this` when executing `callback`.
  `layerFilter` | function | Layer filter function. The filter function will receive one argument, the `layer-candidate` and it should return a boolean value. Only layers which are visible and for which this function returns `true` will be tested for features. By default, all visible layers will be tested.
  `this2` | U | Value to use as `this` when executing `layerFilter`.

  ##### Returns:

  Callback result, i.e. the return value of last callback execution, or the first truthy callback return value.

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

src/ol/object.js, line 101

  Gets a value.

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

  ##### Returns:

  Value.

#### getControls(){ol.Collection.<ol.control.Control>}

src/ol/map.js, line 723

  Get the map controls. Modifying this collection changes the controls associated with the map.

  ##### Returns:

  Controls.

#### getCoordinateFromPixel(pixel){ol.Coordinate}

src/ol/map.js, line 707

  Get the coordinate for a given pixel. This returns a coordinate in the map view projection.

  Name | Type | Description
  --- | --- | ---
  `pixel` | ol.Pixel | Pixel position in the map viewport.

  ##### Returns:

  The coordinate for the pixel position.

#### getEventCoordinate(event){ol.Coordinate}

src/ol/map.js, line 645

  Returns the coordinate in view projection for a browser event.

  Name | Type | Description
  --- | --- | ---
  `event` | Event | Event.

  ##### Returns:

  Coordinate.

#### getEventPixel(event){ol.Pixel}

src/ol/map.js, line 656

  Returns the map pixel position for a browser event relative to the viewport.

  Name | Type | Description
  --- | --- | ---
  `event` | Event | Event.

  ##### Returns:

  Pixel.

#### getInteractions(){ol.Collection.<ol.interaction.Interaction>}

src/ol/map.js, line 761

  Get the map interactions. Modifying this collection changes the interactions associated with the map.

  Interactions are used for e.g. pan, zoom and rotate.

  ##### Returns:

  Interactions.

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

src/ol/object.js, line 115

  Get a list of object property names.

  ##### Returns:

  List of property names.

#### getLayerGroup(){ol.layer.Group}

src/ol/map.js, line 772

  Get the layergroup associated with this map.

  ##### Returns:

  A layer group containing the layers in this map.

#### getLayers(){ol.Collection.<ol.layer.Base>}

src/ol/map.js, line 782

  Get the collection of layers associated with this map.

  ##### Returns:

  Layers.

#### getOverlayById(id){ol.Overlay}

src/ol/map.js, line 747

  Get an overlay by its identifier (the value returned by overlay.getId()). Note that the index treats string and numeric identifiers as the same. So `map.getOverlayById(2)` will return an overlay with id `'2'` or `2`.

  Name | Type | Description
  --- | --- | ---
  `id` | string | number | Overlay identifier.

  ##### Returns:

  Overlay.

#### getOverlays(){ol.Collection.<ol.Overlay>}

src/ol/map.js, line 734

  Get the map overlays. Modifying this collection changes the overlays associated with the map.

  ##### Returns:

  Overlays.

#### getPixelFromCoordinate(coordinate){ol.Pixel}

src/ol/map.js, line 795

  Get the pixel for a coordinate. This takes a coordinate in the map view projection and returns the corresponding pixel.

  Name | Type | Description
  --- | --- | ---
  `coordinate` | ol.Coordinate | A map coordinate.

  ##### Returns:

  A pixel position in the map viewport.

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

#### getSize(){ol.Size|undefined}

src/ol/map.js, line 821

  Get the size of this map.

  ##### Returns:

  The size in pixels of the map in the DOM.

#### getTarget(){Element|string|undefined}

src/ol/map.js, line 675

  Get the target in which this map is rendered. Note that this returns what is entered as an option or in setTarget: if that was an element, it returns an element; if a string, it returns that.

  ##### Returns:

  The Element or id of the Element that the map is rendered in.

#### getTargetElement(){Element}

src/ol/map.js, line 688

  Get the DOM element into which this map is rendered. In contrast to `getTarget` this method always return an `Element`, or `null` if the map has no target.

  ##### Returns:

  The element that the map is rendered in.

#### getView(){ol.View}

src/ol/map.js, line 833

  Get the view associated with this map. A view manages properties such as center and resolution.

  ##### Returns:

  The view that controls this map.

#### getViewport(){Element}

src/ol/map.js, line 843

  Get the element that serves as the map viewport.

  ##### Returns:

  Viewport.

#### hasFeatureAtPixel(pixel, opt_options){boolean}

src/ol/map.js, line 624

  Detect if features intersect a pixel on the viewport. Layers included in the detection can be configured through `opt_layerFilter`.

  Name | Type | Description
  --- | --- | ---
  `pixel` | ol.Pixel | Pixel.

  `options`

  Optional options.

  Name | Type | Description
  --- | --- | ---
  `layerFilter` | function | undefined | Layer filter function. The filter function will receive one argument, the `layer-candidate` and it should return a boolean value. Only layers which are visible and for which this function returns `true` will be tested for features. By default, all visible layers will be tested.
  `hitTolerance` | number | undefined | Hit-detection tolerance in pixels. Pixels inside the radius around the given position will be checked for features. This only works for the canvas renderer and not for WebGL. Default is `0`.

  ##### Returns:

  Is there a feature at the given pixel?

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

#### removeControl(control){ol.control.Control|undefined}

src/ol/map.js, line 1152

  Remove the given control from the map.

  Name | Type | Description
  --- | --- | ---
  `control` | ol.control.Control | Control.

  ##### Returns:

  The removed control (or undefined if the control was not found).

#### removeInteraction(interaction){ol.interaction.Interaction|undefined}

src/ol/map.js, line 1164

  Remove the given interaction from the map.

  Name | Type | Description
  --- | --- | ---
  `interaction` | ol.interaction.Interaction | Interaction to remove.

  ##### Returns:

  The removed interaction (or undefined if the interaction was not found).

#### removeLayer(layer){ol.layer.Base|undefined}

src/ol/map.js, line 1176

  Removes the given layer from the map.

  Name | Type | Description
  --- | --- | ---
  `layer` | ol.layer.Base | Layer.

  ##### Returns:

  The removed layer (or undefined if the layer was not found).

#### removeOverlay(overlay){ol.Overlay|undefined}

src/ol/map.js, line 1189

  Remove the given overlay from the map.

  Name | Type | Description
  --- | --- | ---
  `overlay` | ol.Overlay | Overlay.

  ##### Returns:

  The removed overlay (or undefined if the overlay was not found).

#### render()

src/ol/map.js, line 1137

  Request a map rendering (at the next animation frame).

#### renderSync()

src/ol/map.js, line 1125

  Requests an immediate render in a synchronous manner.

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

#### setLayerGroup(layerGroup)

src/ol/map.js, line 1279

  Sets the layergroup of this map.

  Name | Type | Description
  --- | --- | ---
  `layerGroup` | ol.layer.Group | A layer group containing the layers in this 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.

#### setSize(size)

src/ol/map.js, line 1290

  Set the size of this map.

  Name | Type | Description
  --- | --- | ---
  `size` | ol.Size | undefined | The size in pixels of the map in the DOM.

#### setTarget(target)

src/ol/map.js, line 1302

  Set the target element to render this map into.

  Name | Type | Description
  --- | --- | ---
  `target` | Element | string | undefined | The Element or id of the Element that the map is rendered in.

#### setView(view)

src/ol/map.js, line 1313

  Set the view for this map.

  Name | Type | Description
  --- | --- | ---
  `view` | ol.View | The view that controls this map.

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

#### updateSize()

src/ol/map.js, line 1333

  Force a recalculation of the map viewport size. This should be called when third-party code changes the size of the map viewport.