diff --git a/README.md b/README.md index 12a57739c..06b1b508b 100644 --- a/README.md +++ b/README.md @@ -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 ( @@ -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 ( - These docs are for - - - - Looking for an old version? - - - - - - -

+> 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) @@ -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. diff --git a/docs/api-reference/attribution-control.md b/docs/api-reference/mapbox/attribution-control.md similarity index 54% rename from docs/api-reference/attribution-control.md rename to docs/api-reference/mapbox/attribution-control.md index 78789367d..532aea996 100644 --- a/docs/api-reference/attribution-control.md +++ b/docs/api-reference/mapbox/attribution-control.md @@ -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'; - - - +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 - - -```tsx -import * as React from 'react'; -import Map, {AttributionControl} from 'react-map-gl/maplibre'; - -function App() { - return - - ; -} -``` - - - - ## Properties ### Reactive Properties -#### `style`: CSSProperties {#style} +#### `style`: CSSProperties {#style} CSS style override that applies to the control's container. @@ -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'` diff --git a/docs/api-reference/fullscreen-control.md b/docs/api-reference/mapbox/fullscreen-control.md similarity index 52% rename from docs/api-reference/fullscreen-control.md rename to docs/api-reference/mapbox/fullscreen-control.md index ae3257115..e2fcf6cc2 100644 --- a/docs/api-reference/fullscreen-control.md +++ b/docs/api-reference/mapbox/fullscreen-control.md @@ -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'; - - - +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 - - -```tsx -import * as React from 'react'; -import Map, {FullscreenControl} from 'react-map-gl/maplibre'; - -function App() { - return - - ; -} -``` - - - ## Properties diff --git a/docs/api-reference/geolocate-control.md b/docs/api-reference/mapbox/geolocate-control.md similarity index 62% rename from docs/api-reference/geolocate-control.md rename to docs/api-reference/mapbox/geolocate-control.md index e605d68e0..63622bc18 100644 --- a/docs/api-reference/geolocate-control.md +++ b/docs/api-reference/mapbox/geolocate-control.md @@ -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'; - - - +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 - - -```tsx -import * as React from 'react'; -import Map, {GeolocateControl} from 'react-map-gl/maplibre'; - -function App() { - return - - ; -} -``` - - - - - ## 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. @@ -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'` @@ -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: - - - ```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() { @@ -133,33 +99,6 @@ function App() { } ``` - - - - -```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(); - - useEffect(() => { - // Activate as soon as the control is loaded - geoControlRef.current?.trigger(); - }, [geoControlRef.current]); - - return - - ; -} -``` - - - - ## Source diff --git a/docs/api-reference/layer.md b/docs/api-reference/mapbox/layer.md similarity index 70% rename from docs/api-reference/layer.md rename to docs/api-reference/mapbox/layer.md index 70dccf1bd..525dcff55 100644 --- a/docs/api-reference/layer.md +++ b/docs/api-reference/mapbox/layer.md @@ -2,16 +2,11 @@ This component allows apps to create a [map layer](https://docs.mapbox.com/mapbox-gl-js/style-spec/#layers) using React. -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - - - - ```tsx import * as React from 'react'; -import Map, {Layer} from 'react-map-gl'; -import type {FillLayer} from 'react-map-gl'; +import Map, {Layer} from 'react-map-gl/mapbox'; +import type {FillLayer} from 'react-map-gl/mapbox'; +import 'mapbox-gl/dist/mapbox-gl.css'; const parkLayer: FillLayer = { id: 'landuse_park', @@ -39,42 +34,6 @@ function App() { } ``` - - - - -```tsx -import * as React from 'react'; -import Map, {Layer} from 'react-map-gl/maplibre'; -import type {FillLayer} from 'react-map-gl/maplibre'; - -const parkLayer: FillLayer = { - id: 'landuse_park', - type: 'fill', - source: 'mapbox', - 'source-layer': 'landuse', - filter: ['==', 'class', 'park'], - paint: { - 'fill-color': '#4E3FC8' - } -}; - -function App() { - return - - ; -} -``` - - - ## Properties diff --git a/docs/api-reference/map-provider.md b/docs/api-reference/mapbox/map-provider.md similarity index 92% rename from docs/api-reference/map-provider.md rename to docs/api-reference/mapbox/map-provider.md index 4888a51bf..92a068986 100644 --- a/docs/api-reference/map-provider.md +++ b/docs/api-reference/mapbox/map-provider.md @@ -5,7 +5,7 @@ A [Context.Provider](https://reactjs.org/docs/context.html#contextprovider) that The component should wrap all nodes in which you may want to access the maps: ```tsx -import {MapProvider} from 'react-map-gl'; +import {MapProvider} from 'react-map-gl/mapbox'; function Root() { return ( diff --git a/docs/api-reference/map.md b/docs/api-reference/mapbox/map.md similarity index 91% rename from docs/api-reference/map.md rename to docs/api-reference/mapbox/map.md index 76582d959..a174a7a68 100644 --- a/docs/api-reference/map.md +++ b/docs/api-reference/mapbox/map.md @@ -1,16 +1,11 @@ # default (Map) -React component that wraps the base library's `Map` class ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/)). This is also the default export from react-map-gl. - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - - - +React component that wraps mapbox-gl's [Map](https://docs.mapbox.com/mapbox-gl-js/api/map/) class. This is also the default export from react-map-gl. ```tsx title="app.tsx" 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 ( @@ -28,30 +23,6 @@ function App() { } ``` - - - -```tsx title="app.tsx" -import * as React from 'react'; -import Map from 'react-map-gl/maplibre'; - -function App() { - return ( - - ); -} -``` - - - ## Properties @@ -123,7 +94,7 @@ If `undefined` is provided, removes terrain from the map. #### `initialViewState`: object {#initialviewstate} -The initial view state of the map. If specified, `longitude`, `latitude`, `zoom` etc. in props are ignored when constructing the map. Only specify `initialViewState` if `Map` is being used as an **uncontrolled component**. See [state management](../get-started/state-management.md) for examples. +The initial view state of the map. If specified, `longitude`, `latitude`, `zoom` etc. in props are ignored when constructing the map. Only specify `initialViewState` if `Map` is being used as an **uncontrolled component**. See [state management](../../get-started/state-management.md) for examples. - `bounds`: [LngLatBoundsLike](./types.md#lnglatboundslike) - The initial bounds of the map. If specified, it overrides the `longitude`, `latitude` and `zoom` options. Default `null`. - `fitBoundsOptions` - An object to use only when setting the `bounds` option. Default `null`. @@ -377,7 +348,7 @@ Called just before the map begins a transition from one view to another. Called repeatedly during an animated transition from one view to another. When `Map` is used as a controlled component, `event.viewState` reflects the view state that the camera "proposes" to move to, as a result of either user interaction or methods such as [flyTo](https://docs.mapbox.com/mapbox-gl-js/api/map/#map#flyto). The camera does not actually change until the application updates the view state props (`longitude`, `latitude`, `zoom` etc.). -See [state management](../get-started/state-management.md) for examples. +See [state management](../../get-started/state-management.md) for examples. #### `onMoveEnd`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onmoveend} @@ -480,7 +451,7 @@ By module import (and embedding in the final bundle): ```tsx import * as React from 'react'; -import Map from 'react-map-gl'; +import Map from 'react-map-gl/mapbox'; import mapboxgl from 'mapbox-gl'; function App() { @@ -492,7 +463,7 @@ By dynamic import (thus enable bundle splitting): ```tsx import * as React from 'react'; -import Map from 'react-map-gl'; +import Map from 'react-map-gl/mapbox'; function App() { return ; @@ -507,7 +478,7 @@ Or to load a pre-bundled version of the library: ```tsx title="app.tsx" import * as React from 'react'; -import Map from 'react-map-gl'; +import Map from 'react-map-gl/mapbox'; function App() { return ; @@ -516,7 +487,7 @@ function App() { #### `mapboxAccessToken`: string {#mapboxaccesstoken} -Token used to access the Mapbox data service. See [about map tokens](../get-started/mapbox-tokens.md). +Token used to access the Mapbox data service. See [about map tokens](../../get-started/mapbox-tokens.md). #### `baseApiUrl`: string {#baseapiurl} @@ -567,14 +538,11 @@ Provides an interface for loading mapbox-gl's WebWorker bundle from a self-hoste Imperative methods are accessible via a [React ref](https://reactjs.org/docs/refs-and-the-dom.html#creating-refs) or the [useMap](./use-map.md) hook. - - - ```tsx import * as React from 'react'; import {useRef, useCallback} from 'react'; -import Map from 'react-map-gl'; -import type {MapRef} from 'react-map-gl'; +import Map from 'react-map-gl/mapbox'; +import type {MapRef} from 'react-map-gl/mapbox'; function App() { const mapRef = useRef(null); @@ -589,30 +557,6 @@ function App() { } ``` - - - -```tsx -import * as React from 'react'; -import {useRef, useCallback} from 'react'; -import Map from 'react-map-gl/maplibre'; -import type {MapRef} from 'react-map-gl/maplibre'; - -function App() { - const mapRef = useRef(); - - const onMapLoad = useCallback(() => { - mapRef.current.on('move', () => { - // do something - }); - }, []); - - return ; -} -``` - - - The [MapRef](./types.md#mapref) object exposes Map methods ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-instance-members) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#methods)) that **are safe to call without breaking the React bindings**. For example, `setStyle()` is hidden from the ref object, because the style is supposed to be changed by updating the `mapStyle` prop. Calling the method directly may cause the the React prop to mismatch with the underlying state, and lead to unexpected behaviors. diff --git a/docs/api-reference/marker.md b/docs/api-reference/mapbox/marker.md similarity index 68% rename from docs/api-reference/marker.md rename to docs/api-reference/mapbox/marker.md index 8d59ac79b..dd05aba20 100644 --- a/docs/api-reference/marker.md +++ b/docs/api-reference/mapbox/marker.md @@ -1,17 +1,12 @@ # Marker -React component that wraps the base library's `Marker` class ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#marker) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/Marker/)). +React component that wraps mapbox-gl's [Marker](https://docs.mapbox.com/mapbox-gl-js/api/markers/#marker) class. -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - - - - ```tsx import * as React from 'react'; -import Map, {Marker} from 'react-map-gl'; +import Map, {Marker} from 'react-map-gl/mapbox'; +import 'mapbox-gl/dist/mapbox-gl.css'; function App() { return - - - -```tsx -import * as React from 'react'; -import Map, {Marker} from 'react-map-gl/maplibre'; - -function App() { - return - - - - ; -} -``` - - - If `Marker` is mounted with child components, then its content will be rendered to the specified location. If it is mounted with no content, then a default marker will be used. @@ -149,13 +118,11 @@ Any options supported by the `Marker` class ([Mapbox](https://docs.mapbox.com/ma The underlying native `Marker` 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: - - ```tsx import * as React from 'react'; import {useRef, useMemo, useCallback} from 'react'; -import Map, {Marker} from 'react-map-gl'; +import Map, {Marker} from 'react-map-gl/mapbox'; import mapboxgl from 'mapbox-gl'; function App() { @@ -178,38 +145,6 @@ function App() { } ``` - - - - -```tsx -import * as React from 'react'; -import {useRef, useMemo, useCallback} from 'react'; -import Map, {Marker} from 'react-map-gl/maplibre'; -import maplibregl from 'maplibre-gl'; - -function App() { - const markerRef = useRef(); - - const popup = useMemo(() => { - return new maplibregl.Popup().setText('Hello world!'); - }, []) - - const togglePopup = useCallback(() => { - markerRef.current?.togglePopup(); - }, []); - - return <> - - - - - ; -} -``` - - - ## Source diff --git a/docs/api-reference/navigation-control.md b/docs/api-reference/mapbox/navigation-control.md similarity index 55% rename from docs/api-reference/navigation-control.md rename to docs/api-reference/mapbox/navigation-control.md index 630e83660..639243a3b 100644 --- a/docs/api-reference/navigation-control.md +++ b/docs/api-reference/mapbox/navigation-control.md @@ -1,17 +1,11 @@ # NavigationControl -React component that wraps the base library's `NavigationControl` class ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#navigationcontrol) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/NavigationControl/)). - - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - - - +React component that wraps mapbox-gl's [NavigationControl](https://docs.mapbox.com/mapbox-gl-js/api/markers/#navigationcontrol) class. ```tsx import * as React from 'react'; -import Map, {NavigationControl} from 'react-map-gl'; +import Map, {NavigationControl} from 'react-map-gl/mapbox'; +import 'mapbox-gl/dist/mapbox-gl.css'; function App() { return - - - -```tsx -import * as React from 'react'; -import Map, {NavigationControl} from 'react-map-gl/maplibre'; - -function App() { - return - - ; -} -``` - - - - ## Properties ### Reactive Properties -#### `style`: CSSProperties {#style} +#### `style`: CSSProperties {#style} CSS style override that applies to the control's container. @@ -74,7 +43,7 @@ Any options supported by the `NavigationControl` class ([Mapbox](https://docs.ma Plus the following: -#### `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position} +#### `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position} Default: `'top-right'` diff --git a/docs/api-reference/popup.md b/docs/api-reference/mapbox/popup.md similarity index 62% rename from docs/api-reference/popup.md rename to docs/api-reference/mapbox/popup.md index a9e084112..035ab4957 100644 --- a/docs/api-reference/popup.md +++ b/docs/api-reference/mapbox/popup.md @@ -1,18 +1,13 @@ # Popup -React component that wraps the base library's `Popup` class ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#popup) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/Popup/)). +React component that wraps mapbox-gl's [Popup](https://docs.mapbox.com/mapbox-gl-js/api/markers/#popup) class. -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - - - - ```tsx import * as React from 'react'; import {useState} from 'react'; -import Map, {Popup} from 'react-map-gl'; +import Map, {Popup} from 'react-map-gl/mapbox'; +import 'mapbox-gl/dist/mapbox-gl.css'; function App() { const [showPopup, setShowPopup] = useState(true); @@ -36,54 +31,21 @@ function App() { } ``` - - - - -```tsx -import * as React from 'react'; -import {useState} from 'react'; -import Map, {Popup} from 'react-map-gl/maplibre'; - -function App() { - const [showPopup, setShowPopup] = useState(true); - - return - {showPopup && ( - setShowPopup(false)}> - You are here - )} - ; -} -``` - - - - ## Properties ### Reactive Properties -#### `anchor`: 'center' | 'left' | 'right' | 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | undefined {#anchor} +#### `anchor`: 'center' | 'left' | 'right' | 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | undefined {#anchor} A string indicating the part of the popup that should be positioned closest to the coordinate, set via `longitude` and `latitude`. If unset, the anchor will be dynamically set to ensure the popup falls within the map container with a preference for `'bottom'`. -#### `className`: string {#classname} +#### `className`: string {#classname} Space-separated CSS class names to add to popup container. -#### `offset`: number | [PointLike](./types.md#pointlike) | Record\ {#offset} +#### `offset`: number | [PointLike](./types.md#pointlike) | Record\ {#offset} Default: `null` @@ -95,23 +57,23 @@ A pixel offset applied to the popup's location specified as: Negative offsets indicate left and up. -#### `maxWidth`: string {#maxwidth} +#### `maxWidth`: string {#maxwidth} Default: `240px` A string that sets the CSS property of the popup's maximum width. -#### `style`: CSSProperties {#style} +#### `style`: CSSProperties {#style} CSS style override that applies to the popup's container. ### Callbacks -#### `onOpen`: (evt: [PopupEvent](./types.md#popupevent)) => void {#onopen} +#### `onOpen`: (evt: [PopupEvent](./types.md#popupevent)) => void {#onopen} Called when the popup is opened. -#### `onClose`: (evt: [PopupEvent](./types.md#popupevent)) => void {#onclose} +#### `onClose`: (evt: [PopupEvent](./types.md#popupevent)) => void {#onclose} Called when the popup is closed by the user clicking on the close button or outside (if `closeOnClick: true`). @@ -133,13 +95,10 @@ Any options supported by the `Popup` class ([Mapbox](https://docs.mapbox.com/map The underlying native `Popup` 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: - - - ```tsx import * as React from 'react'; import {useRef, useEffect} from 'react'; -import Map, {Popup} from 'react-map-gl'; +import Map, {Popup} from 'react-map-gl/mapbox'; import mapboxgl from 'mapbox-gl'; function App() { @@ -157,35 +116,6 @@ function App() { } ``` - - - - -```tsx -import * as React from 'react'; -import {useRef, useEffect} from 'react'; -import Map, {Popup} from 'react-map-gl/maplibre'; -import maplibregl from 'maplibre-gl'; - -function App() { - const popupRef = useRef(); - - useEffect(() => { - popupRef.current?.trackPointer(); - }, [popupRef.current]) - - return - - Tooltip - - ; -} -``` - - - - - ## Source [popup.ts](https://github.com/visgl/react-map-gl/tree/7.0-release/src/components/popup.ts) diff --git a/docs/api-reference/scale-control.md b/docs/api-reference/mapbox/scale-control.md similarity index 53% rename from docs/api-reference/scale-control.md rename to docs/api-reference/mapbox/scale-control.md index 590d2bef2..6c470b76f 100644 --- a/docs/api-reference/scale-control.md +++ b/docs/api-reference/mapbox/scale-control.md @@ -1,17 +1,11 @@ # ScaleControl -React component that wraps the base library's `ScaleControl` class ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#scalecontrol) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/ScaleControl/)). - - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - - - +React component that wraps mapbox-gl's [ScaleControl](https://docs.mapbox.com/mapbox-gl-js/api/markers/#scalecontrol) class. ```tsx import * as React from 'react'; -import Map, {ScaleControl} from 'react-map-gl'; +import Map, {ScaleControl} from 'react-map-gl/mapbox'; +import 'mapbox-gl/dist/mapbox-gl.css'; function App() { return - - - -```tsx -import * as React from 'react'; -import Map, {ScaleControl} from 'react-map-gl/maplibre'; - -function App() { - return - - ; -} -``` - - - - - ## Properties ### Reactive Properties -#### `maxWidth`: string {#maxwidth} +#### `maxWidth`: string {#maxwidth} Default: `100` The maximum length of the scale control in pixels. -#### `style`: CSSProperties {#style} +#### `style`: CSSProperties {#style} CSS style override that applies to the control's container. -#### `unit`: 'imperial' | 'metric' | 'nautical' {#unit} +#### `unit`: 'imperial' | 'metric' | 'nautical' {#unit} Default: `'metric'` @@ -80,7 +48,7 @@ Unit of the distance. The properties in this section are not reactive. They are only used when the component first mounts. -#### `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position} +#### `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position} Default: `'top-right'` diff --git a/docs/api-reference/source.md b/docs/api-reference/mapbox/source.md similarity index 58% rename from docs/api-reference/source.md rename to docs/api-reference/mapbox/source.md index 910549b39..6d376e2cc 100644 --- a/docs/api-reference/source.md +++ b/docs/api-reference/mapbox/source.md @@ -3,17 +3,12 @@ This component allows apps to create a [map source](https://docs.mapbox.com/mapbox-gl-js/style-spec/#sources) using React. It may contain [Layer](./layer.md) components as children. -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - - - - ```tsx import * as React from 'react'; -import Map, {Source, Layer} from 'react-map-gl'; -import type {CircleLayer} from 'react-map-gl'; +import Map, {Source, Layer} from 'react-map-gl/mapbox'; +import type {CircleLayer} from 'react-map-gl/mapbox'; import type {FeatureCollection} from 'geojson'; +import 'mapbox-gl/dist/mapbox-gl.css'; const geojson: FeatureCollection = { type: 'FeatureCollection', @@ -48,51 +43,6 @@ function App() { } ``` - - - - -```tsx -import * as React from 'react'; -import Map, {Source, Layer} from 'react-map-gl/maplibre'; -import type {CircleLayer} from 'react-map-gl/maplibre'; -import type {FeatureCollection} from 'geojson'; - -const geojson: FeatureCollection = { - type: 'FeatureCollection', - features: [ - {type: 'Feature', geometry: {type: 'Point', coordinates: [-122.4, 37.8]}} - ] -}; - -const layerStyle: CircleLayer = { - id: 'point', - type: 'circle', - paint: { - 'circle-radius': 10, - 'circle-color': '#007cbf' - } -}; - -function App() { - return - - - - ; -} -``` - - - - ## Properties @@ -102,11 +52,11 @@ When props change _shallowly_, the component will attempt to update the source. Once a `` is mounted, the following props should not change. If add/remove multiple JSX sources dynamically, make sure you use React's [key prop](https://reactjs.org/docs/lists-and-keys.html#keys) to give each element a stable identity. -#### `id`: string {#id} +#### `id`: string {#id} Unique identifier of the source. If not provided, a default id will be assigned. -#### `type`: string {#type} +#### `type`: string {#type} Required. Type of the source. diff --git a/docs/api-reference/types.md b/docs/api-reference/mapbox/types.md similarity index 55% rename from docs/api-reference/types.md rename to docs/api-reference/mapbox/types.md index 9965e8616..47d0b9634 100644 --- a/docs/api-reference/types.md +++ b/docs/api-reference/mapbox/types.md @@ -1,6 +1,6 @@ # Types -The following types can be imported from `react-map-gl` when using TypeScript. +The following types can be imported from `react-map-gl/mapbox` when using TypeScript. ## Components @@ -19,91 +19,91 @@ Instance [ref](https://reactjs.org/docs/refs-and-the-dom.html#creating-refs) of ## Styling -#### MapStyle +#### StyleSpecification An object conforming to the [Mapbox Style Specification](https://mapbox.com/mapbox-gl-style-spec/). -#### Fog +#### FogSpecification An object conforming to the [Fog Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/fog/). -#### Light +#### LightSpecification An object conforming to the [Light Style Specification](https://www.mapbox.com/mapbox-gl-style-spec/#light). -#### Terrain +#### TerrainSpecification An object conforming to the [Terrain Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/terrain/). -#### Projection +#### ProjectionSpecification An object conforming to the [Projection Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/projection/). -#### BackgroundLayer +#### BackgroundLayerSpecification A JSON object that defines a `background` layer according to the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#background). -#### CircleLayer +#### CircleLayerSpecification A JSON object that defines a `circle` layer according to the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#circle). -#### FillExtrusionLayer +#### FillExtrusionLayerSpecification A JSON object that defines a `fill-extrusion` layer according to the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#fill-extrusion). -#### FillLayer +#### FillLayerSpecification A JSON object that defines a `fill` layer according to the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#fill). -#### HeatmapLayer +#### HeatmapLayerSpecification A JSON object that defines a `heatmap` layer according to the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#heatmap). -#### HillshadeLayer +#### HillshadeLayerSpecification A JSON object that defines a `hillshade` layer according to the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#hillshade). -#### LineLayer +#### LineLayerSpecification A JSON object that defines a `line` layer according to the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#line). -#### RasterLayer +#### RasterLayerSpecification A JSON object that defines a `raster` layer according to the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#raster). -#### SymbolLayer +#### SymbolLayerSpecification A JSON object that defines a `symbol` layer according to the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#symbol). -#### SkyLayer +#### SkyLayerSpecification A JSON object that defines a `sky` layer according to the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#sky). -#### GeoJSONSourceRaw +#### GeoJSONSourceSpecification A JSON object that defines a `geojson` source according to the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/sources/#geojson). -#### VideoSourceRaw +#### VideoSourceSpecification A JSON object that defines a `video` source according to the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/sources/#video). -#### ImageSourceRaw +#### ImageSourceSpecification A JSON object that defines a `image` source according to the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/sources/#image). -#### VectorSourceRaw +#### VectorSourceSpecification A JSON object that defines a `vector` source according to the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/sources/#vector). -#### RasterSource +#### RasterSourceSpecification A JSON object that defines a `raster` source according to the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/sources/#raster). -#### RasterDemSource +#### RasterDEMSourceSpecification A JSON object that defines a `raster-dem` source according to the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/sources/#raster-dem). -#### CanvasSourceRaw +#### CanvasSourceSpecification A JSON object that defines a `canvas` source type. See [CanvasSourceOptions](https://docs.mapbox.com/mapbox-gl-js/api/sources/#canvassourceoptions). @@ -128,27 +128,27 @@ An object with the following fields: #### LngLat -A `LngLat` object ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/geography/#lnglat) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/LngLat/)). +A Mapbox [LngLat](https://docs.mapbox.com/mapbox-gl-js/api/geography/#lnglat) object. #### LngLatLike -A [`LngLat`](#lnglat) object, an array of two numbers representing longitude and latitude, or an object with `lng` and `lat` or `lon` and `lat` properties. ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/geography/#lnglatlike) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/LngLatLike/)) +A Mapbox [LngLatLike](https://docs.mapbox.com/mapbox-gl-js/api/geography/#lnglatlike) object. #### LngLatBounds -A `LngLatBounds` object ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/geography/#lnglatbounds) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/LngLatBounds/)). +A Mapbox [LngLatBounds](https://docs.mapbox.com/mapbox-gl-js/api/geography/#lnglatbounds) object. #### LngLatBoundsLike -A [`LngLatBounds`](#lnglatbounds) object, an array of [`LngLatLike`](#lnglatlike) objects in [sw, ne] order, or an array of numbers in [west, south, east, north] order. ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/geography/#lnglatboundslike) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/LngLatBoundsLike/)) +A Mapbox [LngLatBoundsLike](https://docs.mapbox.com/mapbox-gl-js/api/geography/#lnglatboundslike) object. #### Point -A `Point` object. ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/geography/#point) | [Maplibre](https://github.com/mapbox/point-geometry)) +A Mapbox [Point](https://docs.mapbox.com/mapbox-gl-js/api/geography/#point) object. #### PointLike -A [Point](#point) or an array of two numbers representing x and y screen coordinates in pixels ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/geography/#pointlike) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/PointLike/)). +A Mapbox [PointLike](https://docs.mapbox.com/mapbox-gl-js/api/geography/#pointlike) object. #### MapGeoJSONFeature @@ -157,7 +157,7 @@ A [GeoJSON](http://geojson.org/) feature that also contains the following librar - `layer`: Layer - `source`: string - `sourceLayer`: string -- `state`: { [key: string]: any } +- `state`: `{ [key: string]: any }` #### ViewState @@ -169,29 +169,6 @@ An object with the following fields: - `pitch`: number - The pitch (tilt) of the map, in degrees. - `bearing`: number - The bearing (rotation) of the map, in degrees. -## Sources - -The following are implementations of source types that could be retrieved with `Map.getSource` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/#map#getsource) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#getsource)). - -#### GeoJSONSource - -A source containing GeoJSON. See `GeoJSONSource` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/sources/#geojsonsource) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/GeoJSONSource/)). - -#### VideoSource - -A source containing video. See `VideoSource` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/sources/#videosource) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/VideoSource/)). - -#### ImageSource - -A source containing image. See `ImageSource` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/sources/#imagesource) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/ImageSource/)). - -#### CanvasSource - -A source containing the contents of an HTML canvas. See `CanvasSource`([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/sources/#canvassource) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/CanvasSource/)). - -#### VectorTileSource - -A source containing vector tiles in [Mapbox Vector Tile format](https://docs.mapbox.com/vector-tiles/reference/). See `VectorTileSource` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/sources/#vectortilesource) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/VectorTileSource/)). ## Events @@ -200,7 +177,7 @@ A source containing vector tiles in [Mapbox Vector Tile format](https://docs.map An object with the following fields: - `type`: string - Event type -- `target`: `Map` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/)) +- `target`: [Map](https://docs.mapbox.com/mapbox-gl-js/api/map/) - `originalEvent?`: [Event](https://developer.mozilla.org/en-US/docs/Web/API/Event) #### MapLayerMouseEvent @@ -208,7 +185,7 @@ An object with the following fields: An object with the following fields: - `type`: string -- `target`: `Map` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/)) +- `target`: [Map](https://docs.mapbox.com/mapbox-gl-js/api/map/) - `originalEvent?`: [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent) - `point`: [Point](#point) - `lngLat`: [LngLat](#lnglat) @@ -221,7 +198,7 @@ An object with the following fields: An object with the following fields: - `type`: string -- `target`: `Map` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/)) +- `target`: [Map](https://docs.mapbox.com/mapbox-gl-js/api/map/) - `originalEvent?`: [WheelEvent](https://developer.mozilla.org/en-US/docs/Web/API/WheelEvent) - `preventDefault`: () => void - `defaultPrevented`: boolean @@ -231,7 +208,7 @@ An object with the following fields: An object with the following fields: - `type`: string -- `target`: `Map` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/)) +- `target`: [Map](https://docs.mapbox.com/mapbox-gl-js/api/map/) - `originalEvent?`: [TouchEvent](https://developer.mozilla.org/en-US/docs/Web/API/TouchEvent) - `point`: [Point](#point) - `lngLat`: [LngLat](#lnglat) @@ -246,7 +223,7 @@ An object with the following fields: An object with the following fields: - `type`: string - Event type -- `target`: `Map` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/)) +- `target`: [Map](https://docs.mapbox.com/mapbox-gl-js/api/map/) - `viewState`: [ViewState](#viewstate) - the next view state that the camera wants to change to based on user input or transition. #### MapBoxZoomEvent @@ -254,7 +231,7 @@ An object with the following fields: An object with the following fields: - `type`: string -- `target`: `Map` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/)) +- `target`: [Map](https://docs.mapbox.com/mapbox-gl-js/api/map/) - `originalEvent?`: [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent) - `boxZoomBounds`: [LngLatBounds](#lnglatbounds) @@ -263,7 +240,7 @@ An object with the following fields: An object with the following fields: - `type`: string -- `target`: `Map` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/)) +- `target`: [Map](https://docs.mapbox.com/mapbox-gl-js/api/map/) - `dataType`: 'style' #### MapSourceDataEvent @@ -271,7 +248,7 @@ An object with the following fields: An object with the following fields: - `type`: string -- `target`: `Map` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/)) +- `target`: [Map](https://docs.mapbox.com/mapbox-gl-js/api/map/) - `dataType`: 'source' - `isSourceLoaded`: boolean - `source`: string @@ -287,7 +264,7 @@ See [MapDataEvent](https://docs.mapbox.com/mapbox-gl-js/api/events/#mapdataevent An object with the following fields: - `type`: 'error' -- `target`: `Map` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/)) +- `target`: [Map](https://docs.mapbox.com/mapbox-gl-js/api/map/) - `error`: [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) #### GeolocateEvent @@ -295,15 +272,15 @@ An object with the following fields: An object with the following fields: - `type`: string -- `target`: `Map` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/)) -- `target`: `GeolocateControl` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#geolocatecontrol) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/GeolocateControl/)) +- `target`: [Map](https://docs.mapbox.com/mapbox-gl-js/api/map/) +- `target`: [GeolocateControl](https://docs.mapbox.com/mapbox-gl-js/api/markers/#geolocatecontrol) #### GeolocateResultEvent An object with the following fields: - `type`: string -- `target`: `GeolocateControl` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#geolocatecontrol) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/GeolocateControl/)) +- `target`: [GeolocateControl](https://docs.mapbox.com/mapbox-gl-js/api/markers/#geolocatecontrol) - `coords`: [GeolocationCoordinates](https://developer.mozilla.org/en-US/docs/Web/API/GeolocationCoordinates) - the current location. - `timestamp`: number - the time at which the location was retrieved. @@ -312,7 +289,7 @@ An object with the following fields: An object with the following fields: - `type`: string -- `target`: `GeolocateControl` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#geolocatecontrol) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/GeolocateControl/)) +- `target`: [GeolocateControl](https://docs.mapbox.com/mapbox-gl-js/api/markers/#geolocatecontrol) - `code`: PERMISSION_DENIED | POSITION_UNAVAILABLE | TIMEOUT - see [GeolocationPositionError](https://developer.mozilla.org/en-US/docs/Web/API/GeolocationPositionError) - `message`: string - the details of the error. Specifications note that this is primarily intended for debugging use and not to be shown directly in a user interface. @@ -321,14 +298,14 @@ An object with the following fields: An object with the following fields: - `type`: string -- `target`: `Marker` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#marker) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/Marker/)) +- `target`: [Marker](https://docs.mapbox.com/mapbox-gl-js/api/markers/#marker) #### MarkerDragEvent An object with the following fields: - `type`: string -- `target`: `Marker` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#marker) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/Marker/)) +- `target`: [Marker](https://docs.mapbox.com/mapbox-gl-js/api/markers/#marker) - `lngLat`: [LngLat](#lnglat) - the new location of the marker #### PopupEvent @@ -336,4 +313,4 @@ An object with the following fields: An object with the following fields: - `type`: string -- `target`: `Popup` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#popup) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/Popup/)) +- `target`: [Popup](https://docs.mapbox.com/mapbox-gl-js/api/markers/#popup) diff --git a/docs/api-reference/use-control.md b/docs/api-reference/mapbox/use-control.md similarity index 79% rename from docs/api-reference/use-control.md rename to docs/api-reference/mapbox/use-control.md index 9426eef8f..450b7dd0b 100644 --- a/docs/api-reference/use-control.md +++ b/docs/api-reference/mapbox/use-control.md @@ -4,7 +4,7 @@ The `useControl` hook is used to create React wrappers for custom map controls. ```tsx import MapboxDraw from '@mapbox/mapbox-gl-draw'; -import Map, {useControl} from 'react-map-gl'; +import Map, {useControl} from 'react-map-gl/mapbox'; function DrawControl(props: DrawControlProps) { useControl(() => new MapboxDraw(props), { @@ -38,7 +38,7 @@ function App() { } ``` -See a full example [here](/examples/draw-polygon). +See a full example [here](/examples/mapbox/draw-polygon). ## Signature @@ -72,9 +72,9 @@ The hook creates an [IControl](https://docs.mapbox.com/mapbox-gl-js/api/markers/ Parameters: -- `onCreate`: ({map: MapRef, mapLib: mapboxgl}) => [IControl](./types.md#icontrol) - called to create an instance of the control. -- `onAdd`: ({map: MapRef, mapLib: mapboxgl}) => void - called when the control has been added to the map. -- `onRemove`: ({map: MapRef, mapLib: mapboxgl}) => void - called when the control is about to be removed from the map. +- `onCreate`: (`{map: MapRef, mapLib: mapboxgl}`) => [IControl](./types.md#icontrol) - called to create an instance of the control. +- `onAdd`: (`{map: MapRef, mapLib: mapboxgl}`) => void - called when the control has been added to the map. +- `onRemove`: (`{map: MapRef, mapLib: mapboxgl}`) => void - called when the control is about to be removed from the map. - `options`: object + `position`: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' - control position relative to the map diff --git a/docs/api-reference/use-map.md b/docs/api-reference/mapbox/use-map.md similarity index 59% rename from docs/api-reference/use-map.md rename to docs/api-reference/mapbox/use-map.md index 319deacae..5809e49b0 100644 --- a/docs/api-reference/use-map.md +++ b/docs/api-reference/mapbox/use-map.md @@ -4,14 +4,8 @@ The `useMap` hook allows a component to reference the [Map](./map.md) that conta When used with [MapProvider](./map-provider.md), this hook can also reference maps that are rendered outside of the current map component's direct render tree. -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - - - - ```tsx -import {Map, useMap} from 'react-map-gl'; +import {Map, useMap} from 'react-map-gl/mapbox'; function Root() { return ( @@ -32,44 +26,11 @@ function NavigateButton() { } ``` - - - - -```tsx -import {Map, useMap} from 'react-map-gl/maplibre'; - -function Root() { - return ( - - - - ); -} - -function NavigateButton() { - const {current: map} = useMap(); - - const onClick = () => { - map.flyTo({center: [-122.4, 37.8]}); - }; - - return ; -} -``` - - - - When used with the [MapProvider](./map-provider.md), this hook can also reference maps that are rendered outside of the current component's direct render tree as long as both trees are part of the current ``. - - - - ```tsx -import {MapProvider, Map, useMap} from 'react-map-gl'; +import {MapProvider, Map, useMap} from 'react-map-gl/mapbox'; function Root() { // Note: `useMap` will not work in , only children of can use `useMap` @@ -95,37 +56,6 @@ function NavigateButton() { } ``` - - - - -```tsx -import {MapProvider, Map, useMap} from 'react-map-gl/maplibre'; - -function Root() { - return ( - - - - - - ); -} - -function NavigateButton() { - const {myMapA, myMapB} = useMap(); - - const onClick = () => { - myMapA.flyTo({center: [-122.4, 37.8]}); - myMapB.flyTo({center: [-74, 40.7]}); - }; - - return ; -} -``` - - - See a full example [here](https://github.com/visgl/react-map-gl/tree/7.0-release/examples/get-started/hook). diff --git a/docs/api-reference/maplibre/attribution-control.md b/docs/api-reference/maplibre/attribution-control.md new file mode 100644 index 000000000..c97625d86 --- /dev/null +++ b/docs/api-reference/maplibre/attribution-control.md @@ -0,0 +1,56 @@ +# AttributionControl + +React component that wraps maplibre-gl's [AttributionControl](https://maplibre.org/maplibre-gl-js/docs/API/classes/AttributionControl/) class. + + +```tsx +import * as React from 'react'; +import {Map, AttributionControl} from 'react-map-gl/maplibre'; +import 'maplibre-gl/dist/maplibre-gl.css'; + +function App() { + return + + ; +} +``` + + +## Properties + +### Reactive Properties + +#### `style`: CSSProperties {#style} + +CSS style override that applies to the control's container. + +### Other Properties + +The properties in this section are not reactive. They are only used when the component first mounts. + +Any [options](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/AttributionControlOptions/) supported by the `AttributionControl` class, such as + +- `compact` +- `customAttribution` + +Plus the following: + +#### `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position} + +Default: `'bottom-right'` + +Placement of the control relative to the map. + + +## Source + +[attribution-control.ts](https://github.com/visgl/react-map-gl/tree/master/modules/maplibre/src/components/attribution-control.ts) diff --git a/docs/api-reference/maplibre/fullscreen-control.md b/docs/api-reference/maplibre/fullscreen-control.md new file mode 100644 index 000000000..fe9788585 --- /dev/null +++ b/docs/api-reference/maplibre/fullscreen-control.md @@ -0,0 +1,51 @@ +# FullscreenControl + +React component that wraps maplibre-gl's [FullscreenControl](https://maplibre.org/maplibre-gl-js/docs/API/classes/FullscreenControl/) class. + + +```tsx +import * as React from 'react'; +import {Map, FullscreenControl} from 'react-map-gl/maplibre'; +import 'maplibre-gl/dist/maplibre-gl.css'; + +function App() { + return + + ; +} +``` + +## Properties + +### Reactive Properties + +#### `style`: CSSProperties {#style} + +CSS style override that applies to the control's container. + + +### Other Properties + +The properties in this section are not reactive. They are only used when the component first mounts. + +#### `containerId`: string {#containerid} + +Id of the DOM element which should be made full screen. By default, the map container element will be made full screen. + +#### `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position} + +Default: `'top-right'` + +Placement of the control relative to the map. + + +## Source + +[fullscreen-control.ts](https://github.com/visgl/react-map-gl/tree/master/modules/maplibre/src/components/fullscreen-control.ts) diff --git a/docs/api-reference/maplibre/geolocate-control.md b/docs/api-reference/maplibre/geolocate-control.md new file mode 100644 index 000000000..ca7032b6f --- /dev/null +++ b/docs/api-reference/maplibre/geolocate-control.md @@ -0,0 +1,106 @@ +# GeolocateControl + +React component that wraps maplibre-gl's [GeolocateControl](https://maplibre.org/maplibre-gl-js/docs/API/classes/GeolocateControl/) class. + +```tsx +import * as React from 'react'; +import {Map, GeolocateControl} from 'react-map-gl/maplibre'; +import 'maplibre-gl/dist/maplibre-gl.css'; + +function App() { + return + + ; +} +``` + + +## Properties + +### Reactive Properties + +#### `style`: CSSProperties {#style} + +CSS style override that applies to the control's container. + +### Callbacks + +#### `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} + +Called on each Geolocation API position update that returned as an error. + +#### `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} + +Called when the GeolocateControl changes to the active lock state. + +#### `onTrackUserLocationEnd`: (evt: [GeolocateEvent](./types.md#geolocateevent)) => void {#ontrackuserlocationend} + +Called when the GeolocateControl changes to the background state. + + +### Other Properties + +The properties in this section are not reactive. They are only used when the component first mounts. + +Any [options](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/GeolocateControlOptions/) supported by the `GeolocateControl` class, such as + +- `positionOptions` +- `fitBoundsOptions` +- `trackUserLocation` +- `showAccuracyCircle` +- `showUserLocation` + +Plus the following: + +#### `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position} + +Default: `'bottom-right'` + +Placement of the control relative to the map. + + +## Methods + +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: + + +```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(); + + useEffect(() => { + // Activate as soon as the control is loaded + geoControlRef.current?.trigger(); + }, [geoControlRef.current]); + + return + + ; +} +``` + + +## Source + +[geolocate-control.ts](https://github.com/visgl/react-map-gl/tree/master/modules/maplibre/src/components/geolocate-control.ts) diff --git a/docs/api-reference/maplibre/layer.md b/docs/api-reference/maplibre/layer.md new file mode 100644 index 000000000..c44bdf392 --- /dev/null +++ b/docs/api-reference/maplibre/layer.md @@ -0,0 +1,71 @@ +# Layer + +This component allows apps to create a [map layer](https://maplibre.org/maplibre-style-spec/layers/) using React. + + +```tsx +import * as React from 'react'; +import {Map, Layer} from 'react-map-gl/maplibre'; +import type {FillLayer} from 'react-map-gl/maplibre'; +import 'maplibre-gl/dist/maplibre-gl.css'; + +const parkLayer: FillLayer = { + id: 'landuse_park', + type: 'fill', + source: 'vector', + 'source-layer': 'landuse', + filter: ['==', 'class', 'park'], + paint: { + 'fill-color': '#4E3FC8' + } +}; + +function App() { + return + + ; +} +``` + + +## Properties + +The props provided to this component should be conforming to the [Maplibre layer specification](https://maplibre.org/maplibre-style-spec/layers/). + +When props change *shallowly*, the component will perform style diffing to update the layer. Avoid defining constant objects/arrays inline may help performance. + +### Identity Properties + +Once a `` is mounted, the following props should not change. If you add/remove multiple JSX layers dynamically, make sure you use React's [key prop](https://reactjs.org/docs/lists-and-keys.html#keys) to give each element a stable identity. + +#### `id`: string {#id} + +Unique identifier of the layer. If not provided, a default id will be assigned. + +#### `type`: string {#type} + +Required. Type of the layer. + +### Options + +#### `beforeId`: string {#beforeid} + +The ID of an existing layer to insert this layer before. If this prop is omitted, the layer will be appended to the end of the layers array. This is useful when using dynamic layers with a map style from a URL. + +Note that layers are added by the order that they mount. They are *NOT* reordered later if their relative positions in the JSX tree change. If dynamic reordering is desired, you should manipulate `beforeId` for consistent behavior. + +#### `source`: string {#source} + +`source` is required by some layer types in the Mapbox style specification. If `` is used as the immediate child of a [Source](./source.md) component, this prop will be overwritten by the id of the parent source. If the `` component is not an immediate descendant of ``, e.g wrapped inside a helper component, source property needs to be provided same as the id of the `` component for the `` component to show. + + +## Source + +[layer.ts](https://github.com/visgl/react-map-gl/tree/master/modules/maplibre/src/components/layer.ts) diff --git a/docs/api-reference/maplibre/logo-control.md b/docs/api-reference/maplibre/logo-control.md new file mode 100644 index 000000000..914058016 --- /dev/null +++ b/docs/api-reference/maplibre/logo-control.md @@ -0,0 +1,53 @@ +# LogoControl + +React component that wraps maplibre-gl's [LogoControl](https://maplibre.org/maplibre-gl-js/docs/API/classes/LogoControl/) class. + +```tsx +import * as React from 'react'; +import {Map, LogoControl} from 'react-map-gl/maplibre'; +import 'maplibre-gl/dist/maplibre-gl.css'; + +function App() { + return + + ; +} +``` + + +## Properties + +### Reactive Properties + +#### `style`: CSSProperties {#style} + +CSS style override that applies to the control's container. + + +### Other Properties + +The properties in this section are not reactive. They are only used when the component first mounts. + +Any [options](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/LogoControlOptions/) supported by the `LogoControl` class, such as + +- `compact` + +Plus the following: + +#### `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position} + +Default: `'top-right'` + +Placement of the control relative to the map. + + +## Source + +[logo-control.ts](https://github.com/visgl/react-map-gl/tree/master/modules/maplibre/src/components/logo-control.ts) diff --git a/docs/api-reference/maplibre/map-provider.md b/docs/api-reference/maplibre/map-provider.md new file mode 100644 index 000000000..a7e8f4665 --- /dev/null +++ b/docs/api-reference/maplibre/map-provider.md @@ -0,0 +1,26 @@ +# MapProvider + +A [Context.Provider](https://reactjs.org/docs/context.html#contextprovider) that facilitates map operations outside of the component that directly renders a [Map](./map.md). + +The component should wrap all nodes in which you may want to access the maps: + +```tsx +import {MapProvider} from 'react-map-gl/maplibre'; + +function Root() { + return ( + + { + // Application tree, somewhere one or more component(s) are rendered + } + + ); +} +``` + +See [useMap](./use-map.md) for more information. + + +## Source + +[use-map.tsx](https://github.com/visgl/react-map-gl/tree/master/modules/maplibre/src/components/use-map.tsx) diff --git a/docs/api-reference/maplibre/map.md b/docs/api-reference/maplibre/map.md new file mode 100644 index 000000000..4428bf7ac --- /dev/null +++ b/docs/api-reference/maplibre/map.md @@ -0,0 +1,554 @@ +# default (Map) + +React component that wraps maplibre-gl's [Map](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/) class. This is also the default export from `react-map-gl/maplibre`. + +```tsx +import * as React from 'react'; +import {Map} from 'react-map-gl/maplibre'; +import 'maplibre-gl/dist/maplibre-gl.css'; + +function App() { + return ( + + ); +} +``` + + +## Properties + +Aside from the props listed below, the `Map` component supports all [options](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapOptions/) of the `Map` class constructor. Beware that this is not an exhaustive list of all props. Different base map libraries may offer different options and default values. When in doubt, refer to your base map library's documentation. + +### Layout options + +#### `id`: string {#id} + +Map container id. + +#### `style`: CSSProperties {#style} + +Default: `{position: 'relative', width: '100%', height: '100%'}` + +Map container CSS. + +#### `cursor`: string {#cursor} + +Default: `'auto'` + +The current cursor [type](https://developer.mozilla.org/en-US/docs/Web/CSS/cursor). + +### Styling options + +#### `light`: [Light](./types.md#light) {#light} + +Light properties of the style. Must conform to the [Light Style Specification](https://maplibre.org/maplibre-style-spec/light/). + +#### `mapStyle`: [MapStyle](./types.md#mapstyle) | string | Immutable {#mapstyle} + +Default: (empty style) + +The map's Maplibre style. This must be an a JSON object conforming to the schema described in the [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/), or a URL to such JSON. + +#### `projection`: string | [Projection](./types.md#projection) {#projection} + +Default: `'mercator'` + +The projection the map should be rendered in. See [Projection Specification](https://maplibre.org/maplibre-style-spec/projection/). + +#### `renderWorldCopies`: boolean {#renderworldcopies} + +Default: `true` + +If `true`, multiple copies of the world will be rendered, when zoomed out. + +#### `sky`: [Sky](./types.md#sky) {#sky} + +The sky property of the style. Must conform to the [Sky Style Specification](https://maplibre.org/maplibre-style-spec/sky/). + +#### `styleDiffing`: boolean {#stylediffing} + +Default: `true` + +Enable diffing when `mapStyle` changes. If `false`, force a 'full' update, removing the current style and building the given one instead of attempting a diff-based update. + +#### `terrain`: [Terrain](./types.md#terrain)|null {#terrain} + +Terrain property of the style. Must conform to the [Terrain Style Specification](https://maplibre.org/maplibre-style-spec/terrain/). +If `null` is provided, removes terrain from the map. + + +### Camera options + +#### `initialViewState`: object {#initialviewstate} + +The initial view state of the map. If specified, `longitude`, `latitude`, `zoom` etc. in props are ignored when constructing the map. Only specify `initialViewState` if `Map` is being used as an **uncontrolled component**. See [state management](../../get-started/state-management.md) for examples. + +- `bounds`: [LngLatBoundsLike](./types.md#lnglatboundslike) - The initial bounds of the map. If specified, it overrides the `longitude`, `latitude` and `zoom` options. Default `null`. +- `fitBoundsOptions` - An object to use only when setting the `bounds` option. Default `null`. + + `fitBoundsOptions.offset`: [PointLike](./types.md#pointlike) + + `fitBoundsOptions.minZoom`: number + + `fitBoundsOptions.maxZoom`: number + + `fitBoundsOptions.padding`: [PaddingOptions](./types.md#paddingoptions) +- `longitude`: number - The initial longitude of the map center. Default `0`. +- `latitude`: number - The initial latitude of the map center. Default `0`. +- `zoom`: number - The initial zoom level. Default `0`. +- `pitch`: number - The initial pitch (tilt) of the map. Default `0`. +- `bearing`: number - The initial bearing (rotation) of the map. Default `0`. + +#### `longitude`: number {#longitude} + +The longitude of the map center. + +#### `latitude`: number {#latitude} + +The latitude of the map center. + +#### `zoom`: number {#zoom} + +The [zoom level](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapOptions/#zoom) of the map. + +#### `pitch`: number {#pitch} + +The initial [pitch](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapOptions/#pitch) (tilt) of the map, measured in degrees away from the plane of the screen (0-85). + +#### `bearing`: number {#bearing} + +The initial [bearing](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapOptions/#bearing) (rotation) of the map, measured in degrees counter-clockwise from north. + +#### `padding`: [PaddingOptions](./types.md#paddingoptions) {#padding} + +Default: `null` + +The padding in pixels around the viewport. + +#### `minZoom`: number {#minzoom} + +Default: `0` + +The minimum zoom level of the map (0-24). + +#### `maxZoom`: number {#maxzoom} + +Default: `22` + +The maximum zoom level of the map (0-24). + +#### `minPitch`: number {#minpitch} + +Default: `0` + +The minimum pitch of the map (0-85). + +#### `maxPitch`: number {#maxpitch} + +Default: `60` + +The maximum pitch of the map (0-85). + +#### `maxBounds`: [LngLatBoundsLike](./types.md#lnglatboundslike) {#maxbounds} + +Default: `null` + +If set, the map is constrained to the given bounds. + +### Input handler options + +#### `boxZoom`: boolean {#boxzoom} + +Default: `true` + +If `true`, the "box zoom" interaction is enabled. See [BoxZoomHandler](https://maplibre.org/maplibre-gl-js/docs/API/classes/BoxZoomHandler/). + +#### `doubleClickZoom`: boolean {#doubleclickzoom} + +Default: `true` + +If `true`, the "double click to zoom" interaction is enabled. See [DoubleClickZoomHandler](https://maplibre.org/maplibre-gl-js/docs/API/classes/DoubleClickZoomHandler/). + +#### `dragRotate`: boolean {#dragrotate} + +Default: `true` + +If `true`, the "drag to rotate" interaction is enabled. See [DragRotateHandler](https://maplibre.org/maplibre-gl-js/docs/API/classes/DragRotateHandler/). + +#### `dragPan`: boolean | Object {#dragpan} + +Default: `true` + +If `true`, the "drag to pan" interaction is enabled. Optionally accpt an object value that is the options to [DragPanHandler](https://maplibre.org/maplibre-gl-js/docs/API/classes/DragPanHandler/). + +#### `keyboard`: boolean {#keyboard} + +Default: `true` + +If `true`, keyboard shortcuts are enabled. See [KeyboardHandler](https://maplibre.org/maplibre-gl-js/docs/API/classes/KeyboardHandler/). + +#### `scrollZoom`: boolean | Object {#scrollzoom} + +Default: `true` + +If `true`, the "scroll to zoom" interaction is enabled. Optionally accpt an object value that is the options to [ScrollZoomHandler](https://maplibre.org/maplibre-gl-js/docs/API/classes/ScrollZoomHandler/). + +#### `touchPitch`: boolean | Object {#touchpitch} + +Default: `true` + +If `true`, the "drag to pitch" interaction is enabled. Optionally accpt an object value that is the options to [TwoFingersTouchPitchHandler](https://maplibre.org/maplibre-gl-js/docs/API/classes/TwoFingersTouchPitchHandler/). + +#### `touchZoomRotate`: boolean | Object {#touchzoomrotate} + +Default: `true` + +If `true`, the "pinch to rotate and zoom" interaction is enabled. Optionally accpt an object value that is the options to [TwoFingersTouchZoomRotateHandler](https://maplibre.org/maplibre-gl-js/docs/API/classes/TwoFingersTouchZoomRotateHandler/). + +#### `interactiveLayerIds`: string[] {#interactivelayerids} + +Default: `null` + +The id(s) of style layer(s). + +If specified, pointer event (`mousemove`, `click` etc.) listeners will be triggered only if its location is within a visible feature in these layers, and the event will have a `features` property containing an array of the matching features. + +If not specified, pointer event listeners will be triggered by a corresponding event happening anywhere on the map, and the event will not have a `features` property. + +See the [Callbacks](#callbacks) section for affected events. + +### Callbacks + +#### `onResize`: (event: [MapEvent](./types.md#mapevent)) => void {#onresize} + +Called when the map has been resized. + +#### `onLoad`: (event: [MapEvent](./types.md#mapevent)) => void {#onload} + +Called after all necessary resources have been downloaded and the first visually complete rendering of the map has occurred. + +#### `onRender`: (event: [MapEvent](./types.md#mapevent))) => void {#onrender} + +Called whenever the map is drawn to the screen. + +#### `onIdle`: (event: [MapEvent](./types.md#mapevent))) => void {#onidle} + +Called after the last frame rendered before the map enters an "idle" state: + +- No camera transitions are in progress +- All currently requested tiles have loaded +- All fade/transition animations have completed + +#### `onRemove`: (event: [MapEvent](./types.md#mapevent))) => void {#onremove} + +Called when the map has been removed. + +#### `onError`: (event: [ErrorEvent](./types.md#errorevent)) => void {#onerror} + +Default: `evt => console.error(evt.error)` + +Called when an error occurs. + +#### `onMouseDown`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmousedown} + +Called when a pointing device (usually a mouse) is pressed within the map. + +If `interactiveLayerIds` is specified, the event will contain an additional `features` field that contains features under the cursor from the specified layer. + +#### `onMouseUp`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmouseup} + +Called when a pointing device (usually a mouse) is released within the map. + +If `interactiveLayerIds` is specified, the event will contain an additional `features` field that contains features under the cursor from the specified layer. + +#### `onMouseOver`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmouseover} + +Called when a pointing device (usually a mouse) is moved within the map. As you move the cursor across a web page containing a map, the event will fire each time it enters the map or any child elements. + +#### `onMouseEnter`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmouseenter} + +Called when a pointing device (usually a mouse) enters a visible portion of the layer(s) specified by `interactiveLayerIds` from outside that layer or outside the map canvas. + +#### `onMouseMove`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmousemove} + +Called when a pointing device (usually a mouse) is moved while the cursor is inside the map. As you move the cursor across the map, the event will fire every time the cursor changes position within the map. + +If `interactiveLayerIds` is specified, the event will contain an additional `features` field that contains features under the cursor from the specified layer. + +#### `onMouseLeave`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmouseleave} + +Called when a pointing device (usually a mouse) leaves a visible portion of the layer(s) specified by `interactiveLayerIds` or moves from the layer to outside the map canvas. + +#### `onMouseOut`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmouseout} + +Called when a point device (usually a mouse) leaves the map's canvas. + +#### `onClick`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onclick} + +Called when a pointing device (usually a mouse) is pressed and released at the same point on the map. + +If `interactiveLayerIds` is specified, the event will contain an additional `features` field that contains features under the cursor from the specified layer. + +#### `onDblClick`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#ondblclick} + +Called when a pointing device (usually a mouse) is pressed and released twice at the same point on the map in rapid succession. + +If `interactiveLayerIds` is specified, the event will contain an additional `features` field that contains features under the cursor from the specified layer. + +#### `onContextMenu`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#oncontextmenu} + +Called when the right button of the mouse is clicked or the context menu key is pressed within the map. + +If `interactiveLayerIds` is specified, the event will contain an additional `features` field that contains features under the cursor from the specified layer. + +#### `onWheel`: (event: [MapWheelEvent](./types.md#mapwheelevent)) => void {#onwheel} + +Called when a wheel event occurs within the map. + +#### `onTouchStart`: (event: [MapLayerTouchEvent](./types.md#maplayertouchevent)) => void {#ontouchstart} + +Called when a `touchstart` event occurs within the map. + +If `interactiveLayerIds` is specified, the event will contain an additional `features` field that contains features under the cursor from the specified layer. + +#### `onTouchEnd`: (event: [MapLayerTouchEvent](./types.md#maplayertouchevent)) => void {#ontouchend} + +Called when a `touchend` event occurs within the map. + +If `interactiveLayerIds` is specified, the event will contain an additional `features` field that contains features under the cursor from the specified layer. + +#### `onTouchMove`: (event: [MapLayerTouchEvent](./types.md#maplayertouchevent)) => void {#ontouchmove} + +Called when a `touchmove` event occurs within the map. + +If `interactiveLayerIds` is specified, the event will contain an additional `features` field that contains features under the cursor from the specified layer. + +#### `onTouchCancel`: (event: [MapLayerTouchEvent](./types.md#maplayertouchevent)) => void {#ontouchcancel} + +Called when a `touchcancel` event occurs within the map. + +If `interactiveLayerIds` is specified, the event will contain an additional `features` field that contains features under the cursor from the specified layer. + +#### `onMoveStart`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onmovestart} + +Called just before the map begins a transition from one view to another. + +#### `onMove`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onmove} + +Called repeatedly during an animated transition from one view to another. + +When `Map` is used as a controlled component, `event.viewState` reflects the view state that the camera "proposes" to move to, as a result of either user interaction or methods such as [flyTo](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#flyto). The camera does not actually change until the application updates the view state props (`longitude`, `latitude`, `zoom` etc.). +See [state management](../../get-started/state-management.md) for examples. + +#### `onMoveEnd`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onmoveend} + +Called just after the map completes a transition from one view to another. + +#### `onDragStart`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#ondragstart} + +Called when a "drag to pan" interaction starts. + +#### `onDrag`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#ondrag} + +Called repeatedly during a "drag to pan" interaction. + +#### `onDragEnd`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#ondragend} + +Called when a "drag to pan" interaction ends. + +#### `onZoomStart`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onzoomstart} + +Called just before the map begins a transition from one zoom level to another. + +#### `onZoom`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onzoom} + +Called repeatedly during an animated transition from one zoom level to another. + +When `Map` is used as a controlled component, `event.viewState.zoom` reflects the zoom that the camera "proposes" to change to, as a result of either user interaction or methods such as [flyTo](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#flyto). The camera does not actually change until the application updates the `zoom` prop. + +#### `onZoomEnd`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onzoomend} + +Called just after the map completes a transition from one zoom level to another. + +#### `onRotateStart`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onrotatestart} + +Called just before the map begins a transition from one bearing (rotation) to another. + +#### `onRotate`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onrotate} + +Called repeatedly during an animated transition from one bearing (rotation) to another. + +When `Map` is used as a controlled component, `event.viewState.bearing` reflects the zoom that the camera "proposes" to change to, as a result of either user interaction or methods such as [flyTo](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#flyto). The camera does not actually change until the application updates the `bearing` prop. + +#### `onRotateEnd`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onrotateend} + +Called just after the map completes a transition from one bearing (rotation) to another. + +#### `onPitchStart`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onpitchstart} + +Called just before the map begins a transition from one pitch (tilt) to another. + +#### `onPitch`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onpitch} + +Called repeatedly during an animated transition from one pitch (tilt) to another. + +When `Map` is used as a controlled component, `event.viewState.pitch` reflects the zoom that the camera "proposes" to change to, as a result of either user interaction or methods such as [flyTo](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#flyto). The camera does not actually change until the application updates the `pitch` prop. + +#### `onPitchEnd`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onpitchend} + +Called just after the map completes a transition from one pitch (tilt) to another. + +#### `onBoxZoomStart`: (event: [MapBoxZoomEvent](./types.md#mapboxzoomevent)) => void {#onboxzoomstart} + +Called when a "box zoom" interaction starts. + +#### `onBoxZoomEnd`: (event: [MapBoxZoomEvent](./types.md#mapboxzoomevent)) => void {#onboxzoomend} + +Called when a "box zoom" interaction ends. + +#### `onBoxZoomCancel`: (event:[MapBoxZoomEvent](./types.md#mapboxzoomevent)) => void {#onboxzoomcancel} + +Called when the user cancels a "box zoom" interaction, or when the bounding box does not meet the minimum size threshold. + +#### `onData`: (event: [MapStyleDataEvent](./types.md#mapstyledataevent) | [MapSourceDataEvent](./types.md#mapsourcedataevent)) => void {#ondata} + +Called when any map data loads or changes. See [MapDataEvent](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapDataEvent/) for more information. + +#### `onStyleData`: (event: [MapStyleDataEvent](./types.md#mapstyledataevent)) => void {#onstyledata} + +Called when the map's style loads or changes. See [MapDataEvent](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapDataEvent/) for more information. + +#### `onSourceData`: (event: [MapSourceDataEvent](./types.md#mapsourcedataevent)) => void {#onsourcedata} + +Called when one of the map's sources loads or changes, including if a tile belonging to a source loads or changes. See [MapDataEvent](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapDataEvent/) for more information. + +### Other options + +The following props, along with any [options](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapOptions/) of the `Map` class not listed above, can be specified to construct the underlying `Map` instance. + +Note: props in this section are not reactive. They are only used once when the Map instance is constructed. + +#### `mapLib`: any {#maplib} + +Default: +- `import('maplibre-gl')` + +Specify the underlying base map library for the Map component. The value can be provided with several options: + +By module import (and embedding in the final bundle): + +```tsx +import * as React from 'react'; +import {Map} from 'react-map-gl/maplibre'; +import maplibregl from 'maplibre-gl'; + +function App() { + return ; +} +``` + +By dynamic import (thus enable bundle splitting): + +```tsx +import * as React from 'react'; +import {Map} from 'react-map-gl/maplibre'; + +function App() { + return ; +} +``` + +Or to load a pre-bundled version of the library: + +```html title="index.html" + +``` + +```tsx title="app.tsx" +import * as React from 'react'; +import {Map} from 'react-map-gl/maplibre'; + +function App() { + return ; +} +``` + +#### `maxParallelImageRequests`: number {#maxparallelimagerequests} + +Default: `16` + +The maximum number of images (raster tiles, sprites, icons) to load in parallel. + +#### `reuseMaps`: boolean {#reusemaps} + +Default: `false` + +By default, every time a map component is unmounted, all internal resources associated with the underlying `Map` instance are released. If the map gets mounted again, a new `Map` instance is constructed. + +If `reuseMaps` is set to `true`, when a map component is unmounted, the underlying `Map` instance is retained in memory. The next time a map component gets mounted, the saved instance is reused. This behavior may be desirable if an application frequently mounts/unmounts map(s), for example in a tabbed or collapsable UI, and wants to avoid recreating the Map and its data cache triggered by initialization. + +Note that since some map options cannot be modified after initialization, when reusing maps, only the reactive props and `initialViewState` of the new component are respected. + +#### `RTLTextPlugin`: string | false {#rtltextplugin} + +Default: `'https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-rtl-text/v0.2.3/mapbox-gl-rtl-text.js'` + +Sets the map's [RTL text plugin](https://www.mapbox.com/mapbox-gl-js/plugins/#mapbox-gl-rtl-text). Necessary for supporting the Arabic and Hebrew languages, which are written right-to-left. + +Setting this prop is the equivalent of calling [setRTLTextPlugin](https://maplibre.org/maplibre-gl-js/docs/API/functions/setRTLTextPlugin/) with `lazy: true`. Set to `false` to disable loading the RTL text plugin. + + +#### `workerCount`: number {#workercount} + +Default: `2` + +The number of web workers instantiated on a page with maplibre-gl maps. + +#### `workerUrl`: string {#workerurl} + +Provides an interface for loading maplibre-gl's WebWorker bundle from a self-hosted URL. This is useful if your site needs to operate in a strict CSP (Content Security Policy) environment wherein you are not allowed to load JavaScript code from a Blob URL, which is default behavior. + + + +## Methods + +Imperative methods are accessible via a [React ref](https://reactjs.org/docs/refs-and-the-dom.html#creating-refs) or the [useMap](./use-map.md) hook. + + +```tsx +import * as React from 'react'; +import {useRef, useCallback} from 'react'; +import {Map} from 'react-map-gl/maplibre'; +import type {MapRef} from 'react-map-gl/maplibre'; + +function App() { + const mapRef = useRef(); + + const onMapLoad = useCallback(() => { + mapRef.current.on('move', () => { + // do something + }); + }, []); + + return ; +} +``` + + +The [MapRef](./types.md#mapref) object exposes [Map methods](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#methods) that **are safe to call without breaking the React bindings**. For example, `setStyle()` is hidden from the ref object, because the style is supposed to be changed by updating the `mapStyle` prop. Calling the method directly may cause the the React prop to mismatch with the underlying state, and lead to unexpected behaviors. + +You can still access the hidden members via `getMap()`: + +#### `getMap()` {#getmap} + +Returns the native [Map](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/) instance associated with this component. + + + +## Source + +[map.tsx](https://github.com/visgl/react-map-gl/tree/master/modules/maplibre/src/components/map.tsx) diff --git a/docs/api-reference/maplibre/marker.md b/docs/api-reference/maplibre/marker.md new file mode 100644 index 000000000..86670995f --- /dev/null +++ b/docs/api-reference/maplibre/marker.md @@ -0,0 +1,149 @@ +# Marker + +React component that wraps maplibre-gl's [Marker](https://maplibre.org/maplibre-gl-js/docs/API/classes/Marker/) class. + + +```tsx +import * as React from 'react'; +import {Map, Marker} from 'react-map-gl/maplibre'; +import 'maplibre-gl/dist/maplibre-gl.css'; + +function App() { + return + + + + ; +} +``` + + +If `Marker` is mounted with child components, then its content will be rendered to the specified location. If it is mounted with no content, then a default marker will be used. + +## Properties + +### Reactive Properties + +#### `draggable`: boolean {#draggable} + +Default: `false` + +If `true`, the marker is able to be dragged to a new position on the map. + +#### `latitude`: number {#latitude} + +Required. The latitude of the anchor location. + +#### `longitude`: number {#longitude} + +Required. The longitude of the anchor location. + +#### `offset`: [PointLike](./types.md#pointlike) {#offset} + +Default: `null` + +The offset in pixels as a [PointLike](./types.md#pointlike) object to apply relative to the element's center. Negatives indicate left and up. + +#### `pitchAlignment`: 'map' | 'viewport' | 'auto' {#pitchalignment} + +Default: `'auto'` + +- `map` aligns the `Marker` to the plane of the map. +- `viewport` aligns the `Marker` to the plane of the viewport. +- `auto` automatically matches the value of `rotationAlignment`. + +#### `popup`: Popup | null {#popup} + +An instance of the [Popup](https://maplibre.org/maplibre-gl-js/docs/API/classes/Popup/) class to attach to this marker. If undefined or null, any popup set on this Marker instance is unset. + +#### `rotation`: number {#rotation} + +Default: `0` + +The rotation angle of the marker in degrees, relative to its `rotationAlignment` setting. A positive value will rotate the marker clockwise. + +#### `rotationAlignment`: 'map' | 'viewport' | 'auto' {#rotationalignment} + +Default: `'auto'` + +- `map` aligns the `Marker`'s rotation relative to the map, maintaining a bearing as the map rotates. +- `viewport` aligns the `Marker`'s rotation relative to the viewport, agnostic to map rotations. +- `auto` is equivalent to `viewport`. + +#### `style`: CSSProperties {#style} + +CSS style override that applies to the marker's container. + +### Callbacks + +#### `onClick`: (evt: [MapEvent](./types.md#mapevent)) => void {#onclick} + +Called when the marker is clicked on. + +#### `onDragStart`: (evt: [MarkerDragEvent](./types.md#markerdragevent)) => void {#ondragstart} + +Called when dragging starts, if `draggable` is `true`. + +#### `onDrag`: (evt: [MarkerDragEvent](./types.md#markerdragevent)) => void {#ondrag} + +Called while dragging, if `draggable` is `true`. + +#### `onDragEnd`: (evt: [MarkerDragEvent](./types.md#markerdragevent)) => void {#ondragend} + +Called when dragging ends, if `draggable` is `true`. + + +### Other Properties + +The properties in this section are not reactive. They are only used when the component first mounts. + +Any [options](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MarkerOptions/) supported by the `Marker` class, such as + +- `anchor` +- `color` +- `scale` +- `clickTolerance` + + +## Methods + +The underlying native `Marker` 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: + + +```tsx +import * as React from 'react'; +import {useRef, useMemo, useCallback} from 'react'; +import {Map, Marker} from 'react-map-gl/maplibre'; +import maplibregl from 'maplibre-gl'; + +function App() { + const markerRef = useRef(); + + const popup = useMemo(() => { + return maplibregl.Popup().setText('Hello world!'); + }, []) + + const togglePopup = useCallback(() => { + markerRef.current?.togglePopup(); + }, []); + + return <> + + + + + ; +} +``` + +## Source + +[marker.ts](https://github.com/visgl/react-map-gl/tree/master/modules/maplibre/src/components/marker.ts) diff --git a/docs/api-reference/maplibre/navigation-control.md b/docs/api-reference/maplibre/navigation-control.md new file mode 100644 index 000000000..2e38b128e --- /dev/null +++ b/docs/api-reference/maplibre/navigation-control.md @@ -0,0 +1,55 @@ +# NavigationControl + +React component that wraps maplibre-gl's [NavigationControl](https://maplibre.org/maplibre-gl-js/docs/API/classes/NavigationControl/) class. + + +```tsx +import * as React from 'react'; +import {Map, NavigationControl} from 'react-map-gl/maplibre'; +import 'maplibre-gl/dist/maplibre-gl.css'; + +function App() { + return + + ; +} +``` + + +## Properties + +### Reactive Properties + +#### `style`: CSSProperties {#style} + +CSS style override that applies to the control's container. + +### Other Properties + +The properties in this section are not reactive. They are only used when the component first mounts. + +Any [options](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/NavigationControlOptions/) supported by the `NavigationControl` class, such as + +- `showCompass` +- `showZoom` +- `visualizePitch` + +Plus the following: + +#### `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position} + +Default: `'top-right'` + +Placement of the control relative to the map. + + +## Source + +[navigation-control.ts](https://github.com/visgl/react-map-gl/tree/master/modules/maplibre/src/components/navigation-control.ts) diff --git a/docs/api-reference/maplibre/popup.md b/docs/api-reference/maplibre/popup.md new file mode 100644 index 000000000..190e04691 --- /dev/null +++ b/docs/api-reference/maplibre/popup.md @@ -0,0 +1,122 @@ +# Popup + +React component that wraps maplibre-gl's [Popup](https://maplibre.org/maplibre-gl-js/docs/API/classes/Popup/) class. + + +```tsx +import * as React from 'react'; +import {useState} from 'react'; +import {Map, Popup} from 'react-map-gl/maplibre'; +import 'maplibre-gl/dist/maplibre-gl.css'; + +function App() { + const [showPopup, setShowPopup] = useState(true); + + return + {showPopup && ( + setShowPopup(false)}> + You are here + )} + ; +} +``` + + +## Properties + +### Reactive Properties + +#### `anchor`: 'center' | 'left' | 'right' | 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | undefined {#anchor} + +A string indicating the part of the popup that should be positioned closest to the coordinate, set via `longitude` and `latitude`. +If unset, the anchor will be dynamically set to ensure the popup falls within the map container with a preference for `'bottom'`. + +#### `className`: string {#classname} + +Space-separated CSS class names to add to popup container. + +#### `offset`: number | [PointLike](./types.md#pointlike) | Record\ {#offset} + +Default: `null` + +A pixel offset applied to the popup's location specified as: + +- a single number specifying a distance from the popup's location +- a PointLike specifying a constant offset +- an object of Points specifing an offset for each anchor position. + +Negative offsets indicate left and up. + +#### `maxWidth`: string {#maxwidth} + +Default: `240px` + +A string that sets the CSS property of the popup's maximum width. + +#### `style`: CSSProperties {#style} + +CSS style override that applies to the popup's container. + +### Callbacks + +#### `onOpen`: (evt: [PopupEvent](./types.md#popupevent)) => void {#onopen} + +Called when the popup is opened. + +#### `onClose`: (evt: [PopupEvent](./types.md#popupevent)) => void {#onclose} + +Called when the popup is closed by the user clicking on the close button or outside (if `closeOnClick: true`). + + +### Other Properties + +The properties in this section are not reactive. They are only used when the component first mounts. + +Any [options](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/PopupOptions/) supported by the `Popup` class, such as + +- `closeButton` +- `closeOnClick` +- `closeOnMove` +- `focusAfterOpen` + + +## Methods + +The underlying native `Popup` 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: + + +```tsx +import * as React from 'react'; +import {useRef, useEffect} from 'react'; +import {Map, Popup} from 'react-map-gl/maplibre'; +import maplibregl from 'maplibre-gl'; + +function App() { + const popupRef = useRef(); + + useEffect(() => { + popupRef.current?.trackPointer(); + }, [popupRef.current]) + + return + + Tooltip + + ; +} +``` + + +## Source + +[popup.ts](https://github.com/visgl/react-map-gl/tree/master/modules/maplibre/src/components/popup.ts) diff --git a/docs/api-reference/maplibre/scale-control.md b/docs/api-reference/maplibre/scale-control.md new file mode 100644 index 000000000..d912ee603 --- /dev/null +++ b/docs/api-reference/maplibre/scale-control.md @@ -0,0 +1,59 @@ +# ScaleControl + +React component that wraps maplibre-gl's [ScaleControl](https://maplibre.org/maplibre-gl-js/docs/API/classes/ScaleControl/) class. + +```tsx +import * as React from 'react'; +import {Map, ScaleControl} from 'react-map-gl/maplibre'; +import 'maplibre-gl/dist/maplibre-gl.css'; + +function App() { + return + + ; +} +``` + + +## Properties + +### Reactive Properties + +#### `maxWidth`: string {#maxwidth} + +Default: `100` + +The maximum length of the scale control in pixels. + +#### `style`: CSSProperties {#style} + +CSS style override that applies to the control's container. + +#### `unit`: 'imperial' | 'metric' | 'nautical' {#unit} + +Default: `'metric'` + +Unit of the distance. + + +### Other Properties + +The properties in this section are not reactive. They are only used when the component first mounts. + +#### `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position} + +Default: `'top-right'` + +Placement of the control relative to the map. + + +## Source + +[scale-control.ts](https://github.com/visgl/react-map-gl/tree/master/modules/maplibre/src/components/scale-control.ts) diff --git a/docs/api-reference/maplibre/source.md b/docs/api-reference/maplibre/source.md new file mode 100644 index 000000000..88e578496 --- /dev/null +++ b/docs/api-reference/maplibre/source.md @@ -0,0 +1,64 @@ +# Source + +This component allows apps to create a [map source](https://maplibre.org/maplibre-style-spec/sources/) using React. It may contain [Layer](./layer.md) components as children. + + +```tsx +import * as React from 'react'; +import {Map, Source, Layer} from 'react-map-gl/maplibre'; +import type {CircleLayer} from 'react-map-gl/maplibre'; +import type {FeatureCollection} from 'geojson'; +import 'maplibre-gl/dist/maplibre-gl.css'; + +const geojson: FeatureCollection = { + type: 'FeatureCollection', + features: [ + {type: 'Feature', geometry: {type: 'Point', coordinates: [-122.4, 37.8]}} + ] +}; + +const layerStyle: CircleLayer = { + id: 'point', + type: 'circle', + paint: { + 'circle-radius': 10, + 'circle-color': '#007cbf' + } +}; + +function App() { + return + + + + ; +} +``` + + +## Properties + +The props provided to this component should be conforming to the [Mapbox source specification](https://maplibre.org/maplibre-style-spec/sources/) or [CanvasSourceSpecification](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/CanvasSourceSpecification/). + +When props change _shallowly_, the component will attempt to update the source. Do not define objects/arrays inline to avoid perf hit. + +Once a `` is mounted, the following props should not change. If add/remove multiple JSX sources dynamically, make sure you use React's [key prop](https://reactjs.org/docs/lists-and-keys.html#keys) to give each element a stable identity. + +#### `id`: string {#id} + +Unique identifier of the source. If not provided, a default id will be assigned. + +#### `type`: string {#type} + +Required. Type of the source. + +## Source + +[source.ts](https://github.com/visgl/react-map-gl/tree/master/modules/maplibre/src/components/source.ts) diff --git a/docs/api-reference/maplibre/terrain-control.md b/docs/api-reference/maplibre/terrain-control.md new file mode 100644 index 000000000..65a64662b --- /dev/null +++ b/docs/api-reference/maplibre/terrain-control.md @@ -0,0 +1,85 @@ +# TerrainControl + +React component that wraps maplibre-gl's [TerrainControl](https://maplibre.org/maplibre-gl-js/docs/API/classes/TerrainControl/) class. + +```tsx +import * as React from 'react'; +import {Map, MapStyle, TerrainControl} from 'react-map-gl/maplibre'; +import 'maplibre-gl/dist/maplibre-gl.css'; + +// https://maplibre.org/maplibre-gl-js/docs/examples/3d-terrain/ +const MAP_STYLE: MapStyle = { + version: 8, + sources: { + osm: { + type: 'raster', + tiles: ['https://a.tile.openstreetmap.org/{z}/{x}/{y}.png'], + tileSize: 256, + attribution: '© OpenStreetMap Contributors', + maxzoom: 19 + }, + terrainSource: { + type: 'raster-dem', + url: 'https://demotiles.maplibre.org/terrain-tiles/tiles.json', + tileSize: 256 + } + }, + layers: [ + { + id: 'osm', + type: 'raster', + source: 'osm' + } + ], + terrain: { + source: 'terrainSource', + exaggeration: 1 + }, + sky: {} +}; + +function App() { + return + + ; +} +``` + + +## Properties + +### Reactive Properties + +#### `style`: CSSProperties {#style} + +CSS style override that applies to the control's container. + + +### Other Properties + +The properties in this section are not reactive. They are only used when the component first mounts. + +Any [options](https://maplibre.org/maplibre-style-spec/terrain/) supported by the `TerrainControl` class, such as + +- `source` +- `exageration` + +Plus the following: + +#### `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position} + +Default: `'top-right'` + +Placement of the control relative to the map. + + +## Source + +[terrain-control.ts](https://github.com/visgl/react-map-gl/tree/master/modules/maplibre/src/components/terrain-control.ts) diff --git a/docs/api-reference/maplibre/types.md b/docs/api-reference/maplibre/types.md new file mode 100644 index 000000000..8fb0ac2a4 --- /dev/null +++ b/docs/api-reference/maplibre/types.md @@ -0,0 +1,312 @@ +# Types + +The following types can be imported from `react-map-gl/maplibre` when using TypeScript. + +## Components + +#### IControl + +A [custom control implementation](https://maplibre.org/maplibre-gl-js/docs/API/interfaces/IControl/). + +#### CustomLayerInterface + +A [custom layer implementation](https://maplibre.org/maplibre-gl-js/docs/API/interfaces/CustomLayerInterface/). + +#### MapRef + +Instance [ref](https://reactjs.org/docs/refs-and-the-dom.html#creating-refs) of a `Map` component. See [Map documentation](./map.md#methods) for details. + + +## Styling + +#### StyleSpecification + +An object conforming to the [Maplibre Style Specification](https://maplibre.org/maplibre-style-spec/). + +#### SkySpecification + +An object conforming to the [Sky Style Specification](https://maplibre.org/maplibre-style-spec/sky/). + +#### LightSpecification + +An object conforming to the [Light Style Specification](https://maplibre.org/maplibre-style-spec/light/). + +#### TerrainSpecification + +An object conforming to the [Terrain Style Specification](https://maplibre.org/maplibre-style-spec/terrain/). + +#### ProjectionSpecification + +An object conforming to the [Projection Style Specification](https://maplibre.org/maplibre-style-spec/projection/). + +#### BackgroundLayerSpecification + +A JSON object that defines a `background` layer according to the [Maplibre Style Specification](https://maplibre.org/maplibre-style-spec/layers/#background). + +#### CircleLayerSpecification + +A JSON object that defines a `circle` layer according to the [Maplibre Style Specification](https://maplibre.org/maplibre-style-spec/layers//#circle). + +#### FillExtrusionLayerSpecification + +A JSON object that defines a `fill-extrusion` layer according to the [Maplibre Style Specification](https://maplibre.org/maplibre-style-spec/layers/#fill-extrusion). + +#### FillLayerSpecification + +A JSON object that defines a `fill` layer according to the [Maplibre Style Specification](https://maplibre.org/maplibre-style-spec/layers/#fill). + +#### HeatmapLayerSpecification + +A JSON object that defines a `heatmap` layer according to the [Maplibre Style Specification](https://maplibre.org/maplibre-style-spec/layers/#heatmap). + +#### HillshadeLayerSpecification + +A JSON object that defines a `hillshade` layer according to the [Maplibre Style Specification](https://maplibre.org/maplibre-style-spec/layers/#hillshade). + +#### LineLayerSpecification + +A JSON object that defines a `line` layer according to the [Maplibre Style Specification](https://maplibre.org/maplibre-style-spec/layers/#line). + +#### RasterLayerSpecification + +A JSON object that defines a `raster` layer according to the [Maplibre Style Specification](https://maplibre.org/maplibre-style-spec/layers/#raster). + +#### SymbolLayerSpecification + +A JSON object that defines a `symbol` layer according to the [Maplibre Style Specification](https://maplibre.org/maplibre-style-spec/layers/#symbol). + + +#### GeoJSONSourceSpecification + +A JSON object that defines a `geojson` source according to the [Maplibre Style Specification](https://maplibre.org/maplibre-style-spec/sources/#geojson). + +#### VideoSourceSpecification + +A JSON object that defines a `video` source according to the [Maplibre Style Specification](https://maplibre.org/maplibre-style-spec/sources/#video). + +#### ImageSourceSpecification + +A JSON object that defines a `image` source according to the [Maplibre Style Specification](https://maplibre.org/maplibre-style-spec/sources/#image). + +#### VectorSourceSpecification + +A JSON object that defines a `vector` source according to the [Maplibre Style Specification](https://maplibre.org/maplibre-style-spec/sources/#vector). + +#### RasterSourceSpecification + +A JSON object that defines a `raster` source according to the [Maplibre Style Specification](https://maplibre.org/maplibre-style-spec/sources/#raster). + +#### RasterDEMSourceSpecification + +A JSON object that defines a `raster-dem` source according to the [Maplibre Style Specification](https://maplibre.org/maplibre-style-spec/sources/#raster-dem). + +#### CanvasSourceSpecification + +A JSON object that defines a `canvas` source type. See [CanvasSourceSpecification](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/CanvasSourceSpecification/). + + +## Configurations + +#### ControlPosition + +One of `'top-right'`, `'top-left'`, `'bottom-right'` and `'bottom-left'`. + +#### PaddingOptions + +An object with the following fields: + +- `left`: number - in pixels. +- `top`: number - in pixels. +- `right`: number - in pixels. +- `bottom`: number - in pixels. + + +## Data Types + +#### LngLat + +A Maplibre [LngLat](https://maplibre.org/maplibre-gl-js/docs/API/classes/LngLat/) object. + +#### LngLatLike + +A Maplibre [LngLatLike](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/LngLatLike/) object. + +#### LngLatBounds + +A Maplibre [LngLatBounds](https://maplibre.org/maplibre-gl-js/docs/API/classes/LngLatBounds/) object. + +#### LngLatBoundsLike + +A Maplibre [LngLatBoundsLike](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/LngLatBoundsLike/) object. + +#### Point + +A Maplibre [Point](https://github.com/mapbox/point-geometry) object. + +#### PointLike + +A Maplibre [PointLike](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/PointLike/) object. + +#### MapGeoJSONFeature + +A [GeoJSON](http://geojson.org/) feature that also contains the following library-specific fields: + +- `layer`: Layer +- `source`: string +- `sourceLayer`: string +- `state`: `{ [key: string]: any }` + +#### ViewState + +An object with the following fields: + +- `longitude`: number - The longitude of the map center. +- `latitude`: number - The latitude of the map center. +- `zoom`: number - The zoom level. +- `pitch`: number - The pitch (tilt) of the map, in degrees. +- `bearing`: number - The bearing (rotation) of the map, in degrees. + + +## Events + +#### MapEvent + +An object with the following fields: + +- `type`: string - Event type +- `target`: [Map](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/) +- `originalEvent?`: [Event](https://developer.mozilla.org/en-US/docs/Web/API/Event) + +#### MapLayerMouseEvent + +An object with the following fields: + +- `type`: string +- `target`: [Map](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/) +- `originalEvent?`: [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent) +- `point`: [Point](#point) +- `lngLat`: [LngLat](#lnglat) +- `preventDefault`: () => void +- `defaultPrevented`: boolean +- `features?`: [MapGeoJSONFeature](#mapgeojsonfeature)[] + +#### MapWheelEvent + +An object with the following fields: + +- `type`: string +- `target`: [Map](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/) +- `originalEvent?`: [WheelEvent](https://developer.mozilla.org/en-US/docs/Web/API/WheelEvent) +- `preventDefault`: () => void +- `defaultPrevented`: boolean + +#### MapLayerTouchEvent + +An object with the following fields: + +- `type`: string +- `target`: [Map](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/) +- `originalEvent?`: [TouchEvent](https://developer.mozilla.org/en-US/docs/Web/API/TouchEvent) +- `point`: [Point](#point) +- `lngLat`: [LngLat](#lnglat) +- `points`: [Point](#point)[] +- `lngLats`: [LngLat](#lnglat)[] +- `preventDefault`: () => void +- `defaultPrevented`: boolean +- `features?`: [MapGeoJSONFeature](#mapgeojsonfeature)[] + +#### ViewStateChangeEvent + +An object with the following fields: + +- `type`: string - Event type +- `target`: [Map](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/) +- `viewState`: [ViewState](#viewstate) - the next view state that the camera wants to change to based on user input or transition. + +#### MapBoxZoomEvent + +An object with the following fields: + +- `type`: string +- `target`: [Map](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/) +- `originalEvent?`: [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent) +- `boxZoomBounds`: [LngLatBounds](#lnglatbounds) + +#### MapStyleDataEvent + +An object with the following fields: + +- `type`: string +- `target`: [Map](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/) +- `dataType`: 'style' + +#### MapSourceDataEvent + +An object with the following fields: + +- `type`: string +- `target`: [Map](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/) +- `dataType`: 'source' +- `isSourceLoaded`: boolean +- `source`: string +- `sourceId`: string +- `sourceDataType`: 'metadata' | 'content' +- `tile`: any +- `coord`: Coordinate + +See [MapDataEvent](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapDataEvent/). + +#### ErrorEvent + +An object with the following fields: + +- `type`: 'error' +- `target`: [Map](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/) +- `error`: [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) + +#### GeolocateEvent + +An object with the following fields: + +- `type`: string +- `target`: [GeolocateControl](https://maplibre.org/maplibre-gl-js/docs/API/classes/GeolocateControl/) + +#### GeolocateResultEvent + +An object with the following fields: + +- `type`: string +- `target`: [GeolocateControl](https://maplibre.org/maplibre-gl-js/docs/API/classes/GeolocateControl/) +- `coords`: [GeolocationCoordinates](https://developer.mozilla.org/en-US/docs/Web/API/GeolocationCoordinates) - the current location. +- `timestamp`: number - the time at which the location was retrieved. + +#### GeolocateErrorEvent + +An object with the following fields: + +- `type`: string +- `target`: [GeolocateControl](https://maplibre.org/maplibre-gl-js/docs/API/classes/GeolocateControl/) +- `code`: PERMISSION_DENIED | POSITION_UNAVAILABLE | TIMEOUT - see [GeolocationPositionError](https://developer.mozilla.org/en-US/docs/Web/API/GeolocationPositionError) +- `message`: string - the details of the error. Specifications note that this is primarily intended for debugging use and not to be shown directly in a user interface. + +#### MarkerEvent + +An object with the following fields: + +- `type`: string +- `target`: [Marker](https://maplibre.org/maplibre-gl-js/docs/API/classes/Marker/) + +#### MarkerDragEvent + +An object with the following fields: + +- `type`: string +- `target`: [Marker](https://maplibre.org/maplibre-gl-js/docs/API/classes/Marker/) +- `lngLat`: [LngLat](#lnglat) - the new location of the marker + +#### PopupEvent + +An object with the following fields: + +- `type`: string +- `target`: [Popup](https://maplibre.org/maplibre-gl-js/docs/API/classes/Popup/) diff --git a/docs/api-reference/maplibre/use-control.md b/docs/api-reference/maplibre/use-control.md new file mode 100644 index 000000000..627150215 --- /dev/null +++ b/docs/api-reference/maplibre/use-control.md @@ -0,0 +1,87 @@ +# useControl + +The `useControl` hook is used to create React wrappers for custom map controls. + +```tsx +import MapboxDraw from '@mapbox/mapbox-gl-draw'; +import {Map, useControl} from 'react-map-gl/maplibre'; + +function DrawControl(props: DrawControlProps) { + useControl(() => new MapboxDraw(props), { + position: props.position + }); + + return null; +} + +function App() { + return ( + + + + ); +} +``` + +See a full example [here](/examples/maplibre/draw-polygon). + +## Signature + +```js +useControl( + onCreate: ({map: MapRef, mapLib: maplibregl}) => IControl, + options?: { + position?: ControlPosition; + } +): T + +useControl( + onCreate: ({map: MapRef, mapLib: maplibregl}) => IControl, + onRemove: ({map: MapRef, mapLib: maplibregl}) => void, + options?: { + position?: ControlPosition; + } +): T + +useControl( + onCreate: ({map: MapRef, mapLib: maplibregl}) => IControl, + onAdd: ({map: MapRef, mapLib: maplibregl}) => void, + onRemove: ({map: MapRef, mapLib: maplibregl}) => void, + options?: { + position?: ControlPosition; + } +): T +``` + +The hook creates an [IControl](https://maplibre.org/maplibre-gl-js/docs/API/interfaces/IControl/) instance, adds it to the map when it's available, and removes it upon unmount. + +Parameters: + +- `onCreate`: `({map: MapRef, mapLib: maplibregl}) => IControl` - called to create an instance of the control. +- `onAdd`: `({map: MapRef, mapLib: maplibregl}) => void` - called when the control has been added to the map. +- `onRemove`: `({map: MapRef, mapLib: maplibregl}) => void` - called when the control is about to be removed from the map. +- `options`: object + + `position`: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' - control position relative to the map + +Returns: + +[IControl](./types.md#icontrol) - the control instance from `onCreate`. + + +## Source + +[use-control.ts](https://github.com/visgl/react-map-gl/tree/master/modules/maplibre/src/components/use-control.ts) diff --git a/docs/api-reference/maplibre/use-map.md b/docs/api-reference/maplibre/use-map.md new file mode 100644 index 000000000..631132348 --- /dev/null +++ b/docs/api-reference/maplibre/use-map.md @@ -0,0 +1,70 @@ +# useMap + +The `useMap` hook allows a custom component to reference the [Map](./map.md) that contains it. + + +```tsx +import {Map, useMap} from 'react-map-gl/maplibre'; + +function Root() { + return ( + + + + ); +} + +function NavigateButton() { + const {current: map} = useMap(); + + const onClick = () => { + map.flyTo({center: [-122.4, 37.8]}); + }; + + return ; +} +``` + + +When used with the [MapProvider](./map-provider.md), this hook can also reference maps that are rendered outside of the current component's direct render tree. + + +```tsx +import {MapProvider, Map, useMap} from 'react-map-gl/maplibre'; + +function Root() { + return ( + + + + + + ); +} + +function NavigateButton() { + const {myMapA, myMapB} = useMap(); + + const onClick = () => { + myMapA.flyTo({center: [-122.4, 37.8]}); + myMapB.flyTo({center: [-74, 40.7]}); + }; + + return ; +} +``` + + +See a full example [here](https://github.com/visgl/react-map-gl/tree/master/examples/get-started/hook). + +## Signature + +`useMap(): {current?: MapRef, [id: string]: MapRef}` + +The hook returns an object that contains all mounted maps under the closest `MapProvider`. The keys are each map's [id](./map.md#id) and the values are the [MapRef](./types.md#mapref). + +If the hook is used inside a decendent of a `Map` component, the returned object also contains a `current` field that references the containing map. + +## Source + +[use-map.tsx](https://github.com/visgl/react-map-gl/tree/master/modules/maplibre/src/components/use-map.tsx) diff --git a/docs/get-started/adding-custom-data.md b/docs/get-started/adding-custom-data.md index c9e214862..c419685ba 100644 --- a/docs/get-started/adding-custom-data.md +++ b/docs/get-started/adding-custom-data.md @@ -2,12 +2,12 @@ ## Native Mapbox Layers -You can inject data and mapbox native layers using the [Source](../api-reference/source.md) and [Layer](../api-reference/layer.md) components: +You can inject data and mapbox native layers using the [Source](../api-reference/mapbox/source.md) and [Layer](../api-reference/mapbox/layer.md) components: ```tsx import * as React from 'react'; -import Map, {Source, Layer} from 'react-map-gl'; -import type {CircleLayer} from 'react-map-gl'; +import Map, {Source, Layer} from 'react-map-gl/maplibre'; +import type {CircleLayer} from 'react-map-gl/maplibre'; import type {FeatureCollection} from 'geojson'; const geojson: FeatureCollection = { diff --git a/docs/get-started/get-started.md b/docs/get-started/get-started.md index 241421e3c..a7505a636 100644 --- a/docs/get-started/get-started.md +++ b/docs/get-started/get-started.md @@ -1,6 +1,6 @@ # Get Started -You may find complete project setups in [get-started examples](https://github.com/visgl/react-map-gl/tree/7.0-release/examples/get-started). +You may find complete project setups in [get-started examples](https://github.com/visgl/react-map-gl/tree/8.0-release/examples/get-started). ## Installation @@ -33,7 +33,10 @@ npm install react-map-gl maplibre-gl ```tsx title="app.tsx" import * as React from 'react'; -import Map from 'react-map-gl'; +import Map from 'react-map-gl/mapbox'; +// If using with mapbox-gl v1: +// import Map from 'react-map-gl/mapbox-legacy'; +import 'mapbox-gl/dist/mapbox-gl.css'; function App() { return ( @@ -59,6 +62,7 @@ See [about Mapbox tokens](./mapbox-tokens.md) for alternatives to providing a Ma ```tsx title="app.tsx" import * as React from 'react'; import Map from 'react-map-gl/maplibre'; +import 'maplibre-gl/dist/maplibre-gl.css'; function App() { return ( @@ -81,9 +85,11 @@ function App() { ## Styling -The base map library requires its stylesheet be included at all times. The marker, popup and navigation components in react-map-gl also need the stylesheet to work properly. +The base map library requires its stylesheet be included at all times. The marker, popup and navigation components in react-map-gl also need the stylesheet to work properly. + +The above example code imports the CSS file directly into the app. Most bundlers support this syntax out-of-the-box or with an official plugin. -You may add the stylesheet to the head of your page: +Alternatively, you may add the stylesheet to the head of your page: @@ -105,43 +111,3 @@ Find out your maplibre version by running `yarn list maplibre-gl` or `npm ls map - -Or embed it in your app by using [css-loader](https://webpack.github.io/docs/stylesheets.html) with Webpack or [postcss](https://www.npmjs.com/package/rollup-plugin-postcss) with rollup: - - - - -```ts title="app.tsx" -import 'mapbox-gl/dist/mapbox-gl.css'; -``` - - - - -```ts title="app.tsx" -import 'maplibre-gl/dist/maplibre-gl.css'; -``` - - - - - -## Using with a Compatible Fork - -```bash -npm install react-map-gl my-map-gl-fork -``` - -Then override the `mapLib` prop of `Map`: - -```tsx title="app.tsx" -import * as React from 'react'; -import Map from 'react-map-gl'; - -// Include style sheet -import 'my-map-gl-fork/path/to/style-sheet.css'; - -function App() { - return ; -} -``` diff --git a/docs/get-started/state-management.md b/docs/get-started/state-management.md index 3cd564a1c..029782382 100644 --- a/docs/get-started/state-management.md +++ b/docs/get-started/state-management.md @@ -1,6 +1,6 @@ # State Management -There are two ways to use a [Map](../api-reference/map.md): +There are two ways to use a [Map](../api-reference/maplibre/map.md): - [Uncontrolled](https://reactjs.org/docs/uncontrolled-components.html): The application sets the initial view state (Camera options) when the map is mounted, and the component automatically makes changes to the view states afterwards. This mode works very similarly to the mapbox-gl `Map` class. - [Controlled](https://reactjs.org/docs/forms.html#controlled-components): The application manages the view state, and pass it to the map via props. The map invokes a callback with a new view state during user interaction transition, and the application can decide what to do with it. This mode is the most powerful when an application has other components that need to interact with the map, or implements its own user input and data handling logic. @@ -12,7 +12,7 @@ You may clone a full app configuration for this example [here](https://github.co ```tsx import * as React from 'react'; -import Map from 'react-map-gl'; +import Map from 'react-map-gl/maplibre'; function App() { return @@ -96,7 +96,7 @@ If your application uses externally managed camera state, like with Redux, the n ```tsx import {useSelector, useDispatch} from 'react-redux'; -import Map, {Marker} from 'react-map-gl'; +import Map, {Marker} from 'react-map-gl/maplibre'; function MapView() { const viewState = useSelector((s: RootState) => s.viewState); diff --git a/docs/table-of-contents.json b/docs/table-of-contents.json index 39d2f9c7a..394379d65 100644 --- a/docs/table-of-contents.json +++ b/docs/table-of-contents.json @@ -24,20 +24,48 @@ "type": "category", "label": "API Reference", "items": [ - "api-reference/map", - "api-reference/attribution-control", - "api-reference/fullscreen-control", - "api-reference/geolocate-control", - "api-reference/layer", - "api-reference/map-provider", - "api-reference/marker", - "api-reference/navigation-control", - "api-reference/popup", - "api-reference/scale-control", - "api-reference/source", - "api-reference/use-control", - "api-reference/use-map", - "api-reference/types" + { + "type": "category", + "label": "Mapbox", + "items": [ + "api-reference/mapbox/map", + "api-reference/mapbox/attribution-control", + "api-reference/mapbox/fullscreen-control", + "api-reference/mapbox/geolocate-control", + "api-reference/mapbox/layer", + "api-reference/mapbox/map-provider", + "api-reference/mapbox/marker", + "api-reference/mapbox/navigation-control", + "api-reference/mapbox/popup", + "api-reference/mapbox/scale-control", + "api-reference/mapbox/source", + "api-reference/mapbox/use-control", + "api-reference/mapbox/use-map", + "api-reference/mapbox/types" + ] + }, + { + "type": "category", + "label": "Maplibre", + "items": [ + "api-reference/maplibre/map", + "api-reference/maplibre/attribution-control", + "api-reference/maplibre/fullscreen-control", + "api-reference/maplibre/geolocate-control", + "api-reference/maplibre/layer", + "api-reference/maplibre/logo-control", + "api-reference/maplibre/map-provider", + "api-reference/maplibre/marker", + "api-reference/maplibre/navigation-control", + "api-reference/maplibre/popup", + "api-reference/maplibre/scale-control", + "api-reference/maplibre/source", + "api-reference/maplibre/terrain-control", + "api-reference/maplibre/use-control", + "api-reference/maplibre/use-map", + "api-reference/maplibre/types" + ] + } ] } ] \ No newline at end of file diff --git a/docs/upgrade-guide.md b/docs/upgrade-guide.md index 232290d54..29810229f 100644 --- a/docs/upgrade-guide.md +++ b/docs/upgrade-guide.md @@ -68,13 +68,13 @@ v7 is a complete rewrite of the library. It is redesigned to be fast, lightweigh - `InteractiveMap` and `StaticMap` are removed. Instead, import `Map`. - `setRTLTextPlugin` is removed. Use the `Map` component's `RTLTextPlugin` prop (default enabled). - `MapController` is removed. v7.0 has removed its own implementation of user input handling in favor of the [native handlers](https://docs.mapbox.com/mapbox-gl-js/api/handlers/). If you are using a custom implementation of `MapController`, check if the native handlers offer options to address your application's needs. -- `MapContext` and `useMapControl` are removed. Check out the new API [useMap](./api-reference/use-map.md) and [useControl](./api-reference/use-control.md). +- `MapContext` and `useMapControl` are removed. Check out the new API [useMap](./api-reference/mapbox/use-map.md) and [useControl](./api-reference/mapbox/use-control.md). - The overlay components (`HTMLOverlay`, `CanvasOverlay` and `SVGOverlay`) are removed. Check out [this example](https://github.com/visgl/react-map-gl/tree/7.0-release/examples/custom-overlay) for implementing similar controls in your own application. - `LinearInterpolator` and `FlyToInterpolator` are removed. Use `map.easeTo()` and `map.flyTo()` instead, see [this example](https://github.com/visgl/react-map-gl/tree/7.0-release/examples/viewport-animation). ### Map -[documentation](./api-reference/map.md) +[documentation](./api-reference/mapbox/map.md) - Renamed props for better consistency with the wrapped library: + `mapboxApiAccessToken` is now `mapboxAccessToken` diff --git a/docs/whats-new.md b/docs/whats-new.md index ab79260fa..9690e30bd 100644 --- a/docs/whats-new.md +++ b/docs/whats-new.md @@ -17,7 +17,7 @@ v7 is a complete rewrite of the library. It addresses many long-standing issues - Lightweight: the ESM build size is reduced from 219k to 57k - Predictability: Components behave the same as their mapbox counterparts. Props are mapped 1:1 from the native options wherever appropriate. Almost all imperative APIs (`flyTo`, `fitBounds` etc.) can now be called directly without breaking the React binding. - Compatibility: first and third-party plugins! Directly use [mapbox-gl-draw](https://github.com/visgl/react-map-gl/tree/7.0-release/examples/draw-polygon), [mapbox-gl-geocoder](https://github.com/visgl/react-map-gl/tree/7.0-release/examples/geocoder), to name a few. -- TypeScript compliant: the code base is now entirely written in TypeScript, and all types can be [imported](./api-reference/types.md). +- TypeScript compliant: the code base is now entirely written in TypeScript, and all types can be [imported](./api-reference/mapbox/types.md). Visit the [upgrade guide](./upgrade-guide.md) if you are trying to upgrade from v5 and v6. @@ -216,7 +216,7 @@ Date: Jan 17, 2017 ## react-map-gl v1.0 * **Perspective Mode** - Now supports `bearing` and `pitch` properties, per mapbox-gl api documentation. These props default to 0 which means that maps will still be rendered in flat/ortographic mode when they are not provided -* **Support for ES6 imports** - The map overlay components (HTMLOverlay, CanvasOverlay, SVGOverlay etc) previously had to be imported via their relative source paths can now be imported directly using `import {SVGOverlay} from 'react-map-gl'. +* **Support for ES6 imports** - The map overlay components (HTMLOverlay, CanvasOverlay, SVGOverlay etc) previously had to be imported via their relative source paths can now be imported directly. ## react-map-gl v0.6