Layers · Angular, React and OpenLayers

An SVG map as a layer

Mount an interactive SVG map of Poland’s voivodeships as a custom OpenLayers render layer aligned via composeCssTransform and styled with CSS.

An SVG map of Poland's voivodeships on black, Małopolska faded under the pointer and a blue circle on Kraków.
A screenshot of the example. Voivodeships: Państwowy Rejestr Granic © GUGiK.

What this example shows

Against a dark backdrop, a crisp vector SVG drawing of Poland’s 16 voivodeships with a marker on Kraków pans, zooms and rotates smoothly as an OpenLayers map layer.

Moving the pointer across regional boundaries highlights each voivodeship directly through native CSS :hover rules on <path> elements—without writing JavaScript hit-detection loops.

When you need it

Architectural floorplans, schematic transit diagrams, custom data visualisations and pre-authored Illustrator/Inkscape SVGs often carry rich CSS classes, gradients, filters and DOM hover states of their own.

Mounting an existing SVG DOM subtree directly as a custom render layer preserves native SVG DOM events and CSS :hover styling while delegating pan, zoom and rotation math to OpenLayers.

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.

svg-layer.css
/* As on the OpenLayers page: a black map, and the voivodeship under the pointer fades, as the map's other layers let
   the pointer through to the SVG. */
app-svg-layer .ol-viewport {
  background: black;
}

app-svg-layer .svg-layer path:hover {
  opacity: 0.4;
}

app-svg-layer .ol-layer {
  pointer-events: none;
}
svg-layer.ts
import { DOCUMENT } from '@angular/common';
import { ChangeDetectionStrategy, Component, PendingTasks, ViewEncapsulation, inject } from '@angular/core';
import type { FrameState } from 'ol/Map';
import { composeCssTransform } from 'ol/transform';
import {
  CoordinateComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  FeatureComponent,
  GeometryPointComponent,
  LayerRenderComponent,
  LayerVectorComponent,
  MapComponent,
  SourceVectorComponent,
  ViewComponent,
} from 'cc-openlayers';

/** The SVG map's extent in degrees (west, south, east, north) and its size in pixels: tools/make-poland-svg.mjs. */
const SVG_EXTENT = [14, 49, 24.5, 55];
const WIDTH = 2048;
const HEIGHT = 1170;
const SVG_RESOLUTION = (SVG_EXTENT[2] - SVG_EXTENT[0]) / WIDTH;

/**
 * An SVG map of Poland's voivodeships as a layer: a layer with a render function returns the SVG for each frame,
 * placed for the view by a CSS transform. The voivodeship under the pointer fades through a CSS `:hover` rule
 * alone (svg-layer.css); the blue circle on Kraków is a feature of a vector layer over it.
 */
@Component({
  selector: 'app-svg-layer',
  imports: [
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    FeatureComponent,
    GeometryPointComponent,
    LayerRenderComponent,
    LayerVectorComponent,
    MapComponent,
    SourceVectorComponent,
    ViewComponent,
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  // The rules style elements that OpenLayers and the render function create, outside this component's template.
  encapsulation: ViewEncapsulation.None,
  styleUrl: './svg-layer.css',
  template: `
    <aol-map height="480px">
      <aol-interaction-default />
      <aol-control-defaults />
      <aol-view projection="EPSG:4326" [extent]="extent" [zoom]="7">
        <aol-coordinate [x]="19.9368" [y]="50.0614" srid="EPSG:4326" />
      </aol-view>
      <aol-layer-render [render]="render" />
      <aol-layer-vector
        [style]="{ 'circle-fill-color': '#0000ff', 'circle-radius': 10, 'circle-stroke-color': '#ffffff' }"
      >
        <aol-source-vector>
          <aol-feature>
            <aol-geometry-point><aol-coordinate [x]="19.9368" [y]="50.0614" srid="EPSG:4326" /></aol-geometry-point>
          </aol-feature>
        </aol-source-vector>
      </aol-layer-vector>
    </aol-map>
  `,
})
export class SvgLayer {
  protected readonly extent = SVG_EXTENT;
  /** The element the layer shows: the SVG map, moved and scaled for each frame. */
  private readonly container = inject(DOCUMENT).createElement('div');

  constructor() {
    Object.assign(this.container.style, {
      width: `${WIDTH}px`,
      height: `${HEIGHT}px`,
      transformOrigin: 'top left',
      position: 'absolute',
    });
    this.container.className = 'svg-layer';
    void inject(PendingTasks).run(async () => {
      const text = await (await fetch('assets/poland/voivodeships.svg')).text();
      const svg = new DOMParser().parseFromString(text, 'image/svg+xml').documentElement;
      this.container.appendChild(this.container.ownerDocument.importNode(svg, true));
    });
  }

  /** Puts the SVG pixel of the view's centre in the middle of the map, scaled from the SVG's resolution. */
  protected readonly render = (frameState: FrameState): HTMLElement => {
    const { center, resolution, rotation } = frameState.viewState;
    const scale = SVG_RESOLUTION / resolution;
    this.container.style.transform = composeCssTransform(
      frameState.size[0] / 2,
      frameState.size[1] / 2,
      scale,
      scale,
      rotation,
      -(center[0] - SVG_EXTENT[0]) / SVG_RESOLUTION,
      (center[1] - SVG_EXTENT[3]) / SVG_RESOLUTION
    );
    this.container.style.opacity = String(frameState.layerStatesArray[frameState.layerIndex].opacity);
    return this.container;
  };
}

Architecture and OpenLayers mechanics

aol-layer-render builds a sourceless OpenLayers Layer driven by a custom render callback invoked on every animation frame. Because the SVG artwork is authored directly in equirectangular longitude/latitude coordinates (spanning 10.5 degrees across 2048 SVG units) and the map view also runs in EPSG:4326 bounded by [extent], a single affine matrix computed via composeCssTransform translates, scales and rotates the SVG container to match the live view state.

Applying layer state opacity to the wrapper respects parent group fading, while setting pointer-events to none on sibling canvas layers lets mouse hover reach the underlying SVG <path> nodes.

How it works

  • aol-layer-render invokes its custom render function on each frame and mounts the returned SVG container element directly inside the layer stack.
  • composeCssTransform computes the exact CSS matrix translating the view centre to the viewport midpoint, scaling from SVG units to view resolution, and applying view rotation.
  • Matching EPSG:4326 between both the SVG drawing and the OpenLayers view—fenced by [extent]—keeps geographic alignment exact under affine CSS scaling.
  • Native CSS :hover rules fade hovered voivodeship paths while pointer-events none on other layers lets pointer events reach the SVG DOM.

Pitfalls

  • Affine CSS transforms scale uniformly along X and Y: an equirectangular EPSG:4326 SVG will only align over an EPSG:4326 view and would stretch vertically north-to-south if placed over a Web Mercator (EPSG:3857) map without pre-projecting the SVG paths.
  • OpenLayers’ forEachFeatureAtPixel ignores custom DOM/SVG layers—attach click or hover handlers via standard DOM events or Angular/React bindings on the SVG elements themselves.

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.