Vector data · Angular, React and OpenLayers

Drop KMZ archives with their icons

Unpack dropped KMZ archives in the browser with a custom OpenLayers KML format that resolves bundled ZIP icons and sanitizes HTML descriptions.

OpenStreetMap of Kraków with the hills and viewpoints of the dropped KMZ archive as mound, peak and viewpoint icons, a description below the map.
A screenshot of the example. Map data © OpenStreetMap contributors.

What this example shows

Dropping a compressed .kmz archive onto the OpenStreetMap view of Kraków—or downloading and dropping the bundled sample of 55 local hills, mounds and viewpoints—unzips the package entirely in browser memory, renders each placemark with its embedded peak, mound or viewpoint icon, and displays sanitized HTML descriptions below the map on hover or click.

When you need it

Google Earth, drone mission planners and field survey apps default to exporting .kmz ZIP bundles rather than plain .kml whenever custom marker icons or photos accompany the placemarks.

Unpacking KMZ archives directly in the browser lets users preview self-contained icon-rich exports with zero backend upload or temporary server storage.

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.

drag-and-drop-custom-kmz.ts
import { ChangeDetectionStrategy, Component, signal, viewChild } from '@angular/core';
import type Feature from 'ol/Feature';
import type MapBrowserEvent from 'ol/MapBrowserEvent';
import GPX from 'ol/format/GPX';
import GeoJSON from 'ol/format/GeoJSON';
import IGC from 'ol/format/IGC';
import KML from 'ol/format/KML';
import TopoJSON from 'ol/format/TopoJSON';
import type { DragAndDropEvent } from 'ol/interaction/DragAndDrop';
import VectorLayer from 'ol/layer/Vector';
import VectorSource from 'ol/source/Vector';
import {
  CoordinateComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  type DragAndDropFormat,
  DragAndDropInteractionComponent,
  LayerTileComponent,
  MapComponent,
  SourceOsmComponent,
  ViewComponent,
} from 'cc-openlayers';
import { KMZ } from 'cc-openlayers/io';

/** Files dropped on the map are shown as layers; a KMZ archive is read as its KML document with the icons it packs. */
@Component({
  selector: 'app-drag-and-drop-custom-kmz',
  imports: [
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    DragAndDropInteractionComponent,
    LayerTileComponent,
    MapComponent,
    SourceOsmComponent,
    ViewComponent,
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <aol-map height="480px" (pointerMove)="describe($event)" (olClick)="describe($event)">
      <aol-interaction-default />
      <aol-interaction-draganddrop [formatConstructors]="formats" (addFeatures)="show($event)" />
      <aol-control-defaults />
      <aol-view [zoom]="10">
        <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" (click)="download()">Download sample</button>
      <output [innerHTML]="info()"></output>
    </div>
  `,
})
export class DragAndDropCustomKmz {
  readonly info = signal('');
  private readonly map = viewChild.required(MapComponent);
  protected readonly formats: DragAndDropFormat[] = [KMZ, GPX, GeoJSON, IGC, KML, TopoJSON];

  /** The descriptions (or names) of the features under the pixel; KML descriptions are HTML. */
  protected describe(event: MapBrowserEvent): void {
    if (event.dragging) return;
    const descriptions: string[] = [];
    this.map().instance.forEachFeatureAtPixel(event.pixel, (feature) => {
      const description =
        feature.get('description') || feature.get('name') || feature.get('_name') || feature.get('layer');
      if (description) descriptions.push(description);
    });
    this.info.set(descriptions.join('<br>'));
  }

  protected async download(): Promise<void> {
    const response = await fetch('assets/krakow/hills.kmz');
    const link = document.createElement('a');
    link.href = URL.createObjectURL(await response.blob());
    link.download = 'krakow-hills.kmz';
    link.click();
  }

  protected show(event: DragAndDropEvent): void {
    const source = new VectorSource({ features: event.features as Feature[] });
    const map = this.map().instance;
    map.addLayer(new VectorLayer({ source }));
    map.getView().fit(source.getExtent(), { padding: [40, 40, 40, 40] });
  }
}

Architecture and OpenLayers mechanics

KMZ from cc-openlayers/io extends OpenLayers’ native KML parser: it reads dropped files as binary array buffers, decompresses the ZIP container, parses the primary KML document inside, and rewrites embedded relative icon paths to in-memory browser object URLs.

Hovering or clicking a placemark extracts its KML description (falling back to its name when absent) and binds it through [innerHTML] so Angular’s HTML sanitizer strips scripts and inline event handlers.

How it works

  • KMZ from cc-openlayers/io unzips the dropped archive, parses its root KML document and serves bundled icon images via browser object URLs.
  • Configuring the drag-and-drop reader for binary array buffers allows KMZ to inspect ZIP bytes while decoding text formats cleanly alongside it.
  • Pointer hover and click display each feature’s description HTML (or fallback name) beneath the viewport.

Pitfalls

  • Embedded KML descriptions contain arbitrary author-supplied HTML—always bind them through [innerHTML] sanitization and never bypass framework XSS protection.
  • Browser blob object URLs created for unpacked icons remain allocated for the lifetime of the document unless revoked when layers are removed during long multi-archive sessions.

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.