Vector data · Angular, React and OpenLayers

Kraków districts from TopoJSON

Render Kraków’s 18 administrative districts from a compact shared-arc TopoJSON topology over Esri Dark Gray using non-overlapping flat styles.

Kraków's eighteen districts outlined in white over Esri's dark gray map.
A screenshot of the example. Districts: Map data © OpenStreetMap contributors. Base map: Esri World Dark Gray (Esri, HERE, Garmin, OpenStreetMap contributors and the GIS user community).

What this example shows

All eighteen municipal districts of Kraków appear outlined in crisp white over Esri’s World Dark Gray basemap—reconstructed in the browser from a compact TopoJSON file where adjacent districts share every common border arc exactly once.

When you need it

Administrative subdivisions, electoral precincts, postal zones and statistical census tracts share nearly every interior boundary edge with an immediate neighbour.

Encoding shared arcs once in TopoJSON slashes network payload size compared to GeoJSON and guarantees topological consistency with zero slivers or gaps along district seams.

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.

topojson.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import TopoJSON from 'ol/format/TopoJSON';
import type { FlatStyle } from 'ol/style/flat';
import {
  CoordinateComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  LayerTileComponent,
  LayerVectorComponent,
  MapComponent,
  SourceImageTileComponent,
  SourceVectorComponent,
  ViewComponent,
} from 'cc-openlayers';

/**
 * The eighteen districts of Kraków from a TopoJSON topology, in which each border between two districts is stored
 * once as an arc both use, drawn over Esri's dark grey canvas.
 */
@Component({
  selector: 'app-topojson',
  imports: [
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    LayerTileComponent,
    LayerVectorComponent,
    MapComponent,
    SourceImageTileComponent,
    SourceVectorComponent,
    ViewComponent,
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <aol-map height="480px">
      <aol-interaction-default />
      <aol-control-defaults />
      <aol-view [zoom]="11">
        <aol-coordinate [x]="19.945" [y]="50.057" srid="EPSG:4326" />
      </aol-view>
      <aol-layer-tile>
        <aol-source-imagetile
          url="https://server.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Dark_Gray_Base/MapServer/tile/{z}/{y}/{x}"
          [maxZoom]="16"
          attributions="Tiles © Esri — Esri, HERE, Garmin, © OpenStreetMap contributors, and the GIS user community"
        />
      </aol-layer-tile>
      <aol-layer-vector [style]="style">
        <aol-source-vector
          url="assets/krakow/districts.topojson"
          [format]="format"
          [overlaps]="false"
          attributions='Districts © <a href="https://www.openstreetmap.org/copyright" target="_blank">OpenStreetMap</a> contributors'
        />
      </aol-layer-vector>
    </aol-map>
  `,
})
export class Topojson {
  /** Only the topology's districts; a topology may hold more objects, such as their union. */
  protected readonly format = new TopoJSON({ layers: ['districts'] });
  protected readonly style: FlatStyle = { 'stroke-color': '#ffffff', 'stroke-width': 1.5 };
}

Architecture and OpenLayers mechanics

OpenLayers’ TopoJSON format decodes shared arcs from geographic degrees into projected polygon rings, filtering the file via layers: ['districts'] so only the districts topology object is extracted. Setting [overlaps]="false" on the vector source informs OpenLayers’ canvas renderer that polygons partition space cleanly without overlapping interiors—enabling faster batched stroke and fill passes using a concise flat style (stroke-color and stroke-width).

How it works

  • TopoJSON reconstructs each district polygon from shared arc indices and transforms coordinates into the view projection.
  • layers: ['districts'] extracts solely the districts topology collection when a file bundles multiple named layers.
  • [overlaps]="false" lets the vector renderer batch drawing passes safely for mutually exclusive administrative polygons.
  • A flat style with stroke-color and stroke-width draws crisp white borders while leaving the dark basemap visible inside.

Pitfalls

  • Topological deduplication applies to wire transfer size only: once parsed into OpenLayers memory, each district becomes a standalone Polygon feature whose shared boundary edges are stored and stroked per polygon.
  • Omitting the layers filter imports every named geometry collection inside the TopoJSON file—potentially stacking outer city outlines on top of interior districts.

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.