Essentials · Angular, React and OpenLayers

Move a map to another element

Move a live OpenLayers map instance between two DOM containers with setTarget while preserving its camera view, tile cache and map state.

The map of central Kraków moved into the lower element by Teleport, with the upper element left empty above the button.
A screenshot of the example. Map data © OpenStreetMap contributors.

What this example shows

A street map of central Kraków starts inside an upper container while a second sized placeholder box sits empty beneath the Teleport action button. Clicking Teleport detaches the live OpenLayers viewport from the upper host and mounts it instantly inside the lower box—and back again on the next click—without losing zoom, pan position or loaded tiles.

When you need it

Responsive enterprise apps frequently move a single map between a compact sidebar preview, a maximised modal dialog, a split-screen inspection layout or a dedicated print-preview frame.

Destroying one map and instantiating a second copy loses transient draw sketches, re-downloads tiles and forces fragile state synchronisation; moving the single OpenLayers viewport element via setTarget preserves everything in place.

The code

The example uses cc-openlayers, my Angular component library for OpenLayers: each aol-… element creates the OpenLayers object it names, updates it from its inputs and disposes of it with the component.

teleport.ts
import { ChangeDetectionStrategy, Component, type ElementRef, viewChild } from '@angular/core';
import {
  CoordinateComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  LayerTileComponent,
  MapComponent,
  SourceOsmComponent,
  ViewComponent,
} from 'cc-openlayers';

/** One map moved between two frames: Teleport gives the same map, with its view and layers, the other frame. */
@Component({
  selector: 'app-teleport',
  imports: [
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    LayerTileComponent,
    MapComponent,
    SourceOsmComponent,
    ViewComponent,
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <aol-map height="300px">
      <aol-interaction-default />
      <aol-control-defaults />
      <aol-view [zoom]="12">
        <aol-coordinate [x]="19.9373" [y]="50.0617" srid="EPSG:4326" />
      </aol-view>
      <aol-layer-tile><aol-source-osm /></aol-layer-tile>
    </aol-map>
    <div class="example-controls">
      <button type="button" id="teleport" (click)="teleport()">Teleport</button>
    </div>
    <div id="map2" #second style="height: 300px"></div>
  `,
})
export class Teleport {
  private readonly map = viewChild.required(MapComponent);
  private readonly second = viewChild.required<ElementRef<HTMLElement>>('second');
  /** The frame the map component gave the map. */
  private first?: HTMLElement;

  protected teleport(): void {
    const map = this.map().instance;
    this.first ??= map.getTargetElement();
    map.setTarget(map.getTargetElement() === this.first ? this.second().nativeElement : this.first);
  }
}

Architecture and OpenLayers mechanics

OpenLayers decouples its internal viewport DOM tree and canvas buffers from the outer host element. Before moving for the first time, the component records the original host created by aol-map via getTargetElement(), reads the alternate template div via viewChild, and calls setTarget to reparent the live viewport and automatically recalculate its pixel size.

How it works

  • setTarget reparents the live OpenLayers viewport into another DOM element and triggers an immediate size measurement.
  • getTargetElement() captures the initial container created by aol-map so subsequent clicks can move the map back home.
  • The destination slot is a standard template div queried cleanly via Angular viewChild (or a React ref).

Pitfalls

  • Even while displayed inside another DOM container, the host Angular or React component still owns the map lifecycle—destroying that component disposes of the map wherever its viewport currently lives.
  • Ensure the target container has an explicit non-zero height (such as style="height: 300px") before calling setTarget, otherwise the teleported map measures 0 pixels high and disappears.

The same feature in the OpenLayers examples .

Background: state and lifecycle of maps in Angular with OpenLayers, which the components of cc-openlayers take care of.