Recommended way to switch tile urls in mapbox-gl-js

Question

Situation

We render a raster layer to the map. The layer's source has an initial tile-url. Now we want to change the tile-url of the source and trigger a reload for the new tiles. E.g. we have tiles for different points in time and we want to step through the different time steps.

What can be done in mapbox-gl@0.21.0

map.addSource('tile-source', {...});
map.addLayer('tile-layer', {source: 'tile-source', ...});

// react to a button click or what ever to trigger tile url change
...
const source = map.getSource('tile-source');
source.tiles = ['new-tile-url'];
source._pyramid.reload();

This works fine. But, of course, using private methods is bad practice; see the reason below:

What can be done with the current version from github (Latest commit b155118, 2016-07-28)

// init map, add layer, add source, like above
const source = map.getSource('tile-source');
source.tiles = ['new-tile-url'];

map.styles.sources['tile-source'].reload();

It has to be done this way, because the former TilePyramid has been refactored to a SourceCache. Here we are calling reload() on the SourceCache not the RasterTileSource. It seems that we don't have to use any private methods anymore, though this still looks like undocumented API, which may break in future versions.

Also there seems to be an issue with a memory leak when calling reload(): https://github.com/mapbox/mapbox-gl-js/issues/2266

Additionally the cache gets cleared when calling reload(). Which for now doesn't seem to be an issue.

// This yields a `RasterTileSource` instance
map.getSource('tile-source'); 

// This yields a `SourceCache` instance
map.styles.sources['tile-source'];

// What's really confusing too, at least namingwise
map.getStyle(); // <-- Yields the maps (visual) style

The SourceCache has the RasterTileSource instance as a private _source field.

Question

What is the recommended way to do something like this? Is this a feature being worked on? Is there an explanation why this isn't a feature (yet) or never will be?

Answer 1

Here is another way of changing the Mapbox GL JS Layer URL without removing, and adding the Source and Layer.

// Set the tile URL to a cache-busting URL (to circumvent browser caching behavior):
map.getSource('source-id').tiles = [ `http://some.url/{z}/{x}/{y}.pbf?dt=${Date.now()}` ]

// Remove the tiles for a particular source
map.style.sourceCaches['source-id'].clearTiles()

// Load the new tiles for the current viewport (map.transform -> viewport)
map.style.sourceCaches['source-id'].update(map.transform)

// Force a repaint, so that the map will be repainted without you having to touch the map
map.triggerRepaint()

I have figured out another solution. instead of sourceCache try _sourceCache function and type 'other' before your id.

map.style._sourceCaches['other:wms-source'].clearTiles();
map.style._sourceCaches['other:wms-source'].update(map.transform)

https://github.com/mapbox/mapbox-gl-js/issues/2941#issuecomment-518631078

Answer 2

Mapbox GL JS v2.13.0 released on 22 Feb 2023 Add methods for changing a raster tile source dynamically (e.g. setTiles, setUrl). (#12352)

So now you can update a raster source without remove layers and sources.

Answer 3

It sounds like you're trying to change the URL of a raster source. The proper way to do this in GL JS is to remove the source and then add a new source with the same id and the new url.

map.addSource('tile-source', {...});
map.addLayer('tile-layer', {source: 'tile-source', ...});

// react to a button click or what ever to trigger tile url change
...
map.removeSource('tile-source');
map.addSource('tile-source', {tiles: ['new-tile-url'], ...});