Vector data · Angular, React and OpenLayers
Preview a dropped vector tile
Drop raw Mapbox Vector Tile files onto an OpenLayers map and georeference them at z, x and y tile coordinates using a custom MVT format class.

What this example shows
Over northern Kraków on OpenStreetMap, numeric inputs below the map specify a tile coordinate (defaulting to zoom 10, column 568, row 346) alongside a button to download a sample binary tile from Esri’s World Basemap.
Dropping that .mvt / .pbf file onto the canvas decodes its local tile-pixel geometries, scales them precisely into the Web Mercator square of that z / x / y cell in default blue, and lists the name or layer of the hovered feature below.
When you need it
Backend engineers building custom MVT generators, PostGIS ST_AsMVT queries or tile-cache pipelines often need to inspect a single raw .pbf file captured from disk or curl in its exact geographic location.
Because a standalone protobuf vector tile stores coordinates only from 0..4096 inside an unnamed square without world coordinates, supplying the target z / x / y extent lets OpenLayers place and inspect the raw tile on a real map.
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-mvt.tsimport { ChangeDetectionStrategy, Component, signal, viewChild } from '@angular/core';
import 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 type { ReadOptions } from 'ol/format/Feature';
import MVT from 'ol/format/MVT';
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 { createXYZ } from 'ol/tilegrid';
import {
CoordinateComponent,
DefaultControlComponent,
DefaultInteractionComponent,
type DragAndDropFormat,
DragAndDropInteractionComponent,
LayerTileComponent,
MapComponent,
SourceOsmComponent,
ViewComponent,
} from 'cc-openlayers';
/** Files dropped on the map are shown as layers; an MVT tile is placed at the tile coordinate set below the map. */
@Component({
selector: 'app-drag-and-drop-custom-mvt',
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">
<span>
Tile coordinate
<label>z <input type="number" [value]="z()" (input)="z.set(number($event))" /></label>
<label>x <input type="number" [value]="x()" (input)="x.set(number($event))" /></label>
<label>y <input type="number" [value]="y()" (input)="y.set(number($event))" /> </label>
</span>
<button type="button" (click)="download()">Download sample</button>
<output>{{ info() }}</output>
</div>
`,
})
export class DragAndDropCustomMvt {
readonly z = signal(10);
readonly x = signal(568);
readonly y = signal(346);
readonly info = signal('');
private readonly map = viewChild.required(MapComponent);
/** The MVT format needs the extent of the tile it reads, which is the one named by the coordinate inputs. */
protected readonly formats: DragAndDropFormat[] = [this.tileFormat(), GPX, GeoJSON, IGC, KML, TopoJSON];
protected number(event: Event): number {
return (event.target as HTMLInputElement).valueAsNumber;
}
/** The names of the features under the pixel. */
protected describe(event: MapBrowserEvent): void {
if (event.dragging) return;
const names: string[] = [];
this.map().instance.forEachFeatureAtPixel(event.pixel, (feature) => {
const name = feature.get('name') || feature.get('_name') || feature.get('layer');
if (name) names.push(name);
});
this.info.set(names.join(', '));
}
protected async download(): Promise<void> {
const [z, x, y] = [this.z(), this.x(), this.y()];
const response = await fetch(
`https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/tile/${z}/${y}/${x}.pbf`
);
const link = document.createElement('a');
link.href = URL.createObjectURL(await response.blob());
link.download = `${z}-${x}-${y}.mvt`;
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] });
}
private tileFormat(): MVT<Feature> {
const tile = () => [this.z(), this.x(), this.y()];
const TileFormat = class extends MVT<Feature> {
constructor() {
super({ featureClass: Feature });
}
override readFeatures(source: ArrayBuffer, options?: ReadOptions) {
return super.readFeatures(source, { ...options, extent: createXYZ().getTileCoordExtent(tile()) });
}
};
return new TileFormat();
}
} 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.
drag-and-drop-custom-mvt.react.tsximport { useMemo, useRef, useState } from 'react';
import type { Extent } from 'ol/extent.js';
import Feature from 'ol/Feature.js';
import type OLMap from 'ol/Map.js';
import type MapBrowserEvent from 'ol/MapBrowserEvent.js';
import GPX from 'ol/format/GPX.js';
import GeoJSON from 'ol/format/GeoJSON.js';
import IGC from 'ol/format/IGC.js';
import KML from 'ol/format/KML.js';
import type { ReadOptions } from 'ol/format/Feature.js';
import MVT from 'ol/format/MVT.js';
import TopoJSON from 'ol/format/TopoJSON.js';
import type { DragAndDropEvent } from 'ol/interaction/DragAndDrop.js';
import VectorLayer from 'ol/layer/Vector.js';
import VectorSource from 'ol/source/Vector.js';
import { createXYZ } from 'ol/tilegrid.js';
import {
Coordinate,
DefaultControls,
DefaultInteractions,
DragAndDropInteraction,
Map,
OSMSource,
TileLayer,
View,
} from 'cc-openlayers/react';
import type { DragAndDropFormat } from 'cc-openlayers/core';
/** The MVT format needs the extent of the tile it reads, which is the one named by the coordinate inputs. */
function tileFormat(tile: () => number[]): MVT<Feature> {
const TileFormat = class extends MVT<Feature> {
constructor() {
super({ featureClass: Feature });
}
override readFeatures(source: ArrayBuffer, options?: ReadOptions) {
return super.readFeatures(source, { ...options, extent: createXYZ().getTileCoordExtent(tile()) });
}
};
return new TileFormat();
}
/** Files dropped on the map are shown as layers; an MVT tile is placed at the tile coordinate set below the map. */
export function DragAndDropCustomMvt() {
const [z, setZ] = useState(10);
const [x, setX] = useState(568);
const [y, setY] = useState(346);
const [info, setInfo] = useState('');
const map = useRef<OLMap>(null);
// The format reads the tile coordinate the inputs show; a changed coordinate gives the interaction a new format.
const formats = useMemo<DragAndDropFormat[]>(
() => [tileFormat(() => [z, x, y]), GPX, GeoJSON, IGC, KML, TopoJSON],
[z, x, y]
);
const number = (event: { target: HTMLInputElement }): number => event.target.valueAsNumber;
/** The names of the features under the pixel. */
const describe = (event: MapBrowserEvent): void => {
if (event.dragging) return;
const names: string[] = [];
map.current?.forEachFeatureAtPixel(event.pixel, (feature) => {
const name = feature.get('name') || feature.get('_name') || feature.get('layer');
if (name) names.push(name);
});
setInfo(names.join(', '));
};
const download = async (): Promise<void> => {
const response = await fetch(
`https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/tile/${z}/${y}/${x}.pbf`
);
const link = document.createElement('a');
link.href = URL.createObjectURL(await response.blob());
link.download = `${z}-${x}-${y}.mvt`;
link.click();
};
const show = (event: DragAndDropEvent): void => {
const source = new VectorSource({ features: event.features as Feature[] });
const current = map.current;
if (!current) return;
current.addLayer(new VectorLayer({ source }));
current.getView().fit(source.getExtent() as Extent, { padding: [40, 40, 40, 40] });
};
return (
<>
<Map ref={map} height="480px" onPointerMove={describe} onClick={describe}>
<DefaultInteractions />
<DragAndDropInteraction formatConstructors={formats} onAddFeatures={show} />
<DefaultControls />
<View zoom={10}>
<Coordinate x={19.9368} y={50.0614} srid="EPSG:4326" />
</View>
<TileLayer>
<OSMSource />
</TileLayer>
</Map>
<div className="example-controls">
<span>
Tile coordinate
<label>
z <input type="number" value={z} onChange={(event) => setZ(number(event))} />
</label>
<label>
x <input type="number" value={x} onChange={(event) => setX(number(event))} />
</label>
<label>
y <input type="number" value={y} onChange={(event) => setY(number(event))} />{' '}
</label>
</span>
<button type="button" onClick={() => void download()}>
Download sample
</button>
<output>{info}</output>
</div>
</>
);
}How the React version works
A dropped MVT file lands on the tile named by the fields below the map, because the format needs the tile's extent; the other formats work as usual.
What both versions share
OpenLayers renders the map and handles the interactions; the cc-openlayers/core layer gives both adapters the same view binding (MapViewBinding) and the same conversion of coordinates from EPSG:4326 to the map's projection.
From Angular to React
| Angular | React |
|---|---|
<aol-interaction-draganddrop [formatConstructors] (addFeatures)> | <DragAndDropInteraction formatConstructors onAddFeatures>; the format lists are module constants |
one format list reading the coordinate signals | useMemo on [z, x, y]: a change of the coordinates gives the interaction a new format list (React does not allow reading a ref while rendering) |
(input) of the number fields | onChange and useState |
(pointerMove) and viewChild of the map | onPointerMove (and onClick) on Map with useRef<OLMap>; the reading in useState |
Who creates, updates and disposes
Map creates the ol/Map in useLayoutEffect and disposes of it on unmount; each layer, source and interaction component adds its object to the parent it gets from context and removes it in its effect's cleanup, as ngOnDestroy does in Angular. The onAddFeatures handler adds the layers of dropped files to the map; they go away with the map on unmount.
Architecture and OpenLayers mechanics
A custom subclass of MVT overrides readFeatures to look up the current z, x and y input signals at drop time, compute the corresponding projected bounding box via createXYZ().getTileCoordExtent, and pass that extent into the decoder so internal tile units transform into Web Mercator.
Configuring featureClass: Feature instructs the decoder to output full OpenLayers Feature instances suitable for a standard VectorLayer rather than lightweight RenderFeatures.
How it works
- Extending
MVTinjects the projectedextentfromcreateXYZ().getTileCoordExtentintoreadFeaturesfor the chosen z, x and y inputs. - Supplying that tile
extentscales internal tile-space coordinates into their true Web Mercator position. featureClass: Featuredecodes full interactive Feature objects compatible with DragAndDrop vector layers.- Reading coordinate signals lazily when a file is dropped lets one persistent interaction place consecutive tiles at different grid cells.
Pitfalls
- Binary
.mvtfiles carry zero embedded z / x / y headers of their own—if the numeric inputs do not match the tile you dropped, its roads and buildings will appear validly scaled inside the wrong geographic square. - Remember that ArcGIS REST vector-tile URLs order path segments z/y/x (row before column), whereas standard XYZ inputs and file names order them
z, x, y.
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.