Vector tiles for basemaps

Hi community, we currently have an old image based MapServer basemap map layer and we’re trying to update it to a VectorTileServer using ArcGIS.

From what it seems the vector one is not supported by DHIS2 maps-app/maps-gl as the basemap does not load with the XYZ provider.

After checking the code it is hardcoded to ‘raster’ type, and it could theoretically be changes to ‘vector’ but the opacity feature should be refactored and if the vector layers cannot be extracted from the pbf file a new field might be needed in maintenance-app.

Related JIRA issue from one year ago: Log in - DHIS 2 JIRA

cc: @Bjorn_Sandvik

1 Like

Hi Alexis,

It is correct that vector tiles are not currently supported in DHIS2. We planned to add support, but it was delayed when Mapbox GL JS changed their license (no longer open source). For DHIS2 Maps 2.37, we have switched to MapLibre GL JS. We are also considering a switch to don’t have built-in support for MVT vector tile, and we need to consider the total bundle size of the mapping library as we are often used on low-bandwidth networks.

Short story: If we continue to use MapLibre GL JS we will likely add support for vector tiles in an upcoming release, but currently you need to use the raster version from your map server.


Hi Bjorn,

The new official basemaps WHO is building use vector tiles. Legal department requires it to be used on official publications, meaning maps generated with DHIS2 won’t be suitable to be used online or in official reports.

Right now the old rasterized ones are used but for several regions they do not exactly match the new updated boundaries and it is a really important feature that impacts the extent that DHIS2 is used internally.

We have both basemaps and overlays our users need to be displayed. Some of these overlays are very recent and do not have a rasterized version (not even an outdated one).

I’d say that moving to a solution like that is unable to provide vector tiles would have a negative impact in the long run, and, if possible, adding support for VectorTileServers is a high priority requirement (with backwards compatibility of at least 2.36).

The new vector basemaps the GIS team has built offer different layers (such as multiple level regional boundary selection, labels to be displayed and greyed areas for special zones), allowing map users to show/hide these layers. Following the official guidelines is mandatory before publishing any new map.


Hi Alexis, we will consider to include vector tiles support in 2.38. I think backporting to 2.36 is unlikely, but you should be able to update the rasterized ones you already have.

There are many considerations to make - and we also need to measure the longevity of MapLibre GL JS, as we need to rely on open source technologies. Upgrading Mapbox GL JS v2 is not possible, and we can’t stay on an unsupported version.

The plan now is to stick to MapLibre GL JS for a couple of versions (hopefully with vector tiles support), and to continuously monitor the libraries available.

Luckily, also work with MapLibre/MapBox GL so the technologies can be combined (with bundle splitting to avoid large downloads for most users).

@SferaDev it should be possible to serve raster tiles which exactly match the official WHO vector data from ArcGIS server - you would need to pre-select the vector layers and labels etc. to render at each raster zoom level. This should allow any DHIS2 version to consume the raster basemap until DHIS2 maps can support vector tiles.

Here is an example which shows both raster image and VectorTileServer outputs for the official ArcGIS basemap styles: Basemap layer service | Documentation | ArcGIS Developer

1 Like

If we decide on adding vector tiles support in 2.38, it would be nice to have the WHO basemap as a use case. If available for us to test, please pass me the config details (

We also plan to support a base layer option so you can specify to place the thematic layers or overlays below the labels of the basemap.

1 Like