Vector data · Angular, React and OpenLayers

Create a map from a local Mapbox style

Apply a complete Mapbox GL v8 style document to an OpenLayers map using ol-mapbox-style and local TMS municipality vector tiles around Kraków.

Local municipality polygons and boundaries around Kraków rendered from a complete Mapbox GL style document.
A screenshot of the example. Municipal boundaries: Państwowy Rejestr Granic © GUGiK.

What this example shows

Municipal polygons and administrative borders across the Kraków metropolitan area render from a self-contained Mapbox GL v8 JSON style document that configures the vector-tile source, background, fill and boundary layers of the entire OpenLayers map in both Angular and React.

When you need it

Teams designing cartography in Maputnik or maintaining cross-platform Mapbox GL / MapLibre style JSON documents often want that single JSON specification to own the entire map’s sources, layer order and styling inside OpenLayers.

Using the full-map apply workflow from ol-mapbox-style hydrates an OpenLayers Map directly from local or self-hosted GL style JSON with zero cloud vendor lock-in.

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.

mapbox-style.html
<aol-map height="480px" ariaLabel="PRG municipality boundaries styled with a local Mapbox GL style">
  <aol-interaction-default />
  <aol-control-defaults [attributionOptions]="attributionOptions" />
  <aol-control-fullscreen />
</aol-map>

@if (styleError()) {
  <p role="status">The local map style could not be loaded.</p>
}
mapbox-style.scss
:host {
  display: block;
}
mapbox-style.shared.ts
import { attachMapboxVectorLayer, retainMapboxMapStyle, type MapboxVectorLayerOptions } from 'cc-openlayers/core';
import type OLMap from 'ol/Map.js';
import Layer from 'ol/layer/Layer.js';
import VectorTileLayer from 'ol/layer/VectorTile.js';
import VectorTileSource from 'ol/source/VectorTile.js';
import type { Extent } from 'ol/extent.js';
import { createXYZ } from 'ol/tilegrid.js';
import {
  municipalityMaxZoom,
  municipalityTileBounds,
  municipalityTileDirectory,
  municipalityTileSize,
  municipalityTileUrl,
} from '../canvas-tiles-tms/canvas-tiles-tms.shared';

export const municipalityStyleUrl = new URL(`${municipalityTileDirectory}/mapbox-style.json`, document.baseURI).href;
export const municipalitySourceId = 'prg-municipalities';
export const municipalityStyleLayerIds = [
  'prg-background',
  'prg-municipality-fill',
  'prg-municipality-boundary',
] as const;
export const municipalityAttributionOptions = { collapsible: false } as const;

const globalGrid = createXYZ({ maxZoom: municipalityMaxZoom, tileSize: municipalityTileSize });
const finestBounds = municipalityTileBounds[municipalityMaxZoom];
const topLeft = globalGrid.getTileCoordExtent([municipalityMaxZoom, finestBounds.minX, finestBounds.minY]);
const bottomRight = globalGrid.getTileCoordExtent([municipalityMaxZoom, finestBounds.maxX, finestBounds.maxY]);

/** The aligned EPSG:3857 envelope of only the PRG fixture's recorded tile cells. */
export const municipalityFixtureExtent: Extent = [topLeft[0], bottomRight[1], bottomRight[2], topLeft[3]];

const municipalitySourceIds = [municipalitySourceId] as const;

function configureMunicipalityMapStyle(layers: readonly Layer[]): void {
  const vectorLayers = layers.filter(
    (layer): layer is VectorTileLayer<VectorTileSource> => layer instanceof VectorTileLayer
  );
  if (vectorLayers.length !== 1) throw new Error('The local style must create one municipal vector-tile layer.');
  for (const layer of vectorLayers) {
    const source = layer.getSource();
    if (!source) throw new Error('The local style must configure its municipal vector source.');
    const grid = source.getTileGrid();
    const projection = source.getProjection();
    if (
      !grid ||
      projection?.getCode() !== 'EPSG:3857' ||
      grid.getTileSize(0) !== municipalityTileSize ||
      grid.getMaxZoom() !== municipalityMaxZoom
    ) {
      throw new Error('The local style must use the finite 512-pixel Web Mercator fixture grid.');
    }
    source.setTileUrlFunction(municipalityTileUrl);
    layer.setExtent(municipalityFixtureExtent);
  }
}

const mapStyleOptions = {
  sourceIds: municipalitySourceIds,
  layerIds: municipalityStyleLayerIds,
  configureLayers: configureMunicipalityMapStyle,
} as const;

/** Applies a complete local GL style through the library's framework-neutral map owner. */
export function ownMunicipalityMapStyle(map: OLMap, onError: () => void): () => void {
  return retainMapboxMapStyle(map, municipalityStyleUrl, { ...mapStyleOptions, onError });
}

function configureMunicipalityVectorSource(source: VectorTileSource): void {
  source.setTileUrlFunction(municipalityTileUrl);
}

const municipalityVectorLayerOptions: MapboxVectorLayerOptions = {
  styleUrl: municipalityStyleUrl,
  extent: municipalityFixtureExtent,
  minZoom: 0,
  maxZoom: municipalityMaxZoom,
  declutter: true,
};

/** Creates the package's specialized MapboxVectorLayer with the finite local PRG tile mapping. */
export function ownMunicipalityVectorLayer(map: OLMap, onError: () => void): () => void {
  return attachMapboxVectorLayer(map, municipalityVectorLayerOptions, {
    configureSource: configureMunicipalityVectorSource,
    onError,
  });
}
mapbox-style.ts
import { AfterViewInit, ChangeDetectionStrategy, Component, OnDestroy, signal, viewChild } from '@angular/core';
import {
  ControlFullScreenComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  MapComponent,
} from 'cc-openlayers';
import { municipalityAttributionOptions, ownMunicipalityMapStyle } from './mapbox-style.shared';

/** Applies a complete local Mapbox GL style to the map, including its camera and background. */
@Component({
  selector: 'app-mapbox-style',
  imports: [ControlFullScreenComponent, DefaultControlComponent, DefaultInteractionComponent, MapComponent],
  changeDetection: ChangeDetectionStrategy.OnPush,
  templateUrl: './mapbox-style.html',
  styleUrl: './mapbox-style.scss',
})
export class MapboxStyle implements AfterViewInit, OnDestroy {
  protected readonly attributionOptions = municipalityAttributionOptions;
  protected readonly styleError = signal(false);
  private readonly map = viewChild.required(MapComponent);
  private releaseStyle?: () => void;

  ngAfterViewInit(): void {
    this.releaseStyle = ownMunicipalityMapStyle(this.map().instance, () => this.styleError.set(true));
  }

  ngOnDestroy(): void {
    this.releaseStyle?.();
  }
}

Architecture and OpenLayers mechanics

Once the Angular or React component mounts its OpenLayers Map instance, ol-mapbox-style’s full-map apply function reads the local GL v8 JSON specification, instantiates the described 512-pixel TMS municipality MVT source on the Web Mercator grid, and populates the map’s layer stack automatically.

How it works

  • The full-map apply API from ol-mapbox-style configures sources and layers directly on the mounted OpenLayers map instance.
  • A local Mapbox GL v8 style JSON styles bundled PRG municipality MVTs around Kraków without external Mapbox or MapTiler accounts.
  • Both the style JSON and the local tile pyramid align on Web Mercator projection, 512-pixel logical tiles, TMS row order and source-layer naming.

Pitfalls

  • Distinguish full-map apply (which owns and populates the map’s layer collection from a complete GL document) from single-layer applyStyle (which styles one existing VectorTileLayer) or MapboxVectorLayer.
  • Style JSON source definitions must match the tile pyramid’s exact projection and row orientation—swapping in a geographic WorldCRS84Quad tileset requires matching CRS and grid configuration.

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.