StoryMapJS API
    Preparing search index...

    Interface OlMap

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

    Layers are stored as a :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 :ol/layer/Group~LayerGroup is a subclass of :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.

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

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

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

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

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

    interface OlMap {
        controls: Collection<Control>;
        disposed: boolean;
        interactions: Collection<Interaction>;
        on: MapEventHandler<EventsKey>;
        once: MapEventHandler<EventsKey>;
        un: MapEventHandler<void>;
        viewport_: HTMLDivElement | undefined;
        addChangeListener(key: string, listener: Listener): void;
        addControl(control: Control): void;
        addEventListener(type: string, listener: Listener): void;
        addInteraction(interaction: Interaction): void;
        addLayer(layer: BaseLayer<{ [x: string]: any }>): void;
        addOverlay(overlay: Overlay): void;
        applyProperties(source: BaseObject): void;
        changed(): void;
        dispatchEvent(event: string | BaseEvent): boolean | undefined;
        dispose(): void;
        disposeInternal(): void;
        forEachFeatureAtPixel<T>(
            pixel: Pixel,
            callback: (
                arg0: FeatureLike,
                arg1: OlLayer<OlSource, LayerRenderer<any>, { [x: string]: any }>,
                arg2: SimpleGeometry,
            ) => T,
            options?: AtPixelOptions,
        ): T | undefined;
        get(key: string): any;
        getAllLayers(): OlLayer<OlSource, LayerRenderer<any>, { [x: string]: any }>[];
        getControls(): Collection<Control>;
        getCoordinateFromPixel(pixel: Pixel): Coordinate;
        getCoordinateFromPixelInternal(pixel: Pixel): Coordinate;
        getEventCoordinate(event: MouseEvent): Coordinate;
        getEventCoordinateInternal(event: MouseEvent): Coordinate;
        getEventPixel(event: UIEvent | { clientX: number; clientY: number }): Pixel;
        getFeaturesAtPixel(pixel: Pixel, options?: AtPixelOptions): FeatureLike[];
        getInteractions(): Collection<Interaction>;
        getKeys(): string[];
        getLayerGroup(): LayerGroup;
        getLayers(): Collection<BaseLayer<{ [x: string]: any }>>;
        getListeners(type: string): Listener[] | undefined;
        getLoadingOrNotReady(): boolean;
        getOverlayById(id: string | number): Overlay | null;
        getOverlayContainer(): HTMLElement;
        getOverlayContainerStopEvent(): HTMLElement;
        getOverlays(): Collection<Overlay>;
        getOwnerDocument(): Document;
        getPixelFromCoordinate(coordinate: Coordinate): Pixel;
        getPixelFromCoordinateInternal(coordinate: Coordinate): Pixel;
        getPixelRatio(): number;
        getProperties(): NoInfer<{ [x: string]: any }>;
        getPropertiesInternal(): Partial<NoInfer<{ [x: string]: any }>> | null;
        getRenderer(): MapRenderer | null;
        getRevision(): number;
        getSize(): Size | undefined;
        getTarget(): string | HTMLElement | undefined;
        getTargetElement(): HTMLElement;
        getTilePriority(
            tile: Tile,
            tileSourceKey: string,
            tileCenter: Coordinate,
            tileResolution: number,
        ): number;
        getView(): OlView;
        getViewport(): HTMLElement;
        handleBrowserEvent(
            browserEvent: PointerEvent | KeyboardEvent | WheelEvent,
            type?: string,
        ): void;
        handleMapBrowserEvent(mapBrowserEvent: MapBrowserEvent): void;
        handlePostRender(): void;
        hasFeatureAtPixel(pixel: Pixel, options?: AtPixelOptions): boolean;
        hasListener(type?: string): boolean;
        hasProperties(): boolean;
        isRendered(): boolean;
        notify(key: string, oldValue: any): void;
        onceInternal(
            type: string | string[],
            listener: (arg0: Event | BaseEvent) => unknown,
        ): EventsKey | EventsKey[];
        onInternal(
            type: string | string[],
            listener: (arg0: Event | BaseEvent) => unknown,
        ): EventsKey | EventsKey[];
        redrawText(): void;
        removeChangeListener(key: string, listener: Listener): void;
        removeControl(control: Control): Control | undefined;
        removeEventListener(type: string, listener: Listener): void;
        removeInteraction(interaction: Interaction): Interaction | undefined;
        removeLayer(
            layer: BaseLayer<{ [x: string]: any }>,
        ): BaseLayer<{ [x: string]: any }> | undefined;
        removeOverlay(overlay: Overlay): Overlay | undefined;
        render(): void;
        renderSync(): void;
        set(key: string, value: any, silent?: boolean): void;
        setLayerGroup(layerGroup: LayerGroup): void;
        setLayers(
            layers:
                | Collection<BaseLayer<{ [x: string]: any }>>
                | BaseLayer<{ [x: string]: any }>[],
        ): void;
        setPixelRatio(pixelRatio: number): void;
        setProperties(values: Partial<NoInfer<Properties>>, silent?: boolean): void;
        setSize(size: Size | undefined): void;
        setTarget(target?: string | HTMLElement): void;
        setView(view: OlView | Promise<ViewOptions> | null): void;
        unInternal(
            type: string | string[],
            listener: (arg0: Event | BaseEvent) => unknown,
        ): void;
        unset(key: string, silent?: boolean): void;
        updateSize(): void;
    }

    Hierarchy

    • BaseObject<{ [x: string]: any }>
      • OlMap
    Index
    controls disposed interactions on once un viewport_
    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 getPixelRatio 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 setPixelRatio setProperties setSize setTarget setView unInternal unset updateSize
    controls: Collection<Control>
    disposed: boolean

    The object has already been disposed.

    interactions: Collection<Interaction>
    on: MapEventHandler<EventsKey>
    once: MapEventHandler<EventsKey>
    un: MapEventHandler<void>

    viewport_

    viewport_: HTMLDivElement | undefined

    • Parameters

      • key: string

        Key name.

      • listener: Listener

        Listener.

      Returns void

    • Add the given control to the map.

      Parameters

      • control: Control

        Control.

      Returns void

    • Parameters

      • type: string

        Type.

      • listener: Listener

        Listener.

      Returns 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 :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

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

      Parameters

      • layer: BaseLayer<{ [x: string]: any }>

        Layer.

      Returns void

    • Add the given overlay to the map.

      Parameters

      • overlay: Overlay

        Overlay.

      Returns void

    • Protected

      Apply any properties from another object without triggering events.

      Parameters

      • source: BaseObject

        The source object.

      Returns void

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

      Returns void

    • 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 boolean | undefined

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

    • Clean up.

      Returns void

    • Protected

      Extension point for disposable objects.

      Returns void

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

      Type Parameters

      • T

      Parameters

      • pixel: Pixel

        Pixel.

      • callback: (
            arg0: FeatureLike,
            arg1: OlLayer<OlSource, LayerRenderer<any>, { [x: string]: any }>,
            arg2: SimpleGeometry,
        ) => T

        Feature callback. The callback will be called with two arguments. The first argument is one :ol/Feature~Feature feature or :ol/render/Feature~RenderFeature render feature at the pixel, the second is the :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 T | undefined

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

    • Gets a value.

      Parameters

      • key: string

        Key name.

      Returns any

      Value.

    • Get all layers from all layer groups.

      Returns OlLayer<OlSource, LayerRenderer<any>, { [x: string]: any }>[]

      Layers.

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

      Returns Collection<Control>

      Controls.

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

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

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

      Parameters

      • event: MouseEvent

        Event.

      Returns Coordinate

      Coordinate.

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

      Parameters

      • event: MouseEvent

        Event.

      Returns Coordinate

      Coordinate.

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

      Parameters

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

        Event.

      Returns Pixel

      Pixel.

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

      Parameters

      • pixel: Pixel

        Pixel.

      • Optionaloptions: AtPixelOptions

        Optional options.

      Returns FeatureLike[]

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

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

    • Get a list of object property names.

      Returns string[]

      List of property names.

    • Get the layergroup associated with this map.

      Returns LayerGroup

      A layer group containing the layers in this map.

    • Get the collection of layers associated with this map.

      Returns Collection<BaseLayer<{ [x: string]: any }>>

      Layers.

    • 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 Listener[] | undefined

      Listeners.

    • Returns boolean

      Layers have sources that are still loading.

    • 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 Overlay | null

      Overlay.

    • 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 :ol/MapBrowserEvent~MapBrowserEvent events.

      Returns HTMLElement

      The map's overlay container.

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

      Returns HTMLElement

      The map's overlay container that stops events.

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

      Returns Collection<Overlay>

      Overlays.

    • Returns Document

      The document where the map is displayed.

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

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

    • Get the pixel ratio of the rendered map.

      Returns number

      Pixel ratio.

    • Get an object of all property names and values.

      Returns NoInfer<{ [x: string]: any }>

      Object.

    • Get an object of all property names and values.

      Returns Partial<NoInfer<{ [x: string]: any }>> | null

      Object.

    • Get the map renderer.

      Returns MapRenderer | null

      Renderer

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

      Returns number

      Revision.

    • Get the size of this map.

      Returns Size | undefined

      The size in pixels of the map in the DOM.

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

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

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

    • Parameters

      • tile: Tile

        Tile.

      • tileSourceKey: string

        Tile source key.

      • tileCenter: Coordinate

        Tile center.

      • tileResolution: number

        Tile resolution.

      Returns number

      Tile priority.

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

      Returns OlView

      The view that controls this map.

    • Get the element that serves as the map viewport.

      Returns HTMLElement

      Viewport.

    • Parameters

      • browserEvent: PointerEvent | KeyboardEvent | WheelEvent

        Browser event.

      • Optionaltype: string

        Type.

      Returns void

    • Parameters

      • mapBrowserEvent: MapBrowserEvent

        The event to handle.

      Returns void

    • Protected

      Returns void

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

      Parameters

      • pixel: Pixel

        Pixel.

      • Optionaloptions: AtPixelOptions

        Optional options.

      Returns boolean

      Is there a feature at the given pixel?

    • Parameters

      • Optionaltype: string

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

      Returns boolean

      Has listeners.

    • Returns boolean

      The object has properties.

    • Returns boolean

      Is rendered.

    • Parameters

      • key: string

        Key name.

      • oldValue: any

        Old value.

      Returns void

    • Protected

      Parameters

      • type: string | string[]

        Type.

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

        Listener.

      Returns EventsKey | EventsKey[]

      Event key.

    • Protected

      Parameters

      • type: string | string[]

        Type.

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

        Listener.

      Returns EventsKey | EventsKey[]

      Event key.

    • Redraws all text after new fonts have loaded

      Returns void

    • Parameters

      • key: string

        Key name.

      • listener: Listener

        Listener.

      Returns void

    • Remove the given control from the map.

      Parameters

      • control: Control

        Control.

      Returns Control | undefined

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

    • Parameters

      • type: string

        Type.

      • listener: Listener

        Listener.

      Returns void

    • Remove the given interaction from the map.

      Parameters

      • interaction: Interaction

        Interaction to remove.

      Returns Interaction | undefined

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

    • Removes the given layer from the map.

      Parameters

      • layer: BaseLayer<{ [x: string]: any }>

        Layer.

      Returns BaseLayer<{ [x: string]: any }> | undefined

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

    • Remove the given overlay from the map.

      Parameters

      • overlay: Overlay

        Overlay.

      Returns Overlay | undefined

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

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

      Returns void

    • Requests an immediate render in a synchronous manner.

      Returns void

    • Sets a value.

      Parameters

      • key: string

        Key name.

      • value: any

        Value.

      • Optionalsilent: boolean

        Update without triggering an event.

      Returns void

    • Sets the layergroup of this map.

      Parameters

      • layerGroup: LayerGroup

        A layer group containing the layers in this map.

      Returns void

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

      Parameters

      • layers: Collection<BaseLayer<{ [x: string]: any }>> | BaseLayer<{ [x: string]: any }>[]

        The layers to be added to the map.

      Returns void

    • Set the pixel ratio of the rendered map.

      Parameters

      • pixelRatio: number

        Pixel ratio.

      Returns 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: Partial<NoInfer<Properties>>

        Values.

      • Optionalsilent: boolean

        Update without triggering an event.

      Returns void

    • Set the size of this map.

      Parameters

      • size: Size | undefined

        The size in pixels of the map in the DOM.

      Returns void

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

      Parameters

      • Optionaltarget: string | HTMLElement

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

      Returns void

    • Set the view for this map.

      Parameters

      • view: OlView | 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.

      Returns void

    • Protected

      Unlisten for a certain type of event.

      Parameters

      • type: string | string[]

        Type.

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

        Listener.

      Returns void

    • Unsets a property.

      Parameters

      • key: string

        Key name.

      • Optionalsilent: boolean

        Unset without triggering an event.

      Returns 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

    Settings
    Member Visibility

    On This Page
    Properties
    Methods
    addChangeListeneraddControladdEventListeneraddInteractionaddLayeraddOverlayapplyPropertieschangeddispatchEventdisposedisposeInternalforEachFeatureAtPixelgetgetAllLayersgetControlsgetCoordinateFromPixelgetCoordinateFromPixelInternalgetEventCoordinategetEventCoordinateInternalgetEventPixelgetFeaturesAtPixelgetInteractionsgetKeysgetLayerGroupgetLayersgetListenersgetLoadingOrNotReadygetOverlayByIdgetOverlayContainergetOverlayContainerStopEventgetOverlaysgetOwnerDocumentgetPixelFromCoordinategetPixelFromCoordinateInternalgetPixelRatiogetPropertiesgetPropertiesInternalgetRenderergetRevisiongetSizegetTargetgetTargetElementgetTilePrioritygetViewgetViewporthandleBrowserEventhandleMapBrowserEventhandlePostRenderhasFeatureAtPixelhasListenerhasPropertiesisRenderednotifyonceInternalonInternalredrawTextremoveChangeListenerremoveControlremoveEventListenerremoveInteractionremoveLayerremoveOverlayrenderrenderSyncsetsetLayerGroupsetLayerssetPixelRatiosetPropertiessetSizesetTargetsetViewunInternalunsetupdateSize