---
title: Map
summary: A map shows places and markers on an interactive world map. Tabler turns a single element into a themed map, and the map itself is rendered by MapLibre GL JS.
description: Show interactive maps with markers, popups and a matching dark mode from plain HTML, using MapLibre GL JS and free map tiles. No account or access token is needed.
added-in: '1.7.0'
related: [/ui/plugins/vector-map]
docs-libs: [maplibre-gl]
source: core/scss/vendor/_maplibre.scss
css-vars: map-marker
classnames:
component:
- class: ratio
desc: Wrapper that keeps the map at a fixed aspect ratio
- class: map-marker
desc: Marker drawn in HTML, a circle that can hold an icon, a count or an avatar
part:
- class: map-marker-label
desc: Short text under a marker
- class: map-controls
desc: Column of buttons in the top end corner of the map
modifier:
- class: map-marker-dot
desc: Small dot with no content
- class: map-marker-pulse
desc: Ring that grows out of the marker and fades, for a live position
- class: map-marker-pin
desc: Teardrop pin that points down, used with the bottom anchor
- class: map-popup-card
desc: Popup with no padding and a fixed width, for an image above the text
- class: map-tooltip
desc: Popup shown as a small dark label, for text on hover
color:
- class: map-marker-{color}
desc: Any theme color, for example map-marker-red or map-marker-green
size:
- class: ratio-{ratio}
desc: The aspect to hold, for example ratio-16x9 or ratio-21x9
---
import Example from '@components/Example.astro';
import Map from '@shared/components/demo/Map.astro';
import Icon from '@ui/Icon.astro';
import CodeDocs from '@components/CodeDocs.astro';
import { Code } from 'astro:components';
import { site } from '@shared/lib/site.ts';
import { cdnJsTag, cdnMapJsTag, cdnPluginSnippet } from '@lib/cdn-snippets.ts';
## Overview
The map component turns an element into an interactive map. Add `data-bs-toggle="map"` to it, set the center and the zoom with data attributes, and write the markers as child elements. No script is needed.
The map is drawn by [MapLibre GL JS](https://maplibre.org/maplibre-gl-js/docs/), an open-source map library, which you load next to Tabler. The map tiles come from [OpenFreeMap](https://openfreemap.org/). It needs no account and no access token, and it can be used in commercial projects.
If you only need a simple map of countries or regions, use the [vector map](/ui/plugins/vector-map) instead. It makes no network calls at all.
## Installation
The map component is not part of `tabler.js`. It ships as a small add-on, `tabler-map.js`, so pages without a map do not carry it. Load the MapLibre stylesheet, and the add-on after `tabler.js`; it adds `MapView` to the `tabler` object:
${cdnJsTag()}
${cdnMapJsTag()}`}
/>
The add-on loads MapLibre GL JS by itself, from `dist/libs/maplibre-gl` next to the Tabler scripts. Tabler uses version 6, which is published as an ES module. When your files are somewhere else, point the `library` option at the module: `data-bs-library="/vendor/maplibre-gl.mjs"`. The library loads two more files from its own folder, `maplibre-gl-shared.mjs` and `maplibre-gl-worker.mjs`, so keep the three together.
If the page sets `window.maplibregl` before the add-on runs, the component uses that and loads nothing. This is the way to go with a bundler:
```bash
npm install maplibre-gl
```
```js
import * as maplibregl from 'maplibre-gl'
import 'maplibre-gl/dist/maplibre-gl.css'
window.maplibregl = maplibregl
const { MapView } = await import('@tabler/core/dist/js/tabler-map.esm.js')
```
Older versions, including all of version 5, have a known security issue in the code that cleans the attribution text.
Browsers do not load ES modules from a page opened straight from the disk. Use a local server to see the maps while you work.
Tabler styles the map controls, popups and attribution to match the interface, in light and dark mode. These styles are in `tabler-vendors.css`, so load it after the MapLibre stylesheet:
## Usage
### Basic map
Put the map element inside a `ratio` element, so the map keeps its shape on every screen size. `data-bs-center` takes the longitude first and the latitude second. This is the opposite of what most map services show.
Change the shape with the ratio classes, for example `ratio-21x9` for a wide map or `ratio-1x1` for a square one.
### Map styles
The map uses a light gray style in light mode and a dark one in dark mode. Tabler softens their colors, so markers and data stand out. Set another style with `data-bs-map-style`: the name of an OpenFreeMap style, or the URL of any MapLibre style.
| Style | Result |
| --- | --- |
| `positron` | Light gray map. The default in light mode. |
| `dark` | Dark gray map. The default in dark mode. |
| `liberty` | Street map in color. |
| `bright` | Street map with stronger colors. |
| `fiord` | Dark blue map. |
`data-bs-map-style-dark` sets the style for dark mode. Styles from other providers work the same way, as long as they follow the MapLibre style format. Check the terms of each provider, as many of them need an API key or a paid plan.
### Dark mode
The map follows the nearest `data-bs-theme` and changes its style when the theme changes. Markers and popups stay on the map. To keep one look in both modes, set `data-bs-map-theme` to `light` or `dark`.
### Markers
Each child element with `data-bs-lng` and `data-bs-lat` becomes a marker. Use the `.map-marker` class to draw it: a circle in the primary color that can hold an icon, a short count or an avatar. Put a `.map-marker-label` element inside the marker for a short text under it.
Add `.map-marker-dot` for a small dot, or `.map-marker-pin` for a pin that points down. A pin needs `data-bs-anchor="bottom"`, so its tip sits on the place. Change the color with `.map-marker-{color}`.
Add `data-bs-draggable="true"` to let people move a marker, for example to pick an address. Add `.map-marker-pulse` for a ring that grows out of the marker, for a live position or a place that needs attention.
HTML markers work well for up to a few hundred places. For more, use [clusters](#clusters).
### Popups
Add `data-bs-popup` to a marker for a short text that opens when the marker is clicked. Tabler draws the popup as a small bordered panel with no arrow, and fades it in.
For richer content, put a `` inside the marker. Its content becomes the popup. Add the `map-popup-card` class to the template for a popup with an image: it removes the padding and sets a fixed width, so the image reaches the edges. `data-bs-close-button="true"` on the template adds a close button, and `data-bs-popup-open="true"` on the marker opens the popup from the start.
### Controls
Add `data-bs-controls="true"` for zoom buttons in the top corner of the map. They are regular Tabler buttons, so they follow the theme. For more buttons, pass a list of names:
| Name | Buttons |
| --- | --- |
| `zoom` | Zoom in and zoom out. |
| `north` | Turns the map back to north up. |
| `locate` | Moves the map to the position of the device. The browser asks for permission first. |
| `fullscreen` | Shows the map on the whole screen, and back. |
```html
```
The buttons have English names for screen readers. Change them with the `labels` option, by action:
```html
```
You can also write the buttons yourself. Any button with `data-bs-map-action` works on the map it is inside, or on the map its `data-bs-target` points at. The actions are `zoom-in`, `zoom-out`, `north`, `locate` and `fullscreen`. A button with no content gets a matching icon; put the buttons in a `.map-controls` element to place them in the top corner.
```html
```
### Route
Draw a path with `data-bs-route`: a list of `[longitude, latitude]` points. The line takes the primary color and is drawn again after a theme change. Mark its ends with markers.
```html
```
To show how far along a path something is, add `data-bs-route-progress` with the index of the point reached so far, counted from 0. The path up to that point stays solid and the rest is dashed.
```html
```
### Areas and other shapes
`data-bs-geojson` draws [GeoJSON](https://geojson.org/) over the map: areas with a light fill and an outline, lines, and points as small circles. Pass the GeoJSON itself, or the URL of a file.
```html
```
Both use the primary color. Set `data-bs-layer-color` to another color, for example `--tblr-red` or `#d63939`.
### Globe
Add `data-bs-globe="true"` to draw the map as a 3D globe. Use a low zoom, between 1 and 2, to see the whole globe. People can turn it by dragging.
```html
```
### Content over the map
To put buttons or a small card over the map, place them next to the map element and position them with the utility classes:
```html
```
### Attribution
MapLibre adds the credit for the map data in the corner of the map. OpenFreeMap requires it, so do not hide it.
## Layers
The route and GeoJSON options cover simple shapes. For anything more, such as clusters, dashed lines or circles sized by a value, take the MapLibre map from the component and use its own API. The `map` property is the [MapLibre map](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/).
A layer reads its data from a GeoJSON source. Layers are part of the map style, so add them in `onStyle()`. It runs when the style has loaded, and again each time the style changes, for example on a theme change.
```js
document.addEventListener('DOMContentLoaded', function () {
const view = tabler.MapView.getInstance('#map-stores')
view.onStyle(function (map) {
map.addSource('stores', { type: 'geojson', data: stores })
map.addLayer({
id: 'stores',
type: 'circle',
source: 'stores',
paint: { 'circle-color': tabler.MapView.color('--tblr-primary'), 'circle-radius': 6 },
})
})
// Runs once the map exists: the library may load a moment after the page
view.ready(function (map) {
map.on('click', 'stores', function (event) {
console.log(event.features[0].properties)
})
})
})
```
For an area, use a `Polygon` geometry with a `fill` layer, and a `line` layer for its outline.
### Theme colors in layers
MapLibre draws layers on a canvas, so a CSS variable does not work in `paint`, and neither do the `oklch()` values Tabler colors are written in. `MapView.color()` turns a variable, or any CSS color, into a plain `rgb()` color. Call it inside `onStyle()`, so the colors are read again after a theme change.
```js
tabler.MapView.color('--tblr-primary') // 'rgb(6, 111, 209)'
```
### Clusters
Put many points in a GeoJSON source with `cluster: true`. MapLibre then groups nearby points and splits the groups as you zoom in.
```js
map.addSource('stores', { type: 'geojson', data: stores, cluster: true, clusterRadius: 40 })
// Circle for each cluster, larger for more points
map.addLayer({
id: 'clusters',
type: 'circle',
source: 'stores',
filter: ['has', 'point_count'],
paint: { 'circle-color': tabler.MapView.color('--tblr-primary'), 'circle-radius': ['step', ['get', 'point_count'], 14, 10, 18, 25, 24] },
})
// Number of points in the cluster
map.addLayer({
id: 'cluster-count',
type: 'symbol',
source: 'stores',
filter: ['has', 'point_count'],
layout: { 'text-field': ['get', 'point_count_abbreviated'], 'text-font': ['Noto Sans Regular'], 'text-size': 12 },
paint: { 'text-color': '#ffffff' },
})
```
`text-font` has to be a font the map style provides. All OpenFreeMap styles have `Noto Sans Regular`.
### Tooltips
For a short label on hover, add the `map-tooltip` class to a MapLibre popup. It turns the popup into a small dark label.
```js
const tooltip = new maplibregl.Popup({ closeButton: false, offset: 12, className: 'map-tooltip' })
map.on('mousemove', 'cities', function (event) {
tooltip.setLngLat(event.lngLat).setText(event.features[0].properties.name).addTo(map)
})
map.on('mouseleave', 'cities', function () {
tooltip.remove()
})
```
Live versions of a route, an area, clusters, a bubble map, a globe with arcs and a city switcher are on the [maps preview page](https://preview.tabler.io/maps.html). The [map blocks page](https://preview.tabler.io/map-blocks.html) has larger examples: a store locator, a list of homes with prices on the map, a delivery tracker, an address form with a draggable pin, a server status map, a map of live users and a vector map of users by country.
## JavaScript
### Via data attributes
An element with `data-bs-toggle="map"` becomes a map when the `tabler-map.js` script loads:
### Via JavaScript
Create a map from your own code with the same options:
```js
const view = new tabler.MapView('#map', {
center: [13.405, 52.52],
zoom: 12,
controls: true,
})
```
### Options
Pass options as data attributes, with the name written in kebab case after `data-bs-`, or in the config object.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `library` | string | MapLibre in `dist/libs` | URL of the MapLibre GL JS module, loaded when `window.maplibregl` is not set. A relative URL starts at the Tabler script. `null` turns the loading off. |
| `center` | array, string | `[0, 0]` | Center of the map: `[longitude, latitude]`, or the two numbers in a string such as `"13.405,52.52"`. |
| `zoom` | number | `1` | Zoom level, from 0 for the whole world to about 20 for a building. |
| `mapStyle` | string | `'positron'` | Name of an OpenFreeMap style, or the URL of a MapLibre style. |
| `mapStyleDark` | string | `'dark'` | Style used in dark mode. Set `null` to keep `mapStyle` in both modes. |
| `mapTheme` | string | `'auto'` | `'auto'` follows the nearest `[data-bs-theme]`; `'light'` or `'dark'` keeps one look. |
| `palette` | boolean | `true` | Softer colors for the `positron` and `dark` styles. Other styles are left as they are. |
| `controls` | boolean, string | `false` | Buttons over the map: `true` for zoom, or a list of `zoom`, `north`, `locate` and `fullscreen`. |
| `labels` | object | `{}` | Names of the buttons for screen readers, by action: `zoom-in`, `zoom-out`, `north`, `locate`, `fullscreen`. |
| `route` | array | `null` | A path drawn as a line: a list of `[longitude, latitude]` points. |
| `routeProgress` | number | `null` | Index of the route point reached so far. The path up to it is solid, the rest is dashed. |
| `geojson` | object, string | `null` | GeoJSON drawn over the map: an object, or the URL of a file. |
| `layerColor` | string | `'--tblr-primary'` | Color of the route and the GeoJSON shapes: a CSS color or a custom property. |
| `globe` | boolean | `false` | Draw the map as a 3D globe. |
| `mapOptions` | object | `{}` | Any [MapLibre map option](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapOptions/), passed straight through. |
A marker element takes these attributes:
| Attribute | Description |
| --- | --- |
| `data-bs-lng`, `data-bs-lat` | Position of the marker. Both are needed. |
| `data-bs-anchor` | Part of the marker that sits on the position: `center` by default, `bottom` for a pin. |
| `data-bs-draggable` | Set `true` to let people move the marker. |
| `data-bs-popup` | Text of a popup that opens when the marker is clicked. |
| `data-bs-popup-open` | Set `true` to open the popup from the start. |
### Methods
| Name | Description |
| --- | --- |
| `map` | The MapLibre map, for layers, events and everything else the options do not cover. `null` until the library has loaded. |
| `ready(callback)` | Runs the callback with the MapLibre map once it exists. |
| `onStyle(callback)` | Runs the callback with the map each time a style loads. The place to add layers. |
| `markers` | The MapLibre markers made from the child elements, in document order. |
| `zoomIn()`, `zoomOut()` | Zooms the map by one level. |
| `resetNorth()` | Turns the map back to north up, with no tilt. |
| `locate()` | Moves the map to the position of the device. |
| `toggleFullscreen()` | Shows the map on the whole screen, and back. |
| `dispose()` | Removes the map, its markers and the instance. |
| `MapView.color(value)` | Turns a CSS variable or color into a plain `rgb()` color for a map layer. |
| `MapView.getInstance(element)` | Returns the instance for an element, or `null`. |
| `MapView.getOrCreateInstance(element)` | Returns the instance, or creates one. |
### Events
| Event | Description |
| --- | --- |
| `load.bs.map` | Fires on the map element once the map has loaded its style and first tiles. |
## Using Mapbox GL JS
MapLibre GL JS started as a fork of Mapbox GL JS, so the two share most of their API. The map component works with MapLibre only. To use Mapbox, write the map script yourself: load its script and stylesheet, set `mapboxgl.accessToken` to your public token, and use a `mapbox://` style URL.
## Accessibility
- The map is a picture for most users. Give the same information as text near it, for example the address or a list of places.
- Add `role="region"` and an `aria-label` to the map element, so screen reader users know what the map shows.
- Do not put an action only on a marker. Repeat it in a normal link or button below the map.
- Keep a visible fallback when the script fails to load, for example the address in text.