# Class: Map

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

## ol/Map~Map

    import Map from 'ol/Map.js';

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:

    import Map from 'ol/Map.js';
    import View from 'ol/View.js';
    import TileLayer from 'ol/layer/Tile.js';
    import OSM from 'ol/source/OSM.js';

    const map = new Map({
      view: new View({
        center: [0, 0],
        zoom: 1,
      }),
      layers: [
        new TileLayer({
          source: new OSM(),
        }),
      ],
      target: 'map',
    });

The above snippet creates a map using a `TileLayer` to display `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 `Overlay` for the difference). The map itself is placed in a further element within the viewport.

Layers are stored as a `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 `LayerGroup` is a subclass of `BaseLayer`, so layers entered in the options or added with `addLayer` can be groups, which can contain further groups, and so on.

#### new Map(options)

Map.js, line 250

  Name | Type | Description
  --- | --- | ---
  `controls` | Collection<Control> | Array<Control> | undefined | Controls initially added to the map. If not specified, `defaults` is used. In a worker, no controls are added by default.
  `pixelRatio` | number (defaults to window.devicePixelRatio) | The ratio between physical pixels and device-independent pixels (dips) on the device.
  `interactions` | Collection<Interaction> | Array<Interaction> | undefined | Interactions that are initially added to the map. If not specified, `defaults` is used. In a worker, no interactions are added by default.
  `keyboardEventTarget` | HTMLElement | 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<BaseLayer> | Collection<BaseLayer> | LayerGroup | 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.
  `maxTilesLoading` | number (defaults to 16) | Maximum number tiles to load simultaneously.
  `moveTolerance` | number (defaults to 1) | The minimum distance in pixels the cursor must move to be detected as a map move event instead of a click. Increasing this value can make it easier to click on the map.
  `overlays` | Collection<Overlay> | Array<Overlay> | undefined | Overlays initially added to the map. By default, no overlays are added.
  `target` | HTMLElement | string | HTMLCanvasElement | OffscreenCanvas | undefined | The container for the map, either the element itself or the `id` of the element. If not specified at construction time, `setTarget` must be called for the map to be rendered. If passed by element, the container can be in a secondary document. For use in workers or when exporting a map, use an `OffscreenCanvas` or `HTMLCanvasElement` as target, with a width and height in physical pixels, optionally multiplied by and a scale transform matching the map's pixel ratio. For accessibility (focus and keyboard events for map navigation), the `target` element must have a properly configured `tabindex` attribute. If the `target` element is inside a Shadow DOM, the `tabindex` atribute must be set on the custom element's host element. Note: CSS `transform` support for the target element is limited to `scale`.
  `view` | View | Promise<ViewOptions> | undefined | The map's view. No layer sources will be fetched unless this is specified at construction time or through `setView`.

  ##### Fires:

  - `change` (BaseEvent) - Generic change event. Triggered when the revision counter is increased.
  - `change:layerGroup` (ObjectEvent)
  - `change:size` (ObjectEvent)
  - `change:target` (ObjectEvent)
  - `change:view` (ObjectEvent)
  - `click` (MapBrowserEvent) - A click with no dragging. A double click will fire two of this.
  - `dblclick` (MapBrowserEvent) - A true double click, with no dragging.
  - `error` (BaseEvent) - Generic error event. Triggered when an error occurs.
  - `loadend` (MapEvent) - Triggered when loading of additional map data has completed.
  - `loadstart` (MapEvent) - Triggered when loading of additional map data (tiles, images, features) starts.
  - `moveend` (MapEvent) - Triggered after the map is moved.
  - `movestart` (MapEvent) - Triggered when the map starts moving.
  - `pointerdrag` (MapBrowserEvent) - Triggered when a pointer is dragged.
  - `pointermove` (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` (RenderEvent) - Triggered after layers are composed. When dispatched by the map, the event object will not have a context set. When dispatched by a layer, the event object will have a context set. Only WebGL layers currently dispatch this event.
  - `postrender` (MapEvent) - Triggered after a map frame is rendered.
  - `precompose` (RenderEvent) - Triggered before layers are composed. When dispatched by the map, the event object will not have a context set. When dispatched by a layer, the event object will have a context set. Only WebGL layers currently dispatch this event.
  - `propertychange` (ObjectEvent) - Triggered when a property is changed.
  - `rendercomplete` (RenderEvent) - Triggered when rendering is complete, i.e. all sources and tiles have finished loading for the current viewport, and all tiles are faded in. The event object will not have a context set.
  - `singleclick` (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

- BaseObject

### Observable Properties

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

### Methods

#### addControl(control)

Map.js, line 615

  Add the given control to the map.

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

#### addInteraction(interaction)

Map.js, line 628

  Add the given interaction to the map. If you want to add an interaction at another point of the collection use `getInteractions()` and the methods available on `Collection`. This can be used to stop the event propagation from the handleEvent function. The interactions get to handle the events in the reverse order of this collection.

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

#### addLayer(layer)

Map.js, line 639

  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 `Collection`.

  Name | Type | Description
  --- | --- | ---
  `layer` | BaseLayer | Layer.

#### addOverlay(overlay)

Map.js, line 657

  Add the given overlay to the map.

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

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

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

Map.js, line 709

  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 the `layerFilter` option in `options`. For polygons without a fill, only the stroke will be used for hit detection. Polygons must have a fill style applied to ensure that pixels inside a polygon are detected. The fill can be transparent.

  Name | Type | Description
  --- | --- | ---
  `pixel` | 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` | undefined | 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.
  `hitTolerance` | number (defaults to 0) | Hit-detection tolerance in css pixels. Pixels inside the radius around the given position will be checked for features.
  `checkWrapped` | boolean (defaults to true) | Check-Wrapped Will check for wrapped geometries inside the range of +/- 1 world width. Works only if a projection is used that can be wrapped.

  ##### Returns:

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

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

Object.js, line 136

  Gets a value.

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

  ##### Returns:

  Value.

#### getAllLayers(){Array<Layer>}

Map.js, line 760

  Get all layers from all layer groups.

  ##### Returns:

  Layers.

#### getControls(){Collection<Control>}

Map.js, line 910

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

  ##### Returns:

  Controls.

#### getCoordinateFromPixel(pixel){Coordinate}

Map.js, line 883

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

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

  ##### Returns:

  The coordinate for the pixel position.

#### getEventCoordinate(event){Coordinate}

Map.js, line 813

  Returns the coordinate in user projection for a browser event.

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

  ##### Returns:

  Coordinate.

#### getEventPixel(event){Pixel}

Map.js, line 832

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

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

  ##### Returns:

  Pixel.

#### getFeaturesAtPixel(pixel, options){Array<FeatureLike>}

Map.js, line 743

  Get all features that intersect a pixel on the viewport. For polygons without a fill, only the stroke will be used for hit detection. Polygons must have a fill style applied to ensure that pixels inside a polygon are detected. The fill can be transparent.

  Name | Type | Description
  --- | --- | ---
  `pixel` | Pixel | Pixel.
  `options` | Optional options.
  Name | Type | Description
  --- | --- | ---
  `layerFilter` | undefined | 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.
  `hitTolerance` | number (defaults to 0) | Hit-detection tolerance in css pixels. Pixels inside the radius around the given position will be checked for features.
  `checkWrapped` | boolean (defaults to true) | Check-Wrapped Will check for wrapped geometries inside the range of +/- 1 world width. Works only if a projection is used that can be wrapped.

  ##### Returns:

  The detected features or an empty array if none were found.

#### getInteractions(){Collection<Interaction>}

Map.js, line 945

  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

Object.js, line 149

  Get a list of object property names.

  ##### Returns:

  List of property names.

#### getLayerGroup(){LayerGroup}

Map.js, line 955

  Get the layergroup associated with this map.

  ##### Returns:

  A layer group containing the layers in this map.

#### getLayers(){Collection<BaseLayer>}

Map.js, line 981

  Get the collection of layers associated with this map.

  ##### Returns:

  Layers.

#### getOverlayById(id){Overlay | null}

Map.js, line 932

  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(){Collection<Overlay>}

Map.js, line 920

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

  ##### Returns:

  Overlays.

#### getPixelFromCoordinate(coordinate){Pixel}

Map.js, line 1015

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

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

  ##### Returns:

  A pixel position in the map viewport.

#### getPixelRatio(){number}

Map.js, line 1045

  Get the pixel ratio of the rendered map.

  ##### Returns:

  Pixel ratio.

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

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

Map.js, line 1076

  Get the size of this map.

  ##### Returns:

  The size in pixels of the map in the DOM.

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

Map.js, line 859

  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(){HTMLElement}

Map.js, line 872

  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(){View}

Map.js, line 1089

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

  ##### Returns:

  The view that controls this map.

#### getViewport(){HTMLElement}

Map.js, line 1098

  Get the element that serves as the map viewport.

  ##### Returns:

  Viewport.

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

Map.js, line 786

  Detect if features intersect a pixel on the viewport. Layers included in the detection can be configured through the `layerFilter` option. For polygons without a fill, only the stroke will be used for hit detection. Polygons must have a fill style applied to ensure that pixels inside a polygon are detected. The fill can be transparent.

  Name | Type | Description
  --- | --- | ---
  `pixel` | Pixel | Pixel.
  `options` | Optional options.
  Name | Type | Description
  --- | --- | ---
  `layerFilter` | undefined | 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.
  `hitTolerance` | number (defaults to 0) | Hit-detection tolerance in css pixels. Pixels inside the radius around the given position will be checked for features.
  `checkWrapped` | boolean (defaults to true) | Check-Wrapped Will check for wrapped geometries inside the range of +/- 1 world width. Works only if a projection is used that can be wrapped.

  ##### Returns:

  Is there a feature at the given pixel?

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

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

Map.js, line 1550

  Remove the given control from the map.

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

  ##### Returns:

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

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

Map.js, line 1561

  Remove the given interaction from the map.

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

  ##### Returns:

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

#### removeLayer(layer){BaseLayer | undefined}

Map.js, line 1572

  Removes the given layer from the map.

  Name | Type | Description
  --- | --- | ---
  `layer` | BaseLayer | Layer.

  ##### Returns:

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

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

Map.js, line 1592

  Remove the given overlay from the map.

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

  ##### Returns:

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

#### render()

Map.js, line 1537

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

#### renderSync()

Map.js, line 1510

  Requests an immediate render in a synchronous manner.

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

#### setLayerGroup(layerGroup)

Map.js, line 1714

  Sets the layergroup of this map.

  Name | Type | Description
  --- | --- | ---
  `layerGroup` | LayerGroup | A layer group containing the layers in this map.

#### setLayers(layers)

Map.js, line 964

  Clear any existing layers and add layers to the map.

  Name | Type | Description
  --- | --- | ---
  `layers` | Array<BaseLayer> | Collection<BaseLayer> | The layers to be added to the map.

#### setPixelRatio(pixelRatio)

Map.js, line 1054

  Set the pixel ratio of the rendered map.

  Name | Type | Description
  --- | --- | ---
  `pixelRatio` | number | Pixel ratio.

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

#### setSize(size)

Map.js, line 1728

  Set the size of this map.

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

#### setTarget(target)

Map.js, line 1742

  Set the target element to render this map into. For accessibility (focus and keyboard events for map navigation), the `target` element must have a properly configured `tabindex` attribute. If the `target` element is inside a Shadow DOM, the `tabindex` atribute must be set on the custom element's host element.

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

#### setView(view)

Map.js, line 1755

  Set the view for this map.

  Name | Type | Description
  --- | --- | ---
  `view` | View | Promise<ViewOptions> | null | The view that controls this map. It is also possible to pass a promise that resolves to options for constructing a view. This alternative allows view properties to be resolved by sources or other components that load view-related metadata.

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

#### updateSize()

Map.js, line 1773

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