In the world of data visualization, we usually think of dashboards, tables, or standard charts. However, maps offer a unique dimension: spatial context. By adding a layer of distance and geographic relationship, maps help users understand data more deeply.

While there are many libraries available, today we’re diving into MapLibre , an open-source TypeScript library engineered to accelerate rendering using the GPU. If your project involves rendering hundreds or even thousands of Points of Interest (POIs), this tool is a perfect fit.

Thai Water Application (TWA) utilizes MapLibre to visualize hydrological datasets to analyze water resources in Thailand

⸻

Why MapLibre? The Battle of DOM vs. Canvas

Normally, when we think of a map, we think of a marker locating a location. This works perfectly for five or ten points. But what happens when you have a thousand?

Standard markers are typically rendered as elements in the DOM tree. Creating a thousand HTML elements will cause most browsers to lag, freeze, or crash. This is where we shift to the HTML5 Canvas.

MapLibre utilizes WebGL, a JavaScript API that enables hardware-accelerated graphics by tapping into the device’s GPU. This approach, now standard for heavyweights like Google Maps and Windy, allows for high refresh rates (up to 60fps), ensuring a silky-smooth user experience even with massive datasets.

The Power Duo: Sources and Layers

MapLibre organizes data using a “Source” and “Layer” architecture. Think of it this way:

Sources act as your datastore and hold the raw geographic data.
Layers define how that data looks.

Source: A Complete Guide to Sources and Layers in React and Mapbox GL JS

Because a single source can be used by multiple layers, the visualization possibilities are endless. For example, you could have 3 layers as follows:

Layer A renders the POI as a simple circle.
Layer B displays text labels or values from the POI properties.
Layer C adds a pulse animation to specific featured POIs to make them stand out.

Managing Density with Clustering

When your map gets crowded, MapLibre’s built-in clustering properties come to the rescue. It automatically calculates distances and zoom levels to group points together. Since a cluster is technically part of the Source, you can assign unique layer properties to it, allowing you to customize exactly how those group icons appear.

Handling Interaction: Layer-Based Events

In a traditional setup that utilizes the DOM to display markers, you have to assign each individual element to listen to an event. It’s like a teacher trying to listen to 1,000 students all whispering at the same time. In MapLibre, it doesn't create individual objects for each POI. Instead, it draws everything onto a single Canvas and handles events one time at the top level.

Instead of 1,000 listeners, you add one listener to the map and tell it which layer-id to watch. If layers overlap, you simply specify the order of priority. Once MapLibre picks up the interaction, it returns a wealth of data, including the source properties and the internal map state, giving you full control over the user's next step.

Sprites

How about marker icons? Let’s say we want to visualize a POI with an icon of a bicycle to visualize how many cycling spots are available in Thailand. MapLibre has a layer type called Symbol, and we can assign icon-image to the layer’s layout properties to visualize it. To use custom icons, MapLibre uses a Sprite, a single image file containing all your icons, as shown below, paired with a JSON file that acts as a coordinate map.

A common limitation is that standard sprites cannot change icon colors dynamically like SVG icons. If you need to change an icon's color based on data at runtime, you need SDF (Signed Distance Field) Sprites.

SDF sprites store the shape of the icon rather than the pixels, allowing you to use properties like icon-color and icon-halo-color to color it or even stretch, shrink, or scale some part of the sprite dynamically.

The good news is that we do not need to create these manually! I recommend Spreet, a CLI tool that converts your SVGs into both standard and SDF sprites instantly.

Logic at Runtime: Expressions

Finally, there are Expressions. These are formulas that allow you to control visualization dynamically. Whether you need to format strings, add if-else logic, or check if a value is null, Expressions run at the rendering level to ensure your map reacts instantly to data changes without a full reload.

Ready to Build?

MapLibre might have a steeper learning curve than basic plug-and-play maps, but the performance and flexibility it offers are unmatched for complex applications. Whether you're tracking a fleet of vehicles or mapping every coffee shop in the country, MapLibre ensures your data isn't just seen; it's experienced.

Beyond the Marker: High-Performance Map Visualization with MapLibre