In this post we'll use TMaps vector tiles with MapLibre GL JS, the open-source WebGL map library, and build a little style switcher with four styles.

Live demo: examples.tmaps.tn/03-vector-maplibre-styles

How TMaps vector tiles work

You don't request the tiles yourself. Each style is a JSON document that follows the Mapbox Style Specification:

https://tiles.tmaps.tn/v-tile/{style}.json?api_key=YOUR_API_KEY

That JSON lists the tile sources, the fonts (glyphs), the icons (sprites) and how every layer should be drawn. MapLibre reads it and fetches the rest on its own. There are four styles to choose from:

1. A first vector map

You'll need a TMaps API key from the TMaps console, with your domain (and localhost) in its Authorized Domains.

<!doctype html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Vector map of Tunisia</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/maplibre-gl@5.6.0/dist/maplibre-gl.css">
  <script src="https://cdn.jsdelivr.net/npm/maplibre-gl@5.6.0/dist/maplibre-gl.js"></script>
  <style>
    html, body, #map { height: 100%; margin: 0; }
  </style>
</head>
<body>
  <div id="map"></div>
  <script>
    const API_KEY = 'YOUR_API_KEY';

    const map = new maplibregl.Map({
      container: 'map',
      style: `https://tiles.tmaps.tn/v-tile/streets.json?api_key=${API_KEY}`,
      center: [10.1815, 36.8002], // Tunis, as [lng, lat]
      zoom: 12,
      maxZoom: 18,
    });

    map.addControl(new maplibregl.NavigationControl(), 'top-right');
  </script>
</body>
</html>

One thing to watch: MapLibre takes [longitude, latitude], the opposite of Leaflet's [lat, lng]. Mixing them up is the most common reason a map opens in the middle of the ocean.

2. Switch styles without reloading the map

map.setStyle(url) swaps the style but keeps the map, its position and its controls. A basic switcher is only a few lines:

const styleUrl = (name) => `https://tiles.tmaps.tn/v-tile/${name}.json?api_key=${API_KEY}`;

for (const name of ['streets', 'dark', 'terrain', 'sunny']) {
  const button = document.createElement('button');
  button.textContent = name;
  button.addEventListener('click', () => map.setStyle(styleUrl(name)));
  document.body.append(button);
}

Here's the same view of Tunis in the other three styles. First dark, which works well on dashboards:

Then terrain:

And sunny:

Follow the user's dark mode

Since switching is instant, you can simply follow the operating system's theme:

const dark = window.matchMedia('(prefers-color-scheme: dark)');
const applyTheme = () => map.setStyle(styleUrl(dark.matches ? 'dark' : 'streets'));

dark.addEventListener('change', applyTheme);
applyTheme();

3. Tilt and rotate

The map is drawn with WebGL, so you can tilt and rotate it, which raster tiles simply can't do:

map.jumpTo({
  center: [10.179, 36.799], // Medina of Tunis
  zoom: 15.5,
  pitch: 60,     // tilt, in degrees
  bearing: -25,  // rotation, in degrees
});

Users can do the same thing themselves with a right-click drag on desktop, or two fingers on a phone.

4. Customize a style

The style JSON is yours to tweak. Download it, change the layers (colours, fonts, which labels show up at which zoom), and host your own copy. Just keep two things in mind:

• the tile URLs in sources must still point to tiles.tmaps.tn with your api_key, because that's how your usage is authenticated;
• you're free to change layers, and also glyphs and sprite if you host your own fonts and icons.

Raster or vector?

For a simple map embedded in a page, raster tiles with Leaflet are hard to beat. When the map is the heart of your product, go vector.

Going further

• About TMaps: Tunisia maps, geocoding and routing API
• Live demos: examples.tmaps.tn
• Source code, MIT licensed: github.com/tmaps-tn/tmaps-snippets
• Postman collection: postman.com/tmaps-tn/tmaps-api
• Vector tiles documentation: tmaps.tn/documentation

Questions or feedback? Leave a comment or write to support@tmaps.tn.