docs/pages/ui/components/map.mdx - dev - githubmirror/tabler

docs/pages/ui/components/map.mdx
119 строк5 KB
Paweł Kuna
Improve docs SEO, performance and content quality (#2841)
11 авг 2026, 15:45
11 авг 2026, 15:4539634cb
---
title: Map
summary: A map shows places and markers on an interactive world map. Tabler provides the markup and the setup code, and the map itself is rendered by Mapbox GL JS.
description: Show interactive maps with markers using Mapbox GL JS. Tabler provides the container markup and setup code to get you started.
related: [/ui/components/vector-map]
layout: '@layouts/DocsMdxLayout.astro'
---
import Example from '@components/Example.astro';
import { Code } from 'astro:components';

## Overview

The map is a small wrapper around [Mapbox GL JS](https://docs.mapbox.com/mapbox-gl-js/). Tabler gives you the container markup and a short init script. Mapbox draws the tiles, handles zoom, and renders the markers.

A Mapbox account and an access token are needed, because every map load calls the Mapbox API. If you only need a simple map of countries or regions, use the [vector map](/ui/components/vector-map) instead. It needs no account and no network calls.

## Installation

Add the Mapbox GL JS script and stylesheet to your page. Tabler uses version 1.8.0:

<Code
	lang="html"
	code={`<link href="https://api.mapbox.com/mapbox-gl-js/v1.8.0/mapbox-gl.css" rel="stylesheet" />
<script src="https://api.mapbox.com/mapbox-gl-js/v1.8.0/mapbox-gl.js"></script>`}
/>

Then create a free account on [mapbox.com](https://www.mapbox.com/) and copy your public access token. It starts with `pk.`. Set it once, before you create a map:

```js
mapboxgl.accessToken = 'pk.your-token-here'
```

Use a public token only. A secret token (`sk.`) must never be sent to the browser. Limit the token to your own domains in the Mapbox dashboard.

## Usage

### Markup

Put the map container inside a `ratio` element, so the map keeps its shape on every screen size. Give the inner element an `id` and the `w-100 h-100` classes.

<Example codeOnly>
<div class="ratio ratio-16x9"> <div> <div id="map-simple" class="w-100 h-100"></div> </div> </div>
</Example>

Change the shape with the ratio classes, for example `ratio-21x9` for a wide map or `ratio-1x1` for a square one.

### Init the map

Create the map after the DOM is ready. Pass the id of your container, a style, a zoom level, and a center point.

```js
document.addEventListener('DOMContentLoaded', function () {
  mapboxgl.accessToken = 'pk.your-token-here'

  const map = new mapboxgl.Map({
    container: 'map-simple',
    style: 'mapbox://styles/mapbox/streets-v11',
    zoom: 13,
    center: [13.4049, 52.518827],
  })
})
```

`center` takes the longitude first and the latitude second. This is the Mapbox order, and it is the opposite of what most map services show.

### Map styles

Set `style` to any Mapbox style URL. These three are used in the Tabler demos:

| Style | Result |
| --- | --- |
| `mapbox://styles/mapbox/streets-v11` | Default street map. |
| `mapbox://styles/mapbox/light-v10` | Light map, good under charts and markers. |
| `mapbox://styles/mapbox/satellite-v9` | Satellite photos. |

### Markers

Add a marker for each place. `setLngLat` takes the same longitude and latitude order as `center`.

```js
const cities = [
  [-58.666667, -34.58333333], // Buenos Aires
  [16.366667, 48.2], // Vienna
  [116.383333, 39.91666667], // Beijing
]

cities.forEach(function (coords) {
  new mapboxgl.Marker({ color: 'var(--tblr-primary)' }).setLngLat(coords).addTo(map)
})
```

The `color` option is written to the `fill` attribute of the marker icon. A CSS variable works there, so `var(--tblr-primary)` keeps the markers in your theme color, including after a theme change.

## Examples

### Map in a card

Add a card title above the map. This is the usual layout for a small map next to other content.

<Example codeOnly>
<div class="card"> <div class="card-body"> <div class="card-title">Simple map</div> <div class="ratio ratio-16x9"> <div> <div id="map-card" class="w-100 h-100"></div> </div> </div> </div> </div>
</Example>

### Full-card map

Drop the card body to let the map fill the whole card. Add `rounded` to the container, so the map follows the card corners.

<Example codeOnly>
<div class="card"> <div class="ratio ratio-21x9"> <div> <div id="map-full" class="w-100 h-100 rounded"></div> </div> </div> </div>
</Example>

Live versions of these maps are on the [maps preview page](https://preview.tabler.io/maps.html).

## 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 an `aria-label` to the map container, 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.