To use the library, you will need an access token. First go to the sign in page and sign in to your account. After signing in, go to the dashboard and create a new token.

To install the arenarium/maps library for MapLibre using npm, run the following command in your project directory:

To initialize the library, first add a container element to your HTML where the map will be rendered.

Import the MapManager and the required css from the main library.

Next, use the MaplibreProvider class which requires a maplibregl.Map class, a maplibregl.Marker class and a maplibregl.MapOptions object. Use the MaplibreProvider instance, along with the token key, to initialize the map manager.

You can change the map's visual appearance by setting a predefined dark or light theme:

Alternatively, you can apply a custom map style by providing a URL to a JSON file that adheres to the MapLibre Style Specification. You can also override specific color properties within a custom style.

Markers toggle between the pin and the tooltip elements as the user zooms in. The pin is displayed when there is no room for the tooltip. When the user zooms in and more space is available, more tooltips are displayed. Which tooltips are displayed first is determined primarily by the ranking of the markers — the higher the rank, the sooner the tooltip is displayed.

To add markers to the map, you first need to define an array of MapMarkerData objects. Provide the base marker data and the configuration for the tooltip, pin and popup. The configurations have body callbacks which should return a HTMLElement.

Use the updateMarkers method on the map manager to update the map with new markers. If some of the provided markers already exist on the map with the same id, it will be assumed that the data is the same (width, height, body...). This approach is designed for continuous updates of map markers.

When updating the markers, you can let the library try to automatically measure the sizes of the provided elements, or use the dimensions property to manually set the sizes. Using it will also slightly improve loading performance when working with a large number of complex elements.

The following are body callback functions for the current demo. Use them to return the HTMLElement object for the tooltip, pin and popup. You can create them manually or by using a specific frontend library such as React, Vue, Svelte, or any other library that supports creating and manipulating DOM elements.

To remove all markers from the map, use the removeMarkers method:

To manually toggle the popup of a marker, use the showPopup and hidePopup methods:

MapConfiguration allows you to customize various aspects of the map and marker behavior when initializing the MapManager. You can control settings such as pin fading, popup panning, event handlers and more.

To use, simply pass your configuration object when creating the map:

Refer to the MapConfiguration schema for all available options and further customize your map experience.