Essentials · Angular, React and OpenLayers

A map in a separate browser window

Move a live OpenLayers map into a separate multi-monitor browser popup window and back using window.open, setTarget and pagehide cleanup.

A map of southern Poland and its neighbours at zoom 6, centred on Kraków, with a full-screen button and the Open external map button below it.
A screenshot of the example. Map data © OpenStreetMap contributors.

What this example shows

Opening at zoom 6 over southern Poland with a full-screen control and an Open external map button below the canvas, clicking the button launches a separate browser window, copies the page’s stylesheets into it, and moves the live OpenLayers map across windows.

Closing or reloading the popup window automatically returns the exact same map instance—at its latest panned and zoomed position—straight back into the main application page.

When you need it

Emergency dispatch centres, utility network operators and CAD/GIS analysts working across dual monitors often want forms and data tables on one screen and the interactive map maximised on a second monitor.

Reparenting the main application’s live OpenLayers instance into a child window avoids WebSocket or BroadcastChannel state-sync complexity between two separate browser tabs.

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.

external-map.ts
import { ChangeDetectionStrategy, Component, signal, viewChild } from '@angular/core';
import {
  ContentComponent,
  ControlComponent,
  ControlFullScreenComponent,
  CoordinateComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  LayerTileComponent,
  MapComponent,
  SourceOsmComponent,
  ViewComponent,
} from 'cc-openlayers';

/** A map moved into a separate browser window, which goes unusable while the main page is hidden. */
@Component({
  selector: 'app-external-map',
  imports: [
    ContentComponent,
    ControlComponent,
    ControlFullScreenComponent,
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    LayerTileComponent,
    MapComponent,
    SourceOsmComponent,
    ViewComponent,
  ],
  host: { '(document:visibilitychange)': 'updateOverlay()', '(window:pagehide)': 'closeMapWindow()' },
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <aol-map height="480px">
      <aol-interaction-default />
      <aol-control-defaults />
      <aol-control-fullscreen />
      <aol-control>
        <aol-content>
          <div class="ol-mask" hidden><div>Map not usable</div></div>
        </aol-content>
      </aol-control>
      <aol-view [zoom]="6"><aol-coordinate [x]="19.9368" [y]="50.0614" srid="EPSG:4326" /></aol-view>
      <aol-layer-tile><aol-source-osm /></aol-layer-tile>
    </aol-map>
    <div class="example-controls">
      <button type="button" [disabled]="busy()" (click)="openMapWindow()">Open external map</button>
      @if (blocked()) {
        <p class="example-hint">
          Could not open map in external window. If you are using a popup or ad blocker you may need to disable it for
          this example.
        </p>
      }
    </div>
  `,
})
export class ExternalMap {
  /** The button is disabled from the click until the map is back in the page. */
  readonly busy = signal(false);
  readonly blocked = signal(false);
  private readonly map = viewChild.required(MapComponent);
  private readonly mapWindow = signal<Window | undefined>(undefined);

  protected openMapWindow(): void {
    this.blocked.set(false);
    this.busy.set(true);
    const localTarget = this.map().instance.getTargetElement() as HTMLElement;
    const resetMapTarget = () => {
      localTarget.style.height = '';
      this.map().instance.setTarget(localTarget);
      this.busy.set(false);
    };
    // Reset the button and the map target in case the window did not load or open.
    let timeout: number | undefined = window.setTimeout(() => {
      timeout = undefined;
      this.closeMapWindow();
      resetMapTarget();
      this.blocked.set(true);
    }, 3000);
    const mapWindow = window.open(
      'assets/external-map-map.html',
      'MapWindow',
      'toolbar=0,location=0,menubar=0,width=800,height=600'
    );
    if (!mapWindow) return;
    this.mapWindow.set(mapWindow);
    mapWindow.addEventListener('DOMContentLoaded', () => {
      const externalTarget = mapWindow.document.getElementById('map');
      if (!externalTarget) return;
      // The map keeps the styles of this page, OpenLayers' own included.
      for (const style of document.head.querySelectorAll('link[rel="stylesheet"], style')) {
        mapWindow.document.head.append(style.cloneNode(true));
      }
      localTarget.style.height = '0px';
      this.map().instance.setTarget(externalTarget);
      if (timeout !== undefined) {
        window.clearTimeout(timeout);
        timeout = undefined;
      }
      mapWindow.addEventListener('pagehide', () => {
        resetMapTarget();
        // Close the window in case the user reloads it.
        this.closeMapWindow();
      });
      this.updateOverlay();
    });
  }

  protected closeMapWindow(): void {
    this.mapWindow()?.close();
    this.mapWindow.set(undefined);
  }

  /** The external map takes keyboard input only while this page is visible, and is masked otherwise. */
  protected updateOverlay(): void {
    const target = this.mapWindow()?.document.getElementById('map');
    if (!target) return;
    if (document.visibilityState === 'visible') {
      target.classList.remove('unusable');
      target.setAttribute('tabindex', '0');
      target.focus();
    } else {
      target.removeAttribute('tabindex');
      target.classList.add('unusable');
    }
  }
}

Architecture and OpenLayers mechanics

Inside a direct click handler (required to satisfy popup blockers), window.open opens a small example page holding a full-window map host element, clones the parent document’s stylesheets—including OpenLayers’ control styles—into the popup head, and calls setTarget to transfer the live viewport across documents.

Because JavaScript execution and animation frames remain owned by the opener window, hiding or minimising the opener tab throttles animation frames—so the popup displays an informational mask whenever the parent document is hidden. Listening to pagehide on both windows returns the map cleanly when the popup closes and closes the popup automatically if the main page unloads.

How it works

  • window.open creates a child window holding a map container, and setTarget transfers the live OpenLayers viewport into it once ready.
  • Cloning parent stylesheets into the popup ensures OpenLayers zoom buttons, attributions and overlays keep their exact styling.
  • Because the main window still drives the animation frames, the popup masks the map with a notice whenever the parent tab is hidden in the background.
  • pagehide listeners return the map to the main page when the popup closes, and a separate 3-second timeout surfaces a message when the browser blocks the popup.

Pitfalls

  • Browsers block window.open calls outside direct user click gestures; always trigger external windows from an explicit button click and surface clear feedback if a popup blocker intervenes.
  • Closing or refreshing the main application tab terminates the JavaScript context driving the popup map—always close the child window on parent pagehide so users are not left with a dead window.

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.