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.

OpenStreetMap north of Kraków with the features of the dropped vector tile in OpenLayers' default blue over its square, and the features under the pointer listed below the map.
A screenshot of the example. Vector tiles: Esri World Basemap (Esri, TomTom, Garmin, FAO, NOAA, USGS, OpenStreetMap contributors and the GIS User Community). Map data © OpenStreetMap contributors.

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.ts
import { 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();
  }
}

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 MVT injects the projected extent from createXYZ().getTileCoordExtent into readFeatures for the chosen z, x and y inputs.
  • Supplying that tile extent scales internal tile-space coordinates into their true Web Mercator position.
  • featureClass: Feature decodes 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 .mvt files 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.

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.