Essentials · Angular, React and OpenLayers

A tile loading progress bar

Build an accessible tile-loading progress bar for an OpenLayers map by counting tileloadstart, tileloadend and tileloaderror source events.

A street map of Kraków while it loads the tiles of zoom 13, with a green progress bar at half the width of the map's bottom edge and Tiles loaded 8 of 16 below it.
A screenshot of the example. Map data © OpenStreetMap contributors.

What this example shows

Along the bottom edge of a street map of Kraków, a slim progress bar advances smoothly from 0% to 100% during pans and zooms while a counter below reports exact tile progress (such as Tiles loaded 8 of 16), fading out a quarter-second after completion.

When you need it

High-resolution aerial imagery, multi-layer WMTS feeds and slow rural connections can queue dozens of tiles per zoom; a determinate progress bar shows steady forward momentum that an indeterminate spinner cannot convey.

Exposing exact completion percentages through standard ARIA progressbar attributes also gives assistive technology users clear feedback during heavy raster downloads.

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.

tile-load-events.ts
import { ChangeDetectionStrategy, Component, computed, signal } from '@angular/core';
import {
  CoordinateComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  LayerTileComponent,
  MapComponent,
  SourceOsmComponent,
  ViewComponent,
} from 'cc-openlayers';

/** A progress bar over the map, driven by the tile source's load events and shown while the map loads. */
@Component({
  selector: 'app-tile-load-events',
  imports: [
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    LayerTileComponent,
    MapComponent,
    SourceOsmComponent,
    ViewComponent,
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <div class="example-progress-frame">
      <aol-map height="480px" (loadStart)="show()" (loadEnd)="hide()">
        <aol-interaction-default />
        <aol-control-defaults />
        <aol-view [zoom]="12">
          <aol-coordinate [x]="19.9368" [y]="50.0614" srid="EPSG:4326" />
        </aol-view>
        <aol-layer-tile>
          <aol-source-osm
            (tileLoadStart)="requested()"
            (tileLoadEnd)="loaded.update((count) => count + 1)"
            (tileLoadError)="loaded.update((count) => count + 1)"
          />
        </aol-layer-tile>
      </aol-map>
      <div
        class="example-progress"
        role="progressbar"
        aria-label="Tile loading progress"
        aria-valuemin="0"
        aria-valuemax="100"
        [attr.aria-valuenow]="percent()"
        [style.width]="width()"
        [style.visibility]="visible() ? 'visible' : 'hidden'"
      ></div>
    </div>
    <div class="example-controls">
      <label>
        Tiles loaded
        <output>{{ loaded() }} of {{ loading() }}</output>
      </label>
      <p class="example-hint">Pan or zoom the map: the bar shows the tiles loaded so far.</p>
    </div>
  `,
})
export class TileLoadEvents {
  readonly loading = signal(0);
  readonly loaded = signal(0);
  readonly visible = signal(false);
  /** The share of the requested tiles that have finished, in per cent to one decimal. */
  protected readonly percent = computed(() =>
    this.loading() ? Math.round((this.loaded() / this.loading()) * 1000) / 10 : 0
  );
  /** The bar's width: the share while the map loads, nothing while the bar is hidden. */
  protected readonly width = computed(() => (this.visible() && this.loading() ? `${this.percent()}%` : '0px'));
  /** Whether the map has finished the load that the counts belong to. */
  private ended = false;
  private hiding?: ReturnType<typeof setTimeout>;

  /** Counts a requested tile; the first one after a finished load starts the counts again. */
  protected requested(): void {
    if (this.ended) {
      this.ended = false;
      this.loading.set(0);
      this.loaded.set(0);
    }
    this.loading.update((count) => count + 1);
  }

  /** Shows the bar; a load that starts while the one before is being hidden keeps it. */
  protected show(): void {
    clearTimeout(this.hiding);
    this.visible.set(true);
  }

  /** Hides the bar a moment after the map has loaded, so the full bar can be seen. */
  protected hide(): void {
    this.ended = true;
    this.hiding = setTimeout(() => this.visible.set(false), 250);
  }
}

Architecture and OpenLayers mechanics

The component listens directly to tile-source lifecycle hooks: (tileLoadStart) increments the total requested counter, while both (tileLoadEnd) and (tileLoadError) increment the settled counter so a single 404 or timeout never leaves the bar stuck at 95%.

Map-level (loadStart) reveals the bar and (loadEnd) schedules a 250 ms hide timeout so users briefly see 100% completion. Because OpenLayers dispatches the very first tile requests slightly before map (loadStart), counters reset cleanly on the first tile requested after a settled cycle, and role="progressbar" with aria-valuenow exposes percentage progress.

How it works

  • (tileLoadStart) counts requested tiles while (tileLoadEnd) and (tileLoadError) both count completed requests so failed tiles never stall completion.
  • Map (loadStart) reveals the bar and (loadEnd) hides it 250 ms later so the 100% state remains briefly visible.
  • Counters reset on the first tile of a new load cycle because initial tile requests fire just ahead of the map’s loadstart event.
  • role="progressbar" and aria-valuenow communicate live percentage completion to screen readers.

Pitfalls

  • Failing to reset counters between separate pan gestures causes cumulative totals to jump backward or start at 66% on the next move.
  • Always clear the 250 ms hide timer if a new pan begins while the previous bar is still visible, otherwise the pending timeout hides the active bar mid-load.

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.