---
title: "TilePreloader | JavaScript maps SDK"
description: "Documentation for MapTiler SDK"
---

> For AI agents: a documentation index is available at [/llms.txt](https://docs.maptiler.com/llms.txt). Markdown versions of all pages are available by appending .md to any URL.

# Class TilePreloader`Maptiler`

Handles tile preloading for a [Map](https://docs.maptiler.com/sdk-js/api-reference/classes/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.

#### Remarks[](#remarks)

**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.

#### Example[](#example)

```typescript
import { EXPERIMENTAL_TILE_PRELOADING_VERSION } from "./version";
 
EXPERIMENTAL_TILE_PRELOADING_VERSION = "0.2.0";
```

##### Index

### Constructors[](#constructors)

[constructor](#constructor)

### Methods[](#methods)

[abortAll](#abortall) [preloadByTileIDs](#preloadbytileids) [preloadForBounds](#preloadforbounds) [preloadForCameraPositions](#preloadforcamerapositions) [preloadForLinearPath](#preloadforlinearpath)

## Constructors[](#constructors-1)

### `Maptiler`constructor[](#constructor)

-   new TilePreloader(map: [Map](https://docs.maptiler.com/sdk-js/api-reference/classes/Map/)): TilePreloader[](#constructortilepreloader)
    
    #### Parameters
    
    -   map: [Map](https://docs.maptiler.com/sdk-js/api-reference/classes/Map/)
    
    #### Returns TilePreloader
    

## Methods[](#methods-1)

### `Maptiler`abortAll[](#abortall)

-   abortAll(): void[](#abortall-1)
    
    Cancels all in-flight preload requests. Called automatically when a new camera movement begins so stale prefetches do not waste quota.
    
    #### Returns void
    

### `Maptiler`preloadByTileIDs[](#preloadbytileids)

-   preloadByTileIDs(options: [PreloadTilesOptions](https://docs.maptiler.com/sdk-js/api-reference/types/PreloadTilesOptions/)): Promise<void\>[](#preloadbytileids-1)
    
    Preloads a specific set of tiles by their IDs (`"z/x/y"` format).
    
    #### Parameters
    
    -   options: [PreloadTilesOptions](https://docs.maptiler.com/sdk-js/api-reference/types/PreloadTilesOptions/)
        
        The options for preloading tiles by tile IDs.
        
    
    #### Returns Promise<void\>
    
    A promise that resolves when the preloading is complete.
    
    #### Example[](#example-1)
    
    ```typescript
    await map.preloadByTileIDs({
      tileIDs: ["12/1205/1540", "12/1206/1540"],
    });
    ```
    

### `Maptiler`preloadForBounds[](#preloadforbounds)

-   preloadForBounds(options: [PreloadTilesForBoundsOptions](https://docs.maptiler.com/sdk-js/api-reference/types/PreloadTilesForBoundsOptions/)): Promise<void\>[](#preloadforbounds-1)
    
    Preloads all tiles within a geographic bounds across a range of zoom levels.
    
    #### Parameters
    
    -   options: [PreloadTilesForBoundsOptions](https://docs.maptiler.com/sdk-js/api-reference/types/PreloadTilesForBoundsOptions/)
        
        Options for preloading tiles for bounds.
        
    
    #### Returns Promise<void\>
    
    A promise that resolves when the preloading is complete.
    
    #### Remarks[](#remarks-1)
    
    **API Key Usage**: Tile count grows exponentially with zoom level. A wide zoom range over a large area can trigger thousands of requests.
    
    #### Example[](#example-2)
    
    ```typescript
    await map.preloadTilesForBounds({
      bounds: map.getBounds(),
      minZoom: 8,
      maxZoom: 12,
    ```
    

### `Maptiler`preloadForCameraPositions[](#preloadforcamerapositions)

-   preloadForCameraPositions(  
        \_\_namedParameters: [PreloadTilesForCameraPositionsOptions](https://docs.maptiler.com/sdk-js/api-reference/types/PreloadTilesForCameraPositionsOptions/),  
    ): Promise<[TileCoord](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.TileCoord/)\[\]\>[](#preloadforcamerapositions-1)
    
    Preloads tiles visible from each of the given camera positions.
    
    #### Parameters
    
    -   \_\_namedParameters: [PreloadTilesForCameraPositionsOptions](https://docs.maptiler.com/sdk-js/api-reference/types/PreloadTilesForCameraPositionsOptions/)
    
    #### Returns Promise<[TileCoord](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.TileCoord/)\[\]\>
    
    #### Remarks[](#remarks-2)
    
    **API Key Usage**: Each position triggers requests for all tiles visible from that viewpoint. More positions at higher zoom levels increase API usage significantly.
    

### `Maptiler`preloadForLinearPath[](#preloadforlinearpath)

-   preloadForLinearPath(  
        options: [PreloadTilesForLinearPathOptions](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.PreloadTilesForLinearPathOptions/),  
    ): Promise<[TileCoord](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.TileCoord/)\[\]\>[](#preloadforlinearpath-1)
    
    Preloads tiles along a linear camera path (used by panTo and easeTo overrides).
    
    #### Parameters
    
    -   options: [PreloadTilesForLinearPathOptions](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.PreloadTilesForLinearPathOptions/)
        
        The options for preloading tiles along a linear camera path.
        
    
    #### Returns Promise<[TileCoord](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.TileCoord/)\[\]\>
    
    A promise that resolves when the preloading is complete.
    
    #### Example[](#example-3)
    
    ```typescript
    await map.preloadForLinearPath({
      start: { lng: -74.006, lat: 40.7128, zoom: 12 },
      end: { lng: -73.935, lat: 40.730, zoom: 14 },
    });
    ```