https://deck.gl/assets/js/498d4ce8.92b56734.js

1"use strict";(self.webpackChunkproject_website=self.webpackChunkproject_website||[]).push([["4423"],{41498(e,a,n){n.r(a),n.d(a,{metadata:()=>t,default:()=>m,frontMatter:()=>s,contentTitle:()=>d,toc:()=>p,assets:()=>c});var t=JSON.parse('{"id":"developer-guide/base-maps/using-with-mapbox","title":"Using with Mapbox","description":"| Pure JS | React | Overlaid | Interleaved |","source":"@site/../docs/developer-guide/base-maps/using-with-mapbox.md","sourceDirName":"developer-guide/base-maps","slug":"/developer-guide/base-maps/using-with-mapbox","permalink":"/docs/developer-guide/base-maps/using-with-mapbox","draft":false,"unlisted":false,"editUrl":"https://github.com/visgl/deck.gl/tree/master/website/../docs/developer-guide/base-maps/using-with-mapbox.md","tags":[],"version":"current","frontMatter":{},"sidebar":"tutorialSidebar","previous":{"title":"Using with Google Maps Platform","permalink":"/docs/developer-guide/base-maps/using-with-google-maps"},"next":{"title":"Using with MapLibre","permalink":"/docs/developer-guide/base-maps/using-with-maplibre"}}'),r=n(74848),o=n(28453),i=n(50773),l=n(57250);let s={},d="Using with Mapbox",c={},p=[{value:"Integration Modes",id:"integration-modes",level:2},{value:"Interleaved",id:"interleaved",level:3},{value:"Overlaid",id:"overlaid",level:3},{value:"Reverse Controlled",id:"reverse-controlled",level:3},{value:"Examples",id:"examples",level:2},{value:"Example: interleaved or overlaid",id:"example-interleaved-or-overlaid",level:3},{value:"Example: reverse controlled",id:"example-reverse-controlled",level:3},{value:"Additional Information",id:"additional-information",level:2},{value:"react-map-gl",id:"react-map-gl",level:3},{value:"Mapbox Token",id:"mapbox-token",level:3},{value:"Alternatives to Mapbox basemap sevice",id:"alternatives-to-mapbox-basemap-sevice",level:3}];function h(e){let a={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",img:"img",li:"li",p:"p",pre:"pre",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,o.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(a.header,{children:(0,r.jsx)(a.h1,{id:"using-with-mapbox",children:"Using with Mapbox"})}),"\n",(0,r.jsxs)(a.table,{children:[(0,r.jsx)(a.thead,{children:(0,r.jsxs)(a.tr,{children:[(0,r.jsx)(a.th,{children:"Pure JS"}),(0,r.jsx)(a.th,{children:"React"}),(0,r.jsx)(a.th,{children:"Overlaid"}),(0,r.jsx)(a.th,{children:"Interleaved"})]})}),(0,r.jsx)(a.tbody,{children:(0,r.jsxs)(a.tr,{children:[(0,r.jsx)(a.td,{children:"\u2713"}),(0,r.jsx)(a.td,{children:"\u2713"}),(0,r.jsx)(a.td,{children:(0,r.jsx)(a.a,{href:"https://github.com/visgl/deck.gl/tree/9.4-release/examples/get-started/pure-js/mapbox",children:"example"})}),(0,r.jsx)(a.td,{children:(0,r.jsx)(a.a,{href:"https://deck.gl/gallery/mapbox-overlay",children:"example"})})]})})]}),"\n",(0,r.jsx)(a.p,{children:(0,r.jsx)(a.img,{src:"https://raw.github.com/visgl/deck.gl-data/master/images/whats-new/mapbox-layers.jpg",alt:"deck.gl interleaved with Mapbox layers"})}),"\n",(0,r.jsxs)(a.p,{children:[(0,r.jsx)(a.a,{href:"https://github.com/mapbox/mapbox-gl-js",children:"Mapbox GL JS"})," is a popular JavaScript library from ",(0,r.jsx)(a.a,{href:"https://mapbox.com",children:"Mapbox"})," for building web map applications. deck.gl's ",(0,r.jsx)(a.code,{children:"MapView"})," can sync perfectly with the camera of Mapbox, at every zoom level and rotation angle."]}),"\n",(0,r.jsx)(a.h2,{id:"integration-modes",children:"Integration Modes"}),"\n",(0,r.jsx)(a.p,{children:"When using deck.gl and Mapbox, there are three options you can choose from: interleaved, overlaid, and reverse-controlled."}),"\n",(0,r.jsx)(a.h3,{id:"interleaved",children:"Interleaved"}),"\n",(0,r.jsxs)(a.p,{children:["The ",(0,r.jsx)(a.a,{href:"/docs/get-started/using-with-map#interleaved",children:"interleaved"})," mode renders deck.gl layers into the WebGL2 context created by Mapbox. If you need to mix deck.gl layers with Mapbox layers, e.g. having deck.gl surfaces below text labels, or objects occluding each other correctly in 3D, then you have to use this option."]}),"\n",(0,r.jsxs)(a.p,{children:["Interleaving is supported by using ",(0,r.jsx)(a.a,{href:"/docs/api-reference/mapbox/mapbox-overlay",children:"MapboxOverlay"})," with ",(0,r.jsx)(a.code,{children:"interleaved: true"}),". It requires WebGL2 and therefore only works with ",(0,r.jsx)(a.code,{children:"mapbox-gl@>2.13"}),". See ",(0,r.jsx)(a.a,{href:"../../api-reference/mapbox/overview#interleaved-renderer-compatibility",children:"compatibility"})," and ",(0,r.jsx)(a.a,{href:"/docs/api-reference/mapbox/overview#limitations",children:"limitations"}),"."]}),"\n",(0,r.jsx)(a.h3,{id:"overlaid",children:"Overlaid"}),"\n",(0,r.jsxs)(a.p,{children:["The ",(0,r.jsx)(a.a,{href:"/docs/get-started/using-with-map#overlaid",children:"overlaid"})," mode renders deck.gl in a separate canvas inside the Mapbox's controls container. If your use case does not require interleaving, but you still want to use certain features of mapbox-gl, such as mapbox-gl controls (e.g. ",(0,r.jsx)(a.code,{children:"NavigationControl"}),", ",(0,r.jsx)(a.code,{children:"Popup"}),") or plugins (e.g. ",(0,r.jsx)(a.a,{href:"https://docs.mapbox.com/mapbox-gl-js/example/mapbox-gl-directions/",children:"navigation directions"}),", ",(0,r.jsx)(a.a,{href:"https://docs.mapbox.com/mapbox-gl-js/example/mapbox-gl-draw/",children:"mapbox-gl-draw"}),"), then you should use this option."]}),"\n",(0,r.jsxs)(a.p,{children:["This is supported by using ",(0,r.jsx)(a.a,{href:"/docs/api-reference/mapbox/mapbox-overlay",children:"MapboxOverlay"})," with ",(0,r.jsx)(a.code,{children:"interleaved: false"}),"."]}

1),"\n",(0,r.jsx)(a.h3,{id:"reverse-controlled",children:"Reverse Controlled"}),"\n",(0,r.jsxs)(a.p,{children:["The reverse-controlled mode renders deck.gl above the Mapbox container and blocks any interaction to the base map. If your use case does not require interleaving, but you need to implement your own ",(0,r.jsx)(a.a,{href:"/docs/api-reference/core/controller",children:"pointer input handling"}),", have multiple maps or a map that does not fill the whole canvas (with Deck's ",(0,r.jsx)(a.a,{href:"/docs/developer-guide/views#using-multiple-views",children:"multi-view feature"}),"), you need this to allow deck.gl manage the map's size and camera."]}),"\n",(0,r.jsxs)(a.p,{children:["You cannot use mapbox-gl controls and plugins with this option. Instead, use the components from ",(0,r.jsx)(a.code,{children:"@deck.gl/widgets"}),"."]}),"\n",(0,r.jsx)(a.h2,{id:"examples",children:"Examples"}),"\n",(0,r.jsx)(a.h3,{id:"example-interleaved-or-overlaid",children:"Example: interleaved or overlaid"}),"\n",(0,r.jsxs)(a.p,{children:["Both the interleaved and the overlaid options are supported in by the ",(0,r.jsx)(a.a,{href:"/docs/api-reference/mapbox/overview",children:"@deck.gl/mapbox"})," module. This is recommended approach for developers coming from the Mapbox ecosystem, as it can easily switch between interleaved and overlaid rendering, as well as being compatible with other Mapbox controls and plugins."]}),"\n","\n",(0,r.jsxs)(i.A,{groupId:"language",children:[(0,r.jsx)(l.A,{value:"ts",label:"TypeScript",children:(0,r.jsx)(a.pre,{children:(0,r.jsx)(a.code,{className:"language-ts",children:"import {MapboxOverlay} from '@deck.gl/mapbox';\nimport {ScatterplotLayer} from '@deck.gl/layers';\nimport mapboxgl from 'mapbox-gl';\nimport 'mapbox-gl/dist/mapbox-gl.css';\n\nconst map = new mapboxgl.Map({\n  container: 'map',\n  style: 'mapbox://styles/mapbox/light-v9',\n  accessToken: '<mapbox_access_token>',\n  center: [0.45, 51.47],\n  zoom: 11\n});\n\nmap.once('load', () => {\n  const deckOverlay = new MapboxOverlay({\n    interleaved: true,\n    layers: [\n      new ScatterplotLayer({\n        id: 'deckgl-circle',\n        data: [\n          {position: [0.45, 51.47]}\n        ],\n        getPosition: d => d.position,\n        getFillColor: [255, 0, 0, 100],\n        getRadius: 1000,\n        beforeId: 'waterway-label' // In interleaved mode render the layer under map labels\n      })\n    ]\n  });\n\n  map.addControl(deckOverlay);\n});\n"})})}),(0,r.jsx)(l.A,{value:"react",label:"React",children:(0,r.jsx)(a.pre,{children:(0,r.jsx)(a.code,{className:"language-tsx",children:"import React from 'react';\nimport {Map, useControl} from 'react-map-gl/mapbox';\nimport {MapboxOverlay} from '@deck.gl/mapbox';\nimport {DeckProps} from '@deck.gl/core';\nimport {ScatterplotLayer} from '@deck.gl/layers';\nimport 'mapbox-gl/dist/mapbox-gl.css';

1\n\nfunction DeckGLOverlay(props: DeckProps) {\n  const overlay = useControl<MapboxOverlay>(() => new MapboxOverlay(props));\n  overlay.setProps(props);\n  return null;\n}\n\nfunction App() {\n  const layers: [\n    new ScatterplotLayer({\n      id: 'deckgl-circle',\n      data: [\n        {position: [0.45, 51.47]}\n      ],\n      getPosition: d => d.position,\n      getFillColor: [255, 0, 0, 100],\n      getRadius: 1000,\n      beforeId: 'waterway-label' // In interleaved mode render the layer under map labels\n    })\n  ];\n\n  return (\n    <Map\n      initialViewState={{\n        longitude: 0.45,\n        latitude: 51.47,\n        zoom: 11\n      }}\n      mapStyle=\"mapbox://styles/mapbox/light-v9\"\n      mapboxAccessToken=\"<mapbox_access_token>\"\n    >\n      <DeckGLOverlay layers={layers} interleaved />\n    </Map>\n  );\n}\n"})})})]}),"\n",(0,r.jsxs)(a.p,{children:["You can find full project setups in the ",(0,r.jsx)(a.a,{href:"https://github.com/visgl/deck.gl/tree/9.4-release/examples/get-started/react/mapbox/",children:"react get-started example"})," and ",(0,r.jsx)(a.a,{href:"https://github.com/visgl/deck.gl/tree/9.4-release/examples/get-started/pure-js/mapbox/",children:"pure js get-started example"}),"."]}),"\n",(0,r.jsx)(a.h3,{id:"example-reverse-controlled",children:"Example: reverse controlled"}),"\n",(0,r.jsxs)(a.p,{children:["The reverse-controlled option is supported by the pre-built scripting bundle, and in React when used with the ",(0,r.jsx)(a.code,{children:"react-map-gl"})," library. There is currently no easy way to do it under Vanilla JS."]}),"\n",(0,r.jsxs)(i.A,{groupId:"language",children:[(0,r.jsx)(l.A,{value:"scripting",label:"Scripting",children:(0,r.jsx)(a.pre,{children:(0,r.jsx)(a.code,{className:"language-js",children:'<script src="https://unpkg.com/deck.gl@^9.0.0/dist.min.js"><\/script>\n<script src="https://api.mapbox.com/mapbox-gl-js/v3.2.0/mapbox-gl.js"><\/script>\n<link href="https://api.mapbox.com/mapbox-gl-js/v3.2.0/mapbox-gl.css" rel="stylesheet" />\n<script type="text/javascript">\n  const {DeckGL, ScatterplotLayer} = deck;\n\n  mapboxgl.accessToken = \'<mapbox_access_token>\';\n\n  new DeckGL({\n    mapStyle: \'mapbox://styles/mapbox/light-v9\',\n    initialViewState: {\n      longitude: 0.45,\n      latitude: 51.47,\n      zoom: 11\n    },\n    controller: true,\n    layers: [\n      new ScatterplotLayer({\n        id: \'deckgl-circle\',\n        data: [\n          {position: [0.45, 51.47]}\n        ],\n        getPosition: d => d.position,\n        getFillColor: [255, 0, 0, 100],\n        getRadius: 1000\n      })\n    ]\n  });\n<\/script>\n'})})}),(0,r.jsx)(l.A,{value:"react",label:"React",children:(0,r.jsx)(a.pre,{children:(0,r.jsx)(a.code,{className:"language-tsx",children:"import React from 'react';\nimport {Map} from 'react-map-gl/mapbox';\nimport {DeckGL} from '@deck.gl/react';\nimport {ScatterplotLayer} from '@deck.gl/layers';\nimport 'mapbox-gl/dist/mapbox-gl.css';\n\nfunction App() {\n  const layers: [\n    new ScatterplotLayer({\n      id: 'deckgl-circle',\n      data: [\n        {position: [0.45, 51.47]}\n      ],\n      getPosition: d => d.position,\n      getFillColor: [255, 0, 0, 100],\n      getRadius: 1000,\n    })\n  ];\n\n  return (\n    <DeckGL\n      initialViewState={{\n        longitude: 0.45,\n        latitude: 51.47,\n        zoom: 11\n      }}\n      controller\n      layers={layers}\n    >\n      <Map\n        mapStyle=\"mapbox://styles/mapbox/light-v9\"\n        mapboxAccessToken=\"<mapbox_access_token>\"\n      />\n    </DeckGL>\n  );\n}\n"})})})]}),"\n",(0,r.jsx)(a.h2,{id:"additional-information",children:"Additional Information"}),"\n",(0,r.jsx)(a.h3,{id:"react-map-gl",children:"react-map-gl"}),"\n",(0,r.jsxs)(a.p,{children:[(0,r.jsx)(a.a,{href:"https://github.com/visgl/react-map-gl",children:"react-map-gl"})," is a React wrapper around mapbox-gl maintained by the vis.gl community. If you'd like to use deck.gl together with mapbox-gl and React, this library is the recommended companion."]}),"\n",(0,r.jsxs)(a.p,{children:["All the ",(0,r.jsx)(a.a,{href:"https://github.com/visgl/deck.gl/tree/9.4-release/examples/website",children:"examples on this website"})," are implemented using the React integration."]}),"\n",(0,r.jsxs)(a.p,{children:["When you choose the interleaved or overlaid option, the react-map-gl ",(0,r.jsx)(a.a,{href:"https://visgl.github.io/react-map-gl/docs/api-reference/map",children:"Map"})," React component acts as the root component, and ",(0,r.jsx)(a.a,{href:"../../api-reference/mapbox/mapbox-overlay#example",children:"MapboxOverlay"})," is used with react-map-gl's ",(0,r.jsx)(a.code,{children:"useControl"})," hook."]}),"\n",(0,r.jsxs)(a.p,{children:["When you choose the reverse-controlled option, the ",(0,r.jsx)(a.code,{children:"DeckGL"})," React component acts as the root component, and the react-map-gl ",(0,r.jsx)(a.a,{href:"https://visgl.github.io/react-map-gl/docs/api-reference/map",children:"Map"})," is a child. In this case, ",(0,r.jsx)(a.code,{children:"Map"})," will automatically interpret the deck.gl view state (i.e. latitude, longitude, zoom etc), so that deck.gl layers will render as a synchronized geospatial overlay over the underlying map."]}),"\n",(0,r.jsx)(a.h3,{id:"mapbox-token",children:"Mapbox Token"}),"\n",(0,r.jsxs)(a.p,{children:["To use Mapbox, you will need to register on their website in order to retrieve an ",(0,r.jsx)(a.a,{href:"https://docs.mapbox.com/help/how-mapbox-works/access-tokens/",children:"access token"})," required by the map component, which will be used to identify you and start serving up map tiles. The service will be free until a ",(0,r.jsx)(a.a,{href:"https://www.mapbox.com/pricing/",children:"certain level"})," of traffic is exceeded."]}),"\n",(0,r.jsxs)(a.p,{children:["If you are using mapbox-gl without React, check out ",(0,r.jsx)(a.a,{href:"https://docs.mapbox.com/mapbox-gl-js/api/#accesstoken",children:"Mapbox GL JS API"})," for how to apply the token."]}),"\n",(0,r.jsx)(a.p,{children:"If you are using react-map-gl, there are several ways to provide a token to your app:"}),"\n",(0,r.jsxs)(a.ul,{children:["\n",(0,r.jsxs)(a.li,{children:["Set the ",(0,r.jsx)(a.code,{children:"MapboxAccessToken"})," environment variable. You may need to add additional set up to the bundler (",(0,r.jsx)(a.a,{href:"https://webpack.js.org/plugins/environment-plugin/",children:"example"}),") so that ",(0,r.jsx)(a.code,{children:"process.env.MapboxAccessToken"})," is accessible at runtime."]}),"\n",(0,r.jsxs)(a.li,{children:["Provide it in the URL, e.g ",(0,r.jsx)(a.code,{children:"?access_token=TOKEN"})]}),"\n",(0,r.jsxs)(a.li,{children:["Pass it as a prop to the react-map-gl ",(0,r.jsx)(a.code,{children:"Map"})," component ",(0,r.jsx)(a.code,{children:"<Map mapboxAccessToken={TOKEN} />"})]}),"\n"]}),"\n",(0,r.jsx)(a.h3,{id:"alternatives-to-mapbox-basemap-sevice",children:"Alternatives to Mapbox basemap sevice"}),"\n",(0,r.jsxs)(a.p,{children:["As of v2.0, Mapbox GL JS ",(0,r.jsx)(a.a,{href:"https://github.com/mapbox/mapbox-gl-js/blob/main/CHANGELOG.md#200",children:"went proprietary"})," and requires a Mapbox account to use even if you don't load tiles from the Mapbox server. If you do not wish to use the Mapbox service, you may also consider:"]}),"\n",(0,r.jsxs)(a.ul,{children:["\n",(0,r.jsx)(a.li,{children:"mapbox-gl v1.13, the last release before the license change. Interleaving is not supported by this version."}),"\n",(0,r.jsxs)(a.li,{children:[(0,r.jsx)(a.a,{href:"https://maplibre.org",children:"MapLibre GL JS"}),", a community-supported WebGL map library. maplibre-gl can generally be used as a drop-in replacement of mapbox-gl, with some of its own features and APIs. More information can be found in ",(0,r.jsx)(a.a,{href:"/docs/developer-guide/base-maps/using-with-maplibre",children:"using with MapLibre"}),"."]}),"\n"]})]})}function m(e={}){let{wrapper:a}={...(0,o.R)(),...e.components};return a?(0,r.jsx)(a,{...e,children:(0,r.jsx)(h,{...e})}):h(e)}}}]);
2//# sourceMappingURL=498d4ce8.92b56734.js.map