Join us online - 19th of November
Save your spot

Class TilePreloaderMaptiler

Handles tile preloading for a Map instance.

Prefetches tiles for every active tile source in the current style and stores them in the SDK tile cache so MapLibre can render them without a network round-trip.

Preload strategies include geographic bounds with a zoom range (preloadForBounds), prefetch a tilePyramid for a LatLngBounds (preloadForCameraPositions), a sampled linear camera path (preloadForLinearPath), and explicit "z/x/y" tile IDs (preloadByTileIDs). Each method returns a Promise that resolves when the preloading is complete. Call abortAll() to cancel in-flight requests.

API Key Usage: Every tile fetched by this class counts against your MapTiler Cloud API key quota. Prefer narrow zoom ranges and small geographic areas where possible, and use the onProgress callback to monitor consumption.

If you update the version of the tile preloader, please update the version in the EXPERIMENTAL_TILE_PRELOADING_VERSION constant.

import { EXPERIMENTAL_TILE_PRELOADING_VERSION } from "./version";
 
EXPERIMENTAL_TILE_PRELOADING_VERSION = "0.2.0";
Index
constructor
abortAll preloadByTileIDs preloadForBounds preloadForCameraPositions preloadForLinearPath

  • Cancels all in-flight preload requests. Called automatically when a new camera movement begins so stale prefetches do not waste quota.

    Returns void

  • Preloads a specific set of tiles by their IDs ("z/x/y" format).

    Parameters

    Returns Promise<void>

    A promise that resolves when the preloading is complete.

    await map.preloadByTileIDs({
  tileIDs: ["12/1205/1540", "12/1206/1540"],
});

  • Preloads all tiles within a geographic bounds across a range of zoom levels.

    Parameters

    Returns Promise<void>

    A promise that resolves when the preloading is complete.

    API Key Usage: Tile count grows exponentially with zoom level. A wide zoom range over a large area can trigger thousands of requests.

    await map.preloadTilesForBounds({
  bounds: map.getBounds(),
  minZoom: 8,
  maxZoom: 12,

  • Preloads tiles along a linear camera path (used by panTo and easeTo overrides).

    Parameters

    Returns Promise<TileCoord[]>

    A promise that resolves when the preloading is complete.

    await map.preloadForLinearPath({
  start: { lng: -74.006, lat: 40.7128, zoom: 12 },
  end: { lng: -73.935, lat: 40.730, zoom: 14 },
});
Was this helpful?