Skip to content

[v8] Documentation #2471

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Pessimistress merged 2 commits into from
Jan 26, 2025
Merged

[v8] Documentation #2471

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b520e04
Split API reference
Pessimistress Jan 24, 2025
f7f99f2
Updates
Pessimistress Jan 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 4 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ npm install react-map-gl mapbox-gl
// Using Maplibre
import * as React from 'react';
import Map from 'react-map-gl/maplibre';
import 'maplibre-gl/dist/maplibre-gl.css';

function App() {
return (
Expand All @@ -56,11 +57,13 @@ _or_
```js
// Using Mapbox
import * as React from 'react';
import Map from 'react-map-gl';
import Map from 'react-map-gl/mapbox';
import 'mapbox-gl/dist/mapbox-gl.css';

function App() {
return (
<Map
// https://visgl.github.io/react-map-gl/docs/get-started/mapbox-tokens
mapboxAccessToken="<Mapbox access token>"
initialViewState={{
longitude: -100,
Expand All @@ -76,18 +79,6 @@ function App() {

Learn more with in our [Getting Started](https://visgl.github.io/react-map-gl/docs/get-started) guide.

### Using Mapbox Tokens

**Starting with v2.0, mapbox-gl requires a Mapbox token for any usage, with or without the Mapbox data service. See [about Mapbox tokens](/docs/get-started/mapbox-tokens.md) for your options.**

To show maps from a service such as Mapbox you will need to register on their website in order to retrieve an access token required by the map component, which will be used to identify you and start serving up map tiles. The service will be free until a certain level of traffic is exceeded.

There are several ways to provide a token to your app, as showcased in some of the example folders:

* Provide a `mapboxAccessToken` prop to the map component
* Set the `MapboxAccessToken` environment variable (or set `REACT_APP_MAPBOX_ACCESS_TOKEN` if you are using Create React App)
* Provide it in the URL, e.g `?access_token=TOKEN`


### Contribute

Expand Down
38 changes: 15 additions & 23 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,25 @@

# Introduction

<p align="center">
These docs are for
<a href="https://github.com/visgl/react-map-gl/tree/7.0-release/docs">
<img src="https://img.shields.io/badge/v7.0-brightgreen.svg?style=flat-square" />
</a>
Looking for an old version?
<a href="https://github.com/visgl/react-map-gl/tree/6.1-release/docs">
<img src="https://img.shields.io/badge/v6.1-brightgreen.svg?style=flat-square" />
</a>
<a href="https://github.com/visgl/react-map-gl/tree/5.3-release/docs">
<img src="https://img.shields.io/badge/v5.3-brightgreen.svg?style=flat-square" />
</a>
</p>
> These docs are for v8.0. For v7, see [here](https://github.com/visgl/react-map-gl/tree/7.1-release/docs).

react-map-gl is a suite of [React](http://facebook.github.io/react/) components for
[mapbox-gl](https://github.com/mapbox/mapbox-gl-js), [maplibre-gl](https://maplibre.org/maplibre-gl-js/docs/) or compatible libraries.
[mapbox-gl](https://www.npmjs.com/package/mapbox-gl), [maplibre-gl](https://www.npmjs.com/package/maplibre-gl) or compatible libraries.

| Library | Description |
| --- | --- |
| [MapLibre GL JS](https://github.com/MapLibre/maplibre-gl-js) | An open fork of mapbox-gl v1, that can be used without a mapbox token. |
| [Mapbox GL JS v1](https://github.com/mapbox/mapbox-gl-js) | The previous version of mapbox GL JS. This version is free open source and can be used with non-mapbox basemaps without a mapbox token. |
| [Mapbox GL JS v2](https://github.com/mapbox/mapbox-gl-js) | The latest version of Mapbox GL JS. Note that version 2 is not free open source, and a mapbox token is required and billable events are generated even if you do not use mapbox hosted basemaps. |
| Other mapbox-gl forks | It may be possible to use react-map-gl with other mapbox forks, but this is not a supported use case. Minor PRs to enable other forks to be used may be accepted. |
| [MapLibre GL JS](https://maplibre.org/maplibre-gl-js/docs/) | An Open-source TypeScript library for publishing web maps. |
| [Mapbox GL JS](https://www.mapbox.com/mapbox-gljs) | A JavaScript library for interactive, customizable vector maps on the web. |
| [Mapbox GL JS v1](https://github.com/mapbox/mapbox-gl-js/tree/release-v1.13.3) | The last free-open-source version of Mapbox GL JS. This version can be used without a Mapbox token if you do not use Mapbox hosted basemaps. |
| Other compatible forks | It may be possible to use react-map-gl with mapbox-gl/maplibre-gl forks, but this is not a supported use case. Minor PRs to enable other forks to be used may be accepted. |

For basemaps:
- You can load map data from Mapbox's own service.
- You can create and host your own map data using one of the many [open source tools](https://github.com/mapbox/awesome-vector-tiles).
If you need help choosing a base map library that is right for you:

- Decide where to get your vector map data.
+ `mapbox-gl` is designed to work seamlessly with Mapbox's own data service. You will need a billable Mapbox token to use it.
+ There are a number of [map data providers](./get-started/mapbox-tokens.md#display-maps-without-a-mapbox-token) who support `maplibre-gl`, with a variaty of data quality and price options.
+ You can create and host your own map tiles and use them with `maplibre-gl` for (almost) free, if you are comfortable of using [open source tools](./get-started/mapbox-tokens.md#display-maps-without-a-mapbox-token) and setting up a cloud storage account.
- Visit Mapbox and MapLibre websites for examples and documentation. Each library offer unique features that may not exist in another.

New to react-map-gl? [Get Started](./get-started/get-started.md)

Expand All @@ -44,10 +36,10 @@ This does not scale when we have many components that need to synchronize with e

Ultimately, in the spirit of the [reactive programming paradigm](https://en.wikipedia.org/wiki/Reactive_programming), data always flows **down**. As long as the map manages its own state, as mapbox-gl is designed to do, we risk the components going out of sync.

react-map-gl creates a fully reactive wrapper for mapbox-gl. The [Map](./api-reference/map.md) component can be fully [controlled](https://reactjs.org/docs/forms.html#controlled-components), that is, the map's camera would never deviate from the props that it's assigned. Read more about this core behavior in [state management](./get-started/state-management.md).
react-map-gl creates a fully reactive wrapper for mapbox-gl/maplibre-gl. The [Map](./api-reference/maplibre/map.md) component can be fully [controlled](https://reactjs.org/docs/forms.html#controlled-components), that is, the map's camera would never deviate from the props that it's assigned. Read more about this core behavior in [state management](./get-started/state-management.md).

## Limitations

In v7.0, react-map-gl was fully rewritten to better align its API with the underlying Mapbox GL JS library. Wherever the reactive usage patterns permits, the wrapper's props and methods are 1:1 mappings to their native API equivelants.

It is possible to call the native methods directly from the `Map` instance obtained via [getMap](./api-reference/map.md#gemap). However, doing so may result in the map's state to deviate from its props. For example, calling `map.setMaxZoom` directly will cause the map's constraint settings to differ from the value of the `maxZoom` prop. Generally speaking, calling a native method is disencouraged if the same thing can be achieved through the React interface. If a third-party plugin does so, then it may lead to some unexpected behaviors.
It is possible to call the native methods directly from the `Map` instance obtained via [getMap](./api-reference/maplibre/map.md#gemap). However, doing so may result in the map's state to deviate from its props. For example, calling `map.setMaxZoom` directly will cause the map's constraint settings to differ from the value of the `maxZoom` prop. Generally speaking, calling a native method is disencouraged if the same thing can be achieved through the React interface. If a third-party plugin does so, then it may lead to some unexpected behaviors.
42 changes: 5 additions & 37 deletions docs/api-reference/attribution-control.md → ...i-reference/mapbox/attribution-control.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,11 @@
# AttributionControl

React component that wraps the base library's `AttributionControl` class ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#attributioncontrol) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/AttributionControl/)).


import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs groupId="map-library">
<TabItem value="mapbox" label="Mapbox">
React component that wraps mapbox-gl's [AttributionControl](https://docs.mapbox.com/mapbox-gl-js/api/markers/#attributioncontrol) class.

```tsx
import * as React from 'react';
import Map, {AttributionControl} from 'react-map-gl';
import Map, {AttributionControl} from 'react-map-gl/mapbox';
import 'mapbox-gl/dist/mapbox-gl.css';

function App() {
return <Map
Expand All @@ -30,37 +24,11 @@ function App() {
}
```

</TabItem>
<TabItem value="maplibre" label="Maplibre">

```tsx
import * as React from 'react';
import Map, {AttributionControl} from 'react-map-gl/maplibre';

function App() {
return <Map
initialViewState={{
longitude: -100,
latitude: 40,
zoom: 3.5
}}
mapStyle="https://api.maptiler.com/maps/streets/style.json?key=get_your_own_key"
// disable the default attribution
attributionControl={false}
>
<AttributionControl customAttribution="Map design by me" />
</Map>;
}
```

</TabItem>
</Tabs>

## Properties

### Reactive Properties

#### `style`: CSSProperties {#style}
#### `style`: CSSProperties {#style}

CSS style override that applies to the control's container.

Expand All @@ -75,7 +43,7 @@ Any options supported by the `AttributionControl` class ([Mapbox](https://docs.m

Plus the following:

#### `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position}
#### `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position}

Default: `'bottom-right'`

Expand Down
35 changes: 3 additions & 32 deletions docs/api-reference/fullscreen-control.md → ...pi-reference/mapbox/fullscreen-control.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,11 @@
# FullscreenControl

React component that wraps the base library's `FullscreenControl` class ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#fullscreencontrol) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/FullscreenControl/)).


import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs groupId="map-library">
<TabItem value="mapbox" label="Mapbox">
React component that wraps mapbox-gl's [FullscreenControl](https://docs.mapbox.com/mapbox-gl-js/api/markers/#fullscreencontrol) class.

```tsx
import * as React from 'react';
import Map, {FullscreenControl} from 'react-map-gl';
import Map, {FullscreenControl} from 'react-map-gl/mapbox';
import 'mapbox-gl/dist/mapbox-gl.css';

function App() {
return <Map
Expand All @@ -28,29 +22,6 @@ function App() {
}
```

</TabItem>
<TabItem value="maplibre" label="Maplibre">

```tsx
import * as React from 'react';
import Map, {FullscreenControl} from 'react-map-gl/maplibre';

function App() {
return <Map
initialViewState={{
longitude: -100,
latitude: 40,
zoom: 3.5
}}
mapStyle="https://api.maptiler.com/maps/streets/style.json?key=get_your_own_key"
>
<FullscreenControl />
</Map>;
}
```

</TabItem>
</Tabs>

## Properties

Expand Down
83 changes: 11 additions & 72 deletions docs/api-reference/geolocate-control.md → ...api-reference/mapbox/geolocate-control.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,11 @@
# GeolocateControl

React component that wraps the base library's `GeolocateControl` class ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#geolocatecontrol) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/GeolocateControl/)).


import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs groupId="map-library">
<TabItem value="mapbox" label="Mapbox">
React component that wraps mapbox-gl's [GeolocateControl](https://docs.mapbox.com/mapbox-gl-js/api/markers/#geolocatecontrol) class.

```tsx
import * as React from 'react';
import Map, {GeolocateControl} from 'react-map-gl';
import Map, {GeolocateControl} from 'react-map-gl/mapbox';
import 'mapbox-gl/dist/mapbox-gl.css';

function App() {
return <Map
Expand All @@ -28,58 +22,33 @@ function App() {
}
```

</TabItem>
<TabItem value="maplibre" label="Maplibre">

```tsx
import * as React from 'react';
import Map, {GeolocateControl} from 'react-map-gl/maplibre';

function App() {
return <Map
initialViewState={{
longitude: -100,
latitude: 40,
zoom: 3.5
}}
mapStyle="https://api.maptiler.com/maps/streets/style.json?key=get_your_own_key"
>
<GeolocateControl />
</Map>;
}
```

</TabItem>
</Tabs>


## Properties

### Reactive Properties

#### `style`: CSSProperties {#style}
#### `style`: CSSProperties {#style}

CSS style override that applies to the control's container.

### Callbacks

#### `onGeolocate`: (evt: [GeolocateResultEvent](./types.md#geolocateresultevent)) => void {#ongeolocate}
#### `onGeolocate`: (evt: [GeolocateResultEvent](./types.md#geolocateresultevent)) => void {#ongeolocate}

Called on each Geolocation API position update that returned as success.

#### `onError`: (evt: [GeolocateErrorEvent](./types.md#geolocateerrorevent)) => void {#onerror}
#### `onError`: (evt: [GeolocateErrorEvent](./types.md#geolocateerrorevent)) => void {#onerror}

Called on each Geolocation API position update that returned as an error.

#### `onOutOfMaxBounds`: (evt: [GeolocateResultEvent](./types.md#geolocateresultevent)) => void {#onoutofmaxbounds}
#### `onOutOfMaxBounds`: (evt: [GeolocateResultEvent](./types.md#geolocateresultevent)) => void {#onoutofmaxbounds}

Called on each Geolocation API position update that returned as success but user position is out of map `maxBounds`.

#### `onTrackUserLocationStart`: (evt: [GeolocateEvent](./types.md#geolocateevent)) => void {#ontrackuserlocationstart}
#### `onTrackUserLocationStart`: (evt: [GeolocateEvent](./types.md#geolocateevent)) => void {#ontrackuserlocationstart}

Called when the GeolocateControl changes to the active lock state.

#### `onTrackUserLocationEnd`: (evt: [GeolocateEvent](./types.md#geolocateevent)) => void {#ontrackuserlocationend}
#### `onTrackUserLocationEnd`: (evt: [GeolocateEvent](./types.md#geolocateevent)) => void {#ontrackuserlocationend}

Called when the GeolocateControl changes to the background state.

Expand All @@ -98,7 +67,7 @@ Any options supported by the `GeolocateControl` class ([Mapbox](https://docs.map

Plus the following:

#### `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position}
#### `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position}

Default: `'bottom-right'`

Expand All @@ -110,13 +79,10 @@ Placement of the control relative to the map.
The underlying native `GeolocateControl` instance is accessible via a [React ref](https://reactjs.org/docs/refs-and-the-dom.html#creating-refs) hook.
You may use it to call any imperative methods:

<Tabs groupId="map-library">
<TabItem value="mapbox" label="Mapbox">

```tsx
import * as React from 'react';
import {useRef, useEffect} from 'react';
import Map, {GeolocateControl} from 'react-map-gl';
import Map, {GeolocateControl} from 'react-map-gl/mapbox';
import type mapboxgl from 'mapbox-gl';

function App() {
Expand All @@ -133,33 +99,6 @@ function App() {
}
```

</TabItem>
<TabItem value="maplibre" label="Maplibre">


```tsx
import * as React from 'react';
import {useRef, useEffect} from 'react';
import Map, {GeolocateControl} from 'react-map-gl/maplibre';
import type maplibregl from 'maplibre-gl';

function App() {
const geoControlRef = useRef<maplibregl.GeolocateControl>();

useEffect(() => {
// Activate as soon as the control is loaded
geoControlRef.current?.trigger();
}, [geoControlRef.current]);

return <Map>
<GeolocateControl ref={geoControlRef} />
</Map>;
}
```

</TabItem>
</Tabs>


## Source

Expand Down
Loading
Loading