react-three-map
is a bridge to use react-three-fiber
inside react-map-gl
.
Until now you had:
imperative | declarative (react) |
---|---|
Maplibre/Mapbox | react-map-gl |
THREE.js | react-three-fiber |
Now with react-three-map
, you can use them together π€βπ€.
npm install react-three-map
Check out our examples here (powered by Ladle).
Let's build the same react-three-fiber basic example, but now it can be inside a map. (live demo). |
- Import
Canvas
fromreact-three-map
instead of@react-three/fiber
. - Give it a latitude and longitude so it knows where to position the scene in the map.
- Everything else should work just as usual.
import "maplibre-gl/dist/maplibre-gl.css"
import { createRoot } from 'react-dom/client'
import React, { useRef, useState } from 'react'
import { useFrame } from "@react-three/fiber"
import { useRef, useState } from "react"
import Map from "react-map-gl/maplibre"
import { Canvas } from "react-three-map/maplibre"
// import { Canvas } from "react-three-map" // if you are using MapBox
function BasicExample() {
return <Map
antialias
initialViewState={{
latitude: 51,
longitude: 0,
zoom: 13,
pitch: 60
}}
mapStyle="https://basemaps.cartocdn.com/gl/positron-gl-style/style.json"
>
<Canvas latitude={51} longitude={0}>
<hemisphereLight
args={["#ffffff", "#60666C"]}
position={[1, 4.5, 3]}
/>
<object3D scale={500}>
<Box position={[-1.2, 1, 0]} />
<Box position={[1.2, 1, 0]} />
</object3D>
</Canvas>
</Map>
}
Look how complex is to add just one ThreeJS object to a map.
Look how complex is to create your custom root for R3F.
You can now replace all that complexity and hundreds of lines of code with the <Canvas>
component exported by react-three-map
, which includes a tone of extra features and seamless integration, supporting pointer events, raycasting, and much more, all out of the box.
Same as in @react-three/fiber
, the <Canvas>
object is where you start to define your React Three Fiber Scene.
import "maplibre-gl/dist/maplibre-gl.css"
import Map from "react-map-gl/maplibre"
import { Canvas } from 'react-three-map/maplibre'
// import { Canvas } from "react-three-map" // if you are using MapBox
const App = () => (
<Map
initialViewState={{ latitude: 51, longitude: 0, zoom: 13 }}
mapStyle="https://basemaps.cartocdn.com/gl/positron-gl-style/style.json" >
<Canvas latitude={51} longitude={0}>
<pointLight position={[10, 10, 10]} />
<mesh>
<sphereGeometry />
<meshStandardMaterial color="hotpink" />
</mesh>
</Canvas>
</Map>
)
It shares most of the props from R3F <Canvas>
, so you can check them directly in the @react-three/fiber
docs. There are a few important exceptions though, which are mentioned bellow.
Prop | Description | Default |
---|---|---|
latitude | The latitude coordinate where to add the scene. | |
longitude | The longitude coordinate where to add the scene. | |
altitude | The altitude coordinate where to add the scene. | 0 |
frameloop | Render mode: "always" , "demand" . |
"always" |
overlay | Render on a separated canvas. | false |
About overlay
You may want to use overlay
if:
- You use
react-postprocessing
and have issues clearing the screen. - Want to avoid unnecesary map renders when only the Three scene changed.
But it comes with some caveats:
- ThreeJS will always render on top, as this is now a separated canvas and doesn't have access to the map depth buffer.
react-postprocessing
will also not work if you also use<Coordinates>
components.
Because the scene now lives in a map, we leave a lot of the render and camera control to the map, rather than to R3F.
Therefore, the following <Canvas>
props are ignored:
- gl
- camera
- resize
- orthographic
- dpr
This component allows you to have 3D objects at different coordinates.
import { Canvas, Coordinates } from 'react-three-map'
<Canvas latitude={51} longitude={0}>
<Coordinates latitude={50} longitude={0}>
<mesh><sphereGeometry /></mesh>
</Coordinates>
<Coordinates latitude={52} longitude={0}>
<mesh><sphereGeometry /></mesh>
</Coordinates>
</Canvas>
Props | Description | Default |
---|---|---|
latitude | The latitude coordinate where to add the scene. | |
longitude | The longitude coordinate where to add the scene. | |
altitude | The altitude coordinate where to add the scene. | 0 |
Same as Coordinates
, but scale is ignored in exchange of being able to be rendered under the same scene.
Works well at city level distances, but since scale remains unchanged, is not recommended at country level distances.
Check the story to see the difference between the two or check #102 for more info.
Access the map from inside react-three-map
.
import { useMap } from "react-three-map";
// import { useMap } from "react-three-map/maplibre"; if you use maplibre
const Component = () => {
const map = useMap();
return <>...</>
}
This utility function converts geographic coordinates into a Vector3Tuple
, which represents a 3D vector in meters.
Similar to NearCoordinates
, remember that this only updates positions (translation) but that scale is not taken into account, which has an important factor at very long distances (country level).
Parameter | Description |
---|---|
point: Coords |
The geographic coordinates of the point to convert. |
origin: Coords |
The geographic coordinates used as the origin for calculations. |
Returns a Vector3Tuple
representing the 3D position of the point relative to the origin.
This utility function converts a Vector3Tuple
, which represents a 3D vector in meters, back into geographic coordinates.
It is the inverse of coordsToVector3
but it does not have a good level of precision at long distances since we haven't reverse engineered #102 fix yet.
Recommended to use at city level distances, but margin errors will be noticeable at country level distances.
Parameter | Description |
---|---|
position: Vector3Tuple |
The 3D vector to convert back into geographic coordinates. |
origin: Coords |
The geographic coordinates used as the origin for calculations. |
Returns a Coords
object representing the geographic coordinates of the point relative to the origin.