Class Map

Classdesc

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 module:ol/layer/Tile~TileLayer to display module:ol/source/OSM~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 module:ol/Overlay~Overlay for the difference). The map itself is placed in a further element within the viewport.

Layers are stored as a module:ol/Collection~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 module:ol/layer/Group~LayerGroup is a subclass of module:ol/layer/Base~BaseLayer, so layers entered in the options or added with addLayer can be groups, which can contain further groups, and so on.

Fires

import("./MapBrowserEvent.js").MapBrowserEvent

Fires

import("./MapEvent.js").MapEvent

Fires

import("./render/Event.js").default#precompose

Fires

import("./render/Event.js").default#postcompose

Fires

import("./render/Event.js").default#rendercomplete

Api

Hierarchy (view full)

Constructors

constructor

Properties

controls disposed interactions on once resizeObserver_ un

Methods

addChangeListener addControl addEventListener addInteraction addLayer addOverlay applyProperties changed dispatchEvent dispose disposeInternal forEachFeatureAtPixel get getAllLayers getControls getCoordinateFromPixel getCoordinateFromPixelInternal getEventCoordinate getEventCoordinateInternal getEventPixel getFeaturesAtPixel getInteractions getKeys getLayerGroup getLayers getListeners getLoadingOrNotReady getOverlayById getOverlayContainer getOverlayContainerStopEvent getOverlays getOwnerDocument getPixelFromCoordinate getPixelFromCoordinateInternal getProperties getPropertiesInternal getRenderer getRevision getSize getTarget getTargetElement getTilePriority getView getViewport handleBrowserEvent handleMapBrowserEvent handlePostRender hasFeatureAtPixel hasListener hasProperties isRendered notify onceInternal onInternal redrawText removeChangeListener removeControl removeEventListener removeInteraction removeLayer removeOverlay render renderSync set setLayerGroup setLayers setProperties setSize setTarget setView unInternal unset updateSize

Constructors

constructor

Properties

Protectedcontrols

controls: Collection<Control>

Protecteddisposed

disposed: boolean

The object has already been disposed.

Protectedinteractions

interactions: Collection<Interaction>

on

on: MapEventHandler<EventsKey>

once

once: MapEventHandler<EventsKey>

resizeObserver_

resizeObserver_: ResizeObserver

un

un: MapEventHandler<void>

Methods

addChangeListener

  • addChangeListener(key, listener): void

  • Parameters

    • key: string

      Key name.

    • listener: Listener

      Listener.

    Returns void

addControl

  • addControl(control): void

  • Add the given control to the map.

    Parameters

    • control: Control

      Control.

    Returns void

    Api

addEventListener

  • addEventListener(type, listener): void

  • Parameters

    • type: string

      Type.

    • listener: Listener

      Listener.

    Returns void

addInteraction

  • addInteraction(interaction): void

  • 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 module:ol/Collection~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.

    Parameters

    • interaction: Interaction

      Interaction to add.

    Returns void

    Api

addLayer

  • addLayer(layer): void

  • 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 module:ol/Collection~Collection.

    Parameters

    • layer: BaseLayer

      Layer.

    Returns void

    Api

addOverlay

  • addOverlay(overlay): void

  • Add the given overlay to the map.

    Parameters

    Returns void

    Api

ProtectedapplyProperties

  • applyProperties(source): void
  • Protected

    Apply any properties from another object without triggering events.

    Parameters

    • source: Object

      The source object.

    Returns void

changed

  • changed(): void

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

    Returns void

    Api

dispatchEvent

  • dispatchEvent(event): undefined | boolean

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

    Parameters

    • event: string | BaseEvent

      Event object.

    Returns undefined | boolean

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

    Api

dispose

  • dispose(): void

  • Clean up.

    Returns void

ProtecteddisposeInternal

  • disposeInternal(): void
  • Protected

    Extension point for disposable objects.

    Returns void

forEachFeatureAtPixel

  • forEachFeatureAtPixel<T>(pixel, callback, options?): undefined | T

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

    Type Parameters

    • T

    Parameters

    • pixel: Pixel

      Pixel.

    • callback: ((arg0: FeatureLike, arg1: Layer<external.olsource.Source, LayerRenderer<any>>, arg2: SimpleGeometry) => T)

      Feature callback. The callback will be called with two arguments. The first argument is one module:ol/Feature~Feature feature or module:ol/render/Feature~RenderFeature render feature at the pixel, the second is the module:ol/layer/Layer~Layer layer of the feature and will be null for unmanaged layers. To stop detection, callback functions can return a truthy value.

    • Optionaloptions: AtPixelOptions

      Optional options.

    Returns undefined | T

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

    Api

get

  • get(key): any

  • Gets a value.

    Parameters

    • key: string

      Key name.

    Returns any

    Value.

    Api

getAllLayers

  • getAllLayers(): Layer<external.olsource.Source, LayerRenderer<any>>[]

  • Get all layers from all layer groups.

    Returns Layer<external.olsource.Source, LayerRenderer<any>>[]

    Layers.

    Api

getControls

  • getControls(): Collection<Control>

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

    Returns Collection<Control>

    Controls.

    Api

getCoordinateFromPixel

  • getCoordinateFromPixel(pixel): Coordinate

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

    Parameters

    • pixel: Pixel

      Pixel position in the map viewport.

    Returns Coordinate

    The coordinate for the pixel position.

    Api

getCoordinateFromPixelInternal

  • getCoordinateFromPixelInternal(pixel): Coordinate

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

    Parameters

    • pixel: Pixel

      Pixel position in the map viewport.

    Returns Coordinate

    The coordinate for the pixel position.

getEventCoordinate

  • getEventCoordinate(event): Coordinate

  • Returns the coordinate in user projection for a browser event.

    Parameters

    • event: MouseEvent

      Event.

    Returns Coordinate

    Coordinate.

    Api

getEventCoordinateInternal

  • getEventCoordinateInternal(event): Coordinate

  • Returns the coordinate in view projection for a browser event.

    Parameters

    • event: MouseEvent

      Event.

    Returns Coordinate

    Coordinate.

getEventPixel

  • getEventPixel(event): Pixel

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

    Parameters

    • event: UIEvent | {
          clientX: number;
          clientY: number;
      }

      Event.

    Returns Pixel

    Pixel.

    Api

getFeaturesAtPixel

  • getFeaturesAtPixel(pixel, options?): FeatureLike[]

  • Get all features that intersect a pixel on the viewport.

    Parameters

    • pixel: Pixel

      Pixel.

    • Optionaloptions: AtPixelOptions

      Optional options.

    Returns FeatureLike[]

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

    Api

getInteractions

  • getInteractions(): Collection<Interaction>

  • 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 Collection<Interaction>

    Interactions.

    Api

getKeys

  • getKeys(): string[]

  • Get a list of object property names.

    Returns string[]

    List of property names.

    Api

getLayerGroup

  • getLayerGroup(): LayerGroup

  • Get the layergroup associated with this map.

    Returns LayerGroup

    A layer group containing the layers in this map.

    Observable

    Api

getLayers

  • getLayers(): Collection<BaseLayer>

  • Get the collection of layers associated with this map.

    Returns Collection<BaseLayer>

    Layers.

    Api

getListeners

  • getListeners(type): undefined | Listener[]

  • Get the listeners for a specified event type. Listeners are returned in the order that they will be called in.

    Parameters

    • type: string

      Type.

    Returns undefined | Listener[]

    Listeners.

getLoadingOrNotReady

  • getLoadingOrNotReady(): boolean

  • Returns boolean

    Layers have sources that are still loading.

getOverlayById

  • getOverlayById(id): null | Overlay

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

    Parameters

    • id: string | number

      Overlay identifier.

    Returns null | Overlay

    Overlay.

    Api

getOverlayContainer

  • getOverlayContainer(): HTMLElement

  • Get the element that serves as the container for overlays. Elements added to this container will let mousedown and touchstart events through to the map, so clicks and gestures on an overlay will trigger module:ol/MapBrowserEvent~MapBrowserEvent events.

    Returns HTMLElement

    The map's overlay container.

getOverlayContainerStopEvent

  • getOverlayContainerStopEvent(): HTMLElement

  • Get the element that serves as a container for overlays that don't allow event propagation. Elements added to this container won't let mousedown and touchstart events through to the map, so clicks and gestures on an overlay don't trigger any module:ol/MapBrowserEvent~MapBrowserEvent.

    Returns HTMLElement

    The map's overlay container that stops events.

getOverlays

  • getOverlays(): Collection<Overlay>

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

    Returns Collection<Overlay>

    Overlays.

    Api

getOwnerDocument

  • getOwnerDocument(): Document

  • Returns Document

    The document where the map is displayed.

getPixelFromCoordinate

  • getPixelFromCoordinate(coordinate): Pixel

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

    Parameters

    • coordinate: Coordinate

      A map coordinate.

    Returns Pixel

    A pixel position in the map viewport.

    Api

getPixelFromCoordinateInternal

  • getPixelFromCoordinateInternal(coordinate): Pixel

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

    Parameters

    • coordinate: Coordinate

      A map coordinate.

    Returns Pixel

    A pixel position in the map viewport.

getProperties

  • getProperties(): {
        [x: string]: any;
    }

  • Get an object of all property names and values.

    Returns {
        [x: string]: any;
    }

    Object.

    • [x: string]: any

    Api

getPropertiesInternal

  • getPropertiesInternal(): null | {
        [x: string]: any;
    }

  • Get an object of all property names and values.

    Returns null | {
        [x: string]: any;
    }

    Object.

getRenderer

  • getRenderer(): null | MapRenderer

  • Get the map renderer.

    Returns null | MapRenderer

    Renderer

getRevision

  • getRevision(): number

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

    Returns number

    Revision.

    Api

getSize

  • getSize(): undefined | Size

  • Get the size of this map.

    Returns undefined | Size

    The size in pixels of the map in the DOM.

    Observable

    Api

getTarget

  • getTarget(): undefined | string | HTMLElement

  • 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 undefined | string | HTMLElement

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

    Observable

    Api

getTargetElement

  • getTargetElement(): HTMLElement

  • 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 HTMLElement

    The element that the map is rendered in.

    Api

getTilePriority

  • getTilePriority(tile, tileSourceKey, tileCenter, tileResolution): number

  • Parameters

    • tile: external.ol.Tile

      Tile.

    • tileSourceKey: string

      Tile source key.

    • tileCenter: Coordinate

      Tile center.

    • tileResolution: number

      Tile resolution.

    Returns number

    Tile priority.

getView

  • getView(): external.ol.View

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

    Returns external.ol.View

    The view that controls this map.

    Observable

    Api

getViewport

  • getViewport(): HTMLElement

  • Get the element that serves as the map viewport.

    Returns HTMLElement

    Viewport.

    Api

handleBrowserEvent

  • handleBrowserEvent(browserEvent, type?): void

  • Parameters

    • browserEvent: UIEvent

      Browser event.

    • Optionaltype: string

      Type.

    Returns void

handleMapBrowserEvent

  • handleMapBrowserEvent(mapBrowserEvent): void

  • Parameters

    Returns void

ProtectedhandlePostRender

  • handlePostRender(): void
  • Protected

    Returns void

hasFeatureAtPixel

  • hasFeatureAtPixel(pixel, options?): boolean

  • Detect if features intersect a pixel on the viewport. Layers included in the detection can be configured through the layerFilter option.

    Parameters

    • pixel: Pixel

      Pixel.

    • Optionaloptions: AtPixelOptions

      Optional options.

    Returns boolean

    Is there a feature at the given pixel?

    Api

hasListener

  • hasListener(type?): boolean

  • Parameters

    • Optionaltype: string

      Type. If not provided, true will be returned if this event target has any listeners.

    Returns boolean

    Has listeners.

hasProperties

  • hasProperties(): boolean

  • Returns boolean

    The object has properties.

isRendered

  • isRendered(): boolean

  • Returns boolean

    Is rendered.

notify

  • notify(key, oldValue): void

  • Parameters

    • key: string

      Key name.

    • oldValue: any

      Old value.

    Returns void

ProtectedonceInternal

  • onceInternal(type, listener): EventsKey | EventsKey[]
  • Protected

    Parameters

    • type: string | string[]

      Type.

    • listener: ((arg0: Event | BaseEvent) => unknown)

      Listener.

        • (arg0): unknown

        • Parameters

          • arg0: Event | BaseEvent

          Returns unknown

    Returns EventsKey | EventsKey[]

    Event key.

ProtectedonInternal

  • onInternal(type, listener): EventsKey | EventsKey[]
  • Protected

    Parameters

    • type: string | string[]

      Type.

    • listener: ((arg0: Event | BaseEvent) => unknown)

      Listener.

        • (arg0): unknown

        • Parameters

          • arg0: Event | BaseEvent

          Returns unknown

    Returns EventsKey | EventsKey[]

    Event key.

redrawText

  • redrawText(): void

  • Redraws all text after new fonts have loaded

    Returns void

removeChangeListener

  • removeChangeListener(key, listener): void

  • Parameters

    • key: string

      Key name.

    • listener: Listener

      Listener.

    Returns void

removeControl

  • removeControl(control): undefined | Control

  • Remove the given control from the map.

    Parameters

    • control: Control

      Control.

    Returns undefined | Control

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

    Api

removeEventListener

  • removeEventListener(type, listener): void

  • Parameters

    • type: string

      Type.

    • listener: Listener

      Listener.

    Returns void

removeInteraction

  • removeInteraction(interaction): undefined | Interaction

  • Remove the given interaction from the map.

    Parameters

    • interaction: Interaction

      Interaction to remove.

    Returns undefined | Interaction

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

    Api

removeLayer

  • removeLayer(layer): undefined | BaseLayer

  • Removes the given layer from the map.

    Parameters

    • layer: BaseLayer

      Layer.

    Returns undefined | BaseLayer

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

    Api

removeOverlay

  • removeOverlay(overlay): undefined | Overlay

  • Remove the given overlay from the map.

    Parameters

    Returns undefined | Overlay

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

    Api

render

  • render(): void

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

    Returns void

    Api

renderSync

  • renderSync(): void

  • Requests an immediate render in a synchronous manner.

    Returns void

    Api

set

  • set(key, value, silent?): void

  • Sets a value.

    Parameters

    • key: string

      Key name.

    • value: any

      Value.

    • Optionalsilent: boolean

      Update without triggering an event.

    Returns void

    Api

setLayerGroup

  • setLayerGroup(layerGroup): void

  • Sets the layergroup of this map.

    Parameters

    • layerGroup: LayerGroup

      A layer group containing the layers in this map.

    Returns void

    Observable

    Api

setLayers

  • setLayers(layers): void

  • Clear any existing layers and add layers to the map.

    Parameters

    • layers: BaseLayer[] | Collection<BaseLayer>

      The layers to be added to the map.

    Returns void

    Api

setProperties

  • setProperties(values, silent?): void

  • 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).

    Parameters

    • values: {
          [x: string]: any;
      }

      Values.

      • [x: string]: any
    • Optionalsilent: boolean

      Update without triggering an event.

    Returns void

    Api

setSize

  • setSize(size): void

  • Set the size of this map.

    Parameters

    • size: undefined | Size

      The size in pixels of the map in the DOM.

    Returns void

    Observable

    Api

setTarget

  • setTarget(target?): void

  • Set the target element to render this map into.

    Parameters

    • Optionaltarget: string | HTMLElement

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

    Returns void

    Observable

    Api

setView

  • setView(view): void

  • Set the view for this map.

    Parameters

    • view: external.ol.View | Promise<ViewOptions>

      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.

    Returns void

    Observable

    Api

ProtectedunInternal

  • unInternal(type, listener): void
  • Protected

    Unlisten for a certain type of event.

    Parameters

    • type: string | string[]

      Type.

    • listener: ((arg0: Event | BaseEvent) => unknown)

      Listener.

        • (arg0): unknown

        • Parameters

          • arg0: Event | BaseEvent

          Returns unknown

    Returns void

unset

  • unset(key, silent?): void

  • Unsets a property.

    Parameters

    • key: string

      Key name.

    • Optionalsilent: boolean

      Unset without triggering an event.

    Returns void

    Api

updateSize

  • updateSize(): void

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

    Returns void

    Api

Settings

Member Visibility

On This Page

Constructors
Properties
Methods
addChangeListeneraddControladdEventListeneraddInteractionaddLayeraddOverlayapplyPropertieschangeddispatchEventdisposedisposeInternalforEachFeatureAtPixelgetgetAllLayersgetControlsgetCoordinateFromPixelgetCoordinateFromPixelInternalgetEventCoordinategetEventCoordinateInternalgetEventPixelgetFeaturesAtPixelgetInteractionsgetKeysgetLayerGroupgetLayersgetListenersgetLoadingOrNotReadygetOverlayByIdgetOverlayContainergetOverlayContainerStopEventgetOverlaysgetOwnerDocumentgetPixelFromCoordinategetPixelFromCoordinateInternalgetPropertiesgetPropertiesInternalgetRenderergetRevisiongetSizegetTargetgetTargetElementgetTilePrioritygetViewgetViewporthandleBrowserEventhandleMapBrowserEventhandlePostRenderhasFeatureAtPixelhasListenerhasPropertiesisRenderednotifyonceInternalonInternalredrawTextremoveChangeListenerremoveControlremoveEventListenerremoveInteractionremoveLayerremoveOverlayrenderrenderSyncsetsetLayerGroupsetLayerssetPropertiessetSizesetTargetsetViewunInternalunsetupdateSize