Projections · Angular, React and OpenLayers
A 512-pixel geographic vector-tile grid
Configure an explicit 512-pixel EPSG:4326 vector-tile grid in OpenLayers and apply a local Mapbox GL v8 style with matching zoom resolutions.

What this example shows
Centred on Kraków in an EPSG:4326 view ([zoom]="12", [constrainOnlyCenter]="true"), PRG municipality vector tiles load on an explicit 512-pixel geographic tile grid ([-180, 90] origin) and render through a local Mapbox GL v8 style document with expanded attribution.
When you need it
Commercial and enterprise EPSG:4326 vector-tile providers frequently serve 512-pixel logical tiles (maxResolution = 180 / 512) rather than OpenLayers’ default 256-pixel grid—requiring both the TileGrid and ol-mapbox-style zoom stops to share that exact resolution ladder.
Aligning resolutions across aol-tilegrid and applyStyle keeps tile requests and zoom-dependent Mapbox GL rules in exact lockstep.
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.
vector-tiles-4326.shared.tsimport { extend, createEmpty, type Extent } from 'ol/extent.js';
import type { TileCoord } from 'ol/tilecoord.js';
import { createXYZ } from 'ol/tilegrid.js';
import municipalityMetadata from '../../../assets/krakow/municipality-tiles/WorldCRS84Quad.json';
const TILESET_PATH = 'assets/krakow/municipality-tiles/WorldCRS84Quad';
const WORLD_EXTENT: Extent = [-180, -90, 180, 90];
const WORLD_ORIGIN = [-180, 90] as const;
const LOGICAL_TILE_SIZE = 512;
const GLOBAL_MAX_RESOLUTION = 180 / LOGICAL_TILE_SIZE;
const limitsByZoom = new Map(
municipalityMetadata.tileMatrixSetLimits.map((limits) => [Number(limits.tileMatrix), limits])
);
const sourceZooms = [...limitsByZoom.keys()];
const MIN_SOURCE_ZOOM = Math.min(...sourceZooms);
const MAX_SOURCE_ZOOM = Math.max(...sourceZooms);
/** The 512-pixel grid keeps each WorldCRS84Quad matrix cell at its original z/x/y indices. */
export const geographicTileGrid = createXYZ({
extent: WORLD_EXTENT,
minZoom: MIN_SOURCE_ZOOM,
tileSize: LOGICAL_TILE_SIZE,
maxResolution: GLOBAL_MAX_RESOLUTION,
maxZoom: MAX_SOURCE_ZOOM,
});
/** A value declaration for the Angular and React source adapters. */
export const geographicTileGridDeclaration = {
extent: WORLD_EXTENT,
minZoom: MIN_SOURCE_ZOOM,
origin: [...WORLD_ORIGIN],
resolutions: geographicTileGrid.getResolutions(),
tileSize: LOGICAL_TILE_SIZE,
};
/**
* The finite PRG coverage comes from the fixture's finest matrix limits. Extents are generated by
* the public grid API so the geographic grid remains the single owner of cell geometry.
*/
export const municipalityFixtureExtent: Extent = (() => {
const limits = limitsByZoom.get(MAX_SOURCE_ZOOM);
if (!limits) throw new Error(`Missing WorldCRS84Quad limits for zoom ${MAX_SOURCE_ZOOM}.`);
const extent = createEmpty();
extend(extent, geographicTileGrid.getTileCoordExtent([MAX_SOURCE_ZOOM, limits.minTileCol, limits.minTileRow]));
extend(extent, geographicTileGrid.getTileCoordExtent([MAX_SOURCE_ZOOM, limits.maxTileCol, limits.maxTileRow]));
return extent;
})();
/** Keep the local PRG source credit expanded beside the map. */
export const municipalityAttributionOptions = { collapsible: false };
/**
* Uses the PRG metadata to suppress requests outside the actual local fixture. OL tile coordinates
* and the fixture's WorldCRS84Quad links both use a top-left, positive row index.
*/
export function municipalityTileUrl(tileCoord: TileCoord | null): string | undefined {
if (!tileCoord) return undefined;
const [zoom, column, row] = tileCoord;
const limits = limitsByZoom.get(zoom);
if (
!limits ||
column < limits.minTileCol ||
column > limits.maxTileCol ||
row < limits.minTileRow ||
row > limits.maxTileRow
) {
return undefined;
}
return new URL(`${TILESET_PATH}/${zoom}/${row}/${column}.mvt`, document.baseURI).href;
}
/** Local Mapbox GL v8 style shared by the geographic and reprojected examples. */
export const municipalityStyle = {
version: 8,
sources: {
municipalities: {
type: 'vector',
tiles: [`${TILESET_PATH}/{z}/{y}/{x}.mvt`],
minzoom: 4,
maxzoom: MAX_SOURCE_ZOOM,
tileSize: LOGICAL_TILE_SIZE,
},
},
layers: [
{
id: 'municipality-fill',
type: 'fill',
source: 'municipalities',
'source-layer': 'municipalities',
paint: { 'fill-color': '#f7f7e9' },
},
{
id: 'municipality-boundaries',
type: 'line',
source: 'municipalities',
'source-layer': 'municipalities',
paint: {
'line-color': '#8c8b8b',
'line-width': ['interpolate', ['linear'], ['zoom'], 4, 0.6, 10, 1.6],
},
},
{
id: 'background',
type: 'background',
paint: { 'background-color': '#d1d1d1' },
},
],
} as const;vector-tiles-4326.tsimport { AfterViewInit, ChangeDetectionStrategy, Component, OnDestroy, signal, viewChild } from '@angular/core';
import { applyBackground, applyStyle } from 'ol-mapbox-style';
import {
CoordinateComponent,
DefaultControlComponent,
DefaultInteractionComponent,
FormatMVTComponent,
LayerVectorTileComponent,
MapComponent,
SourceVectorTileComponent,
TileGridComponent,
ViewComponent,
} from 'cc-openlayers';
import {
geographicTileGrid,
geographicTileGridDeclaration,
municipalityAttributionOptions,
municipalityFixtureExtent,
municipalityStyle,
municipalityTileUrl,
} from './vector-tiles-4326.shared';
/** The local PRG MVT fixture rendered in its WorldCRS84Quad geographic projection. */
@Component({
selector: 'app-vector-tiles-4326',
imports: [
CoordinateComponent,
DefaultControlComponent,
DefaultInteractionComponent,
FormatMVTComponent,
LayerVectorTileComponent,
MapComponent,
SourceVectorTileComponent,
TileGridComponent,
ViewComponent,
],
changeDetection: ChangeDetectionStrategy.OnPush,
template: `
<aol-map height="480px" [ariaLabel]="ariaLabel">
<aol-interaction-default />
<aol-control-defaults [attributionOptions]="attributionOptions" />
<aol-view projection="EPSG:4326" [zoom]="12" [extent]="municipalityFixtureExtent" [constrainOnlyCenter]="true">
<aol-coordinate [x]="19.9368" [y]="50.0614" srid="EPSG:4326" />
</aol-view>
<aol-layer-vectortile [declutter]="true" background="#d1d1d1">
<aol-source-vectortile
projection="EPSG:4326"
[tileUrlFunction]="tileUrlFunction"
attributions="Boundaries: PRG, Główny Urząd Geodezji i Kartografii"
>
<aol-format-mvt />
<aol-tilegrid
[extent]="grid.extent"
[minZoom]="grid.minZoom"
[origin]="grid.origin"
[resolutions]="grid.resolutions"
[tileSize]="grid.tileSize"
/>
</aol-source-vectortile>
</aol-layer-vectortile>
</aol-map>
@if (styleError()) {
<p role="status">The local vector style could not be applied.</p>
}
`,
})
export class VectorTiles4326 implements AfterViewInit, OnDestroy {
protected readonly ariaLabel = 'Geographic vector tiles over Kraków';
protected readonly grid = geographicTileGridDeclaration;
protected readonly attributionOptions = municipalityAttributionOptions;
protected readonly municipalityFixtureExtent = municipalityFixtureExtent;
protected readonly tileUrlFunction = municipalityTileUrl;
protected readonly styleError = signal(false);
private readonly layer = viewChild.required(LayerVectorTileComponent);
private destroyed = false;
ngAfterViewInit(): void {
const layer = this.layer().instance;
void Promise.all([
applyStyle(layer, municipalityStyle, {
resolutions: geographicTileGrid.getResolutions(),
updateSource: false,
}),
applyBackground(layer, municipalityStyle),
]).catch(() => {
if (!this.destroyed) this.styleError.set(true);
});
}
ngOnDestroy(): void {
this.destroyed = true;
}
} The React version uses the library's React adapter, cc-openlayers/react: each component creates the OpenLayers object it names when it mounts, updates it from its props and disposes of it when it unmounts.
vector-tiles-4326.react.tsximport { useCallback, useEffect, useState } from 'react';
import { applyBackground, applyStyle } from 'ol-mapbox-style';
import type OLVectorTileLayer from 'ol/layer/VectorTile.js';
import {
Coordinate,
DefaultControls,
DefaultInteractions,
Map,
useLayer,
useMVTFormat,
useTileGrid,
VectorTileLayer,
VectorTileSource,
View,
} from 'cc-openlayers/react';
import {
geographicTileGrid,
geographicTileGridDeclaration,
municipalityAttributionOptions,
municipalityFixtureExtent,
municipalityStyle,
municipalityTileUrl,
} from './vector-tiles-4326.shared';
function ApplyMunicipalityStyle({ onError }: { onError: () => void }) {
const layer = useLayer() as OLVectorTileLayer;
useEffect(() => {
let active = true;
void Promise.all([
applyStyle(layer, municipalityStyle, {
resolutions: geographicTileGrid.getResolutions(),
updateSource: false,
}),
applyBackground(layer, municipalityStyle),
]).catch(() => {
if (active) onError();
});
return () => {
active = false;
};
}, [layer, onError]);
return null;
}
/** The local PRG MVT fixture rendered in its WorldCRS84Quad geographic projection. */
export function VectorTiles4326React() {
const [styleError, setStyleError] = useState(false);
const format = useMVTFormat();
const tileGrid = useTileGrid(geographicTileGridDeclaration);
const reportStyleError = useCallback(() => setStyleError(true), []);
return (
<>
<Map height="480px" ariaLabel="Geographic vector tiles over Kraków">
<DefaultInteractions />
<DefaultControls attributionOptions={municipalityAttributionOptions} />
<View projection="EPSG:4326" zoom={12} extent={municipalityFixtureExtent} constrainOnlyCenter>
<Coordinate x={19.9368} y={50.0614} srid="EPSG:4326" />
</View>
<VectorTileLayer declutter background="#d1d1d1">
<VectorTileSource
projection="EPSG:4326"
tileUrlFunction={municipalityTileUrl}
tileGrid={tileGrid}
format={format}
attributions="Boundaries: PRG, Główny Urząd Geodezji i Kartografii"
/>
<ApplyMunicipalityStyle onError={reportStyleError} />
</VectorTileLayer>
</Map>
{styleError ? <p role="status">The local vector style could not be applied.</p> : null}
</>
);
}vector-tiles-4326.shared.tsimport { extend, createEmpty, type Extent } from 'ol/extent.js';
import type { TileCoord } from 'ol/tilecoord.js';
import { createXYZ } from 'ol/tilegrid.js';
import municipalityMetadata from '../../../assets/krakow/municipality-tiles/WorldCRS84Quad.json';
const TILESET_PATH = 'assets/krakow/municipality-tiles/WorldCRS84Quad';
const WORLD_EXTENT: Extent = [-180, -90, 180, 90];
const WORLD_ORIGIN = [-180, 90] as const;
const LOGICAL_TILE_SIZE = 512;
const GLOBAL_MAX_RESOLUTION = 180 / LOGICAL_TILE_SIZE;
const limitsByZoom = new Map(
municipalityMetadata.tileMatrixSetLimits.map((limits) => [Number(limits.tileMatrix), limits])
);
const sourceZooms = [...limitsByZoom.keys()];
const MIN_SOURCE_ZOOM = Math.min(...sourceZooms);
const MAX_SOURCE_ZOOM = Math.max(...sourceZooms);
/** The 512-pixel grid keeps each WorldCRS84Quad matrix cell at its original z/x/y indices. */
export const geographicTileGrid = createXYZ({
extent: WORLD_EXTENT,
minZoom: MIN_SOURCE_ZOOM,
tileSize: LOGICAL_TILE_SIZE,
maxResolution: GLOBAL_MAX_RESOLUTION,
maxZoom: MAX_SOURCE_ZOOM,
});
/** A value declaration for the Angular and React source adapters. */
export const geographicTileGridDeclaration = {
extent: WORLD_EXTENT,
minZoom: MIN_SOURCE_ZOOM,
origin: [...WORLD_ORIGIN],
resolutions: geographicTileGrid.getResolutions(),
tileSize: LOGICAL_TILE_SIZE,
};
/**
* The finite PRG coverage comes from the fixture's finest matrix limits. Extents are generated by
* the public grid API so the geographic grid remains the single owner of cell geometry.
*/
export const municipalityFixtureExtent: Extent = (() => {
const limits = limitsByZoom.get(MAX_SOURCE_ZOOM);
if (!limits) throw new Error(`Missing WorldCRS84Quad limits for zoom ${MAX_SOURCE_ZOOM}.`);
const extent = createEmpty();
extend(extent, geographicTileGrid.getTileCoordExtent([MAX_SOURCE_ZOOM, limits.minTileCol, limits.minTileRow]));
extend(extent, geographicTileGrid.getTileCoordExtent([MAX_SOURCE_ZOOM, limits.maxTileCol, limits.maxTileRow]));
return extent;
})();
/** Keep the local PRG source credit expanded beside the map. */
export const municipalityAttributionOptions = { collapsible: false };
/**
* Uses the PRG metadata to suppress requests outside the actual local fixture. OL tile coordinates
* and the fixture's WorldCRS84Quad links both use a top-left, positive row index.
*/
export function municipalityTileUrl(tileCoord: TileCoord | null): string | undefined {
if (!tileCoord) return undefined;
const [zoom, column, row] = tileCoord;
const limits = limitsByZoom.get(zoom);
if (
!limits ||
column < limits.minTileCol ||
column > limits.maxTileCol ||
row < limits.minTileRow ||
row > limits.maxTileRow
) {
return undefined;
}
return new URL(`${TILESET_PATH}/${zoom}/${row}/${column}.mvt`, document.baseURI).href;
}
/** Local Mapbox GL v8 style shared by the geographic and reprojected examples. */
export const municipalityStyle = {
version: 8,
sources: {
municipalities: {
type: 'vector',
tiles: [`${TILESET_PATH}/{z}/{y}/{x}.mvt`],
minzoom: 4,
maxzoom: MAX_SOURCE_ZOOM,
tileSize: LOGICAL_TILE_SIZE,
},
},
layers: [
{
id: 'municipality-fill',
type: 'fill',
source: 'municipalities',
'source-layer': 'municipalities',
paint: { 'fill-color': '#f7f7e9' },
},
{
id: 'municipality-boundaries',
type: 'line',
source: 'municipalities',
'source-layer': 'municipalities',
paint: {
'line-color': '#8c8b8b',
'line-width': ['interpolate', ['linear'], ['zoom'], 4, 0.6, 10, 1.6],
},
},
{
id: 'background',
type: 'background',
paint: { 'background-color': '#d1d1d1' },
},
],
} as const;How the React version works
The existing PRG municipality MVTs can be read directly on an explicit geographic grid rather than discovered through the OGC tileset adapter. The source uses 512 logical pixels per tile and the corresponding resolution ladder. A local Mapbox v8 style receives the geographic resolutions so its zoom-dependent appearance follows that grid.
What both versions share
The fixture's WorldCRS84Quad matrix levels 4–10 originally describe 256-pixel logical cells. Doubling the logical tile size and halving each resolution keeps the same geographic cell, matrix identifier, row and column. The origin remains the global [-180, 90]; finite fixture limits constrain requests without moving it. This is vector data: the logical tile size is not a raster image's decoded width. The example reuses the existing MVT decoder, vector-tile layer and source, explicit tile-grid API and public ol-mapbox-style helpers. Source data, attribution and geographic indexing remain unchanged. The local municipality style replaces the original provider's basemap cartography.
From Angular to React
| Angular | React |
|---|---|
A child <aol-tilegrid> declares the source grid | useTileGrid supplies the same grid |
<aol-format-mvt> declares the format | useMVTFormat supplies the format |
<aol-source-vectortile> owns the source | <VectorTileSource> owns the source |
<aol-view> keeps geographic coordinates | <View> keeps the same geographic coordinates |
Who creates, updates and disposes
The existing adapters own the map, layer, source and format. Applying a local style must preserve the declared source. Work completing after teardown must not attach resources or update a newer map. Attribution stays expanded and the named map describes the geographic example.
Architecture and OpenLayers mechanics
aol-source-vectortile (projection="EPSG:4326") declares <aol-tilegrid> explicitly with 512-pixel tileSize, global origin [-180, 90], and halved resolutions starting at 180 / 512 across matrix levels 4–10.
In ngAfterViewInit, applyStyle (updateSource: false, passing geographicTileGrid.getResolutions()) and applyBackground from ol-mapbox-style style the aol-layer-vectortile without overwriting its custom geographic source.
How it works
- Local PRG municipality MVT cells are served on an explicit 512-pixel
EPSG:4326grid styled via a local Mapbox GL v8 document. - Using 512-pixel logical tiles with origin
[-180, 90]and top resolution 180 / 512 preserves identical geographic cell footprints to 256-pixelWorldCRS84Quadmatrices. - Passing the source grid’s resolution array into
applyStyle(updateSource: false) aligns Mapbox GL zoom expressions with geographic scale. - View extent bounds navigation around Kraków while keeping global tile matrix coordinates intact.
Pitfalls
- Doubling
tileSizefrom 256 to512without halving the resolution ladder doubles the geographic footprint of every cell and requests completely wrong{z}/{x}/{y}files. - Never replace the global
[-180, 90]grid origin with your local city bounding box—use view/gridextentto restrict requests while keeping matrix row/column numbering global.
Related examples
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.