mirror of
https://github.com/visgl/react-map-gl.git
synced 2026-01-18 15:54:22 +00:00
124 lines
70 KiB
HTML
124 lines
70 KiB
HTML
<!DOCTYPE html><html><head><meta charSet="utf-8"/><meta http-equiv="x-ua-compatible" content="ie=edge"/><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"/><meta name="generator" content="Gatsby 2.32.0"/><title data-react-helmet="true">react-map-gl | Upgrade Guide</title><link data-react-helmet="true" rel="stylesheet" href="https://api.tiles.mapbox.com/mapbox-gl-js/v2.6.1/mapbox-gl.css" type="text/css"/><link data-react-helmet="true" rel="stylesheet" href="https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-draw/v1.3.0/mapbox-gl-draw.css" type="text/css"/><link data-react-helmet="true" rel="stylesheet" href="https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v4.7.2/mapbox-gl-geocoder.css" type="text/css"/><link data-react-helmet="true" rel="stylesheet" href="/react-map-gl/style.css" type="text/css"/><link data-react-helmet="true" rel="icon" type="img/ico" href="favicon.ico"/><meta data-react-helmet="true" name="description" content="React wrapper for Mapbox GL JS"/><meta data-react-helmet="true" name="image" content="https://github.com/visgl/images/hero-sm.jpg"/><meta data-react-helmet="true" property="og:url" content="https://github.com/visgl/*"/><meta data-react-helmet="true" property="og:type" content="article"/><meta data-react-helmet="true" property="og:title" content="react-map-gl | Upgrade Guide"/><meta data-react-helmet="true" property="og:description" content="React wrapper for Mapbox GL JS"/><meta data-react-helmet="true" property="og:image" content="https://github.com/visgl/images/hero-sm.jpg"/><meta data-react-helmet="true" property="fb:app_id" content=""/><meta data-react-helmet="true" name="twitter:card" content="summary_large_image"/><meta data-react-helmet="true" name="twitter:creator" content=""/><meta data-react-helmet="true" name="twitter:title" content="react-map-gl | Upgrade Guide"/><meta data-react-helmet="true" name="twitter:description" content="React wrapper for Mapbox GL JS"/><meta data-react-helmet="true" name="twitter:image" content="https://github.com/visgl/images/hero-sm.jpg"/><script data-react-helmet="true" type="application/ld+json">[{"@context":"http://schema.org","@type":"WebSite","url":"https://github.com/visgl","name":"react-map-gl"},[{"@context":"http://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"https://github.com/visgl/*","name":"react-map-gl | Upgrade Guide","image":"https://github.com/visgl/images/hero-sm.jpg"}}]},{"@context":"http://schema.org","@type":"BlogPosting","url":"https://github.com/visgl","name":"react-map-gl | Upgrade Guide","headline":"react-map-gl | Upgrade Guide","image":{"@type":"ImageObject","url":"https://github.com/visgl/images/hero-sm.jpg"},"description":"React wrapper for Mapbox GL JS"}]]</script><script data-react-helmet="true" async="" src="https://www.googletagmanager.com/gtag/js?id=UA-74374017-2"></script><style data-styled="ckjqBY kTxBVF hLObhf jcCSEG bdPEit dkfbFn ljEIIX isdBno cqPqff cpyGKT FcGip cowmvG eYbFBV idNLwm iTIrjR dMTgn dvhuEd jYCwIr cncNYa hAWDlt egvBsN ePRhQs hsOfQe kVRSNy dMoEUD fPGooQ dMIfYV bnjLCb kXxWox kxRoVr" data-styled-version="4.4.1">
|
|
/* sc-component-id: body__BodyContainerToC-lvm4v2-1 */
|
|
.idNLwm{height:100%;width:100%;padding:64px 0 0 300px;} @media screen and (max-width:768px){.idNLwm{height:calc(100vh - 64px);padding:0;-webkit-order:2;-ms-flex-order:2;order:2;}}
|
|
/* sc-component-id: body__Body-lvm4v2-3 */
|
|
.ckjqBY{font:normal 14px/20px UberMove,Helvetica,Arial,sans-serif;width:100vw;height:100vh;}
|
|
/* sc-component-id: toc__TocChevron-c2gnov-0 */
|
|
.ljEIIX{height:16px;width:16px;position:absolute;left:24px;top:20px;-webkit-transform:none;-ms-transform:none;transform:none;-webkit-transition:-webkit-transform 0.3s;-webkit-transition:transform 0.3s;transition:transform 0.3s;}.isdBno{height:16px;width:16px;position:absolute;left:24px;top:20px;-webkit-transform:rotate(-90deg);-ms-transform:rotate(-90deg);transform:rotate(-90deg);-webkit-transition:-webkit-transform 0.3s;-webkit-transition:transform 0.3s;transition:transform 0.3s;}
|
|
/* sc-component-id: toc__TocEntry-c2gnov-1 */
|
|
.jcCSEG{font:bold 14px/20px UberMove,Helvetica,Arial,sans-serif;border-top:1px solid tranparent;color:#101918;cursor:pointer;margin:-0.5px 0;position:relative;white-space:nowrap;text-overflow:ellipsis;overflow:hidden;}.bdPEit{font:bold 14px/20px UberMove,Helvetica,Arial,sans-serif;border-top:1px solid tranparent;color:#486865;cursor:pointer;margin:-0.5px 0;position:relative;white-space:nowrap;text-overflow:ellipsis;overflow:hidden;}.dkfbFn{font:bold 14px/20px UberMove,Helvetica,Arial,sans-serif;border-top:1px solid #e1f0ee;color:#101918;cursor:pointer;margin:-0.5px 0;position:relative;white-space:nowrap;text-overflow:ellipsis;overflow:hidden;}
|
|
/* sc-component-id: toc__TocHeader-c2gnov-2 */
|
|
.cqPqff{display:block;padding:16px 16px 16px 48px;} .cqPqff:hover{background:#f7fcfb;}
|
|
/* sc-component-id: toc__TocLink-c2gnov-3 */
|
|
.cowmvG a{display:block;padding:16px 16px 16px 60px;color:#486865 !important;-webkit-text-decoration:none;text-decoration:none;} .cowmvG:hover{background:#f7fcfb;}.eYbFBV a{display:block;padding:16px 16px 16px 60px;color:#00ADE6 !important;-webkit-text-decoration:none;text-decoration:none;} .eYbFBV:hover{background:#f7fcfb;}
|
|
/* sc-component-id: toc__TocSubpages-c2gnov-4 */
|
|
.cpyGKT{list-style:none;margin:0;max-height:224px;overflow:hidden;padding:0;-webkit-transition:max-height 0.3s;transition:max-height 0.3s;}.FcGip{list-style:none;margin:0;max-height:0px;overflow:hidden;padding:0;-webkit-transition:max-height 0.3s;transition:max-height 0.3s;}
|
|
/* sc-component-id: toc__TocContainer-c2gnov-5 */
|
|
.hLObhf{position:fixed;top:0;padding:64px 0;max-width:300px;height:100%;z-index:2;border-right:1px solid #cae0dc;overflow-y:auto;overflow-x:hidden;width:100%;} @media screen and (max-width:768px){.hLObhf{max-width:100%;height:initial;border-right:none;position:-webkit-sticky;position:sticky;padding:0;-webkit-transition:opacity 0.3s,-webkit-transform 0.3s;-webkit-transition:opacity 0.3s,transform 0.3s;transition:opacity 0.3s,transform 0.3s;opacity:0;max-height:0;overflow:hidden;-webkit-transform:translateY(30px);-ms-transform:translateY(30px);transform:translateY(30px);}}
|
|
/* sc-component-id: header__HeaderContainer-sc-3r2dxq-1 */
|
|
.kTxBVF{grid-column:1/3;grid-row:1/2;} @media screen and (max-width:768px){.kTxBVF{-webkit-order:1;-ms-flex-order:1;order:1;}}
|
|
/* sc-component-id: sc-global-3868639009 */
|
|
body{margin:0;overflow-x:hidden;-webkit-text-size-adjust:100%;} *{box-sizing:border-box;}
|
|
/* sc-component-id: typography__A-sc-1pmaksm-0 */
|
|
.dvhuEd{-webkit-text-decoration:none;text-decoration:none;color:#00ADE6;} .dvhuEd:visited{color:#174EB6;} .dvhuEd:active{color:#123D90;} .dvhuEd:hover{color:#123D90;}
|
|
/* sc-component-id: typography__GatsbyA-sc-1pmaksm-1 */
|
|
.dMoEUD{-webkit-text-decoration:none;text-decoration:none;color:#00ADE6;} .dMoEUD:visited{color:#174EB6;} .dMoEUD:active{color:#123D90;} .dMoEUD:hover{color:#123D90;}
|
|
/* sc-component-id: typography__H1-sc-1pmaksm-2 */
|
|
.dMTgn{font:bold 40px/56px UberMove,Helvetica,Arial,sans-serif;-webkit-letter-spacing:0.02em;-moz-letter-spacing:0.02em;-ms-letter-spacing:0.02em;letter-spacing:0.02em;margin:4px 0 24px;}
|
|
/* sc-component-id: typography__H2-sc-1pmaksm-3 */
|
|
.jYCwIr{font:bold 32px/48px UberMove,Helvetica,Arial,sans-serif;margin:24px 0 16px;}
|
|
/* sc-component-id: typography__H3-sc-1pmaksm-4 */
|
|
.ePRhQs{font:bold 24px/36px UberMove,Helvetica,Arial,sans-serif;}
|
|
/* sc-component-id: typography__H4-sc-1pmaksm-5 */
|
|
.dMIfYV{font:bold 20px/28px UberMove,Helvetica,Arial,sans-serif;}
|
|
/* sc-component-id: typography__P-sc-1pmaksm-8 */
|
|
.cncNYa{margin:'0 0 16px';}
|
|
/* sc-component-id: typography__List-sc-1pmaksm-9 */
|
|
.hsOfQe{margin:0 0 12px;}
|
|
/* sc-component-id: typography__ListItem-sc-1pmaksm-10 */
|
|
.kVRSNy{margin-bottom:4px;}
|
|
/* sc-component-id: typography__MarkdownBody-sc-1pmaksm-11 */
|
|
.iTIrjR{font:normal 14px/20px UberMove,Helvetica,Arial,sans-serif;padding:36px;max-width:692px;}
|
|
/* sc-component-id: typography__InlineCode-sc-1pmaksm-12 */
|
|
.egvBsN{background-color:#f7fcfb;border-radius:4px;padding:0 5px;font-family:Consolas,Menlo,Monaco,'Andale Mono WT','Andale Mono','Lucida Console','Lucida Sans Typewriter','DejaVu Sans Mono','Bitstream Vera Sans Mono','Liberation Mono','Nimbus Mono L','Courier New',Courier,monospace;font-size:0.9em;margin:1px 0;line-height:calc(1.5em / 0.9 - 2px);display:inline-block;vertical-align:top;}
|
|
/* sc-component-id: typography__Pre-sc-1pmaksm-14 */
|
|
.fPGooQ{font-size:14px;background-color:#f7fcfb;padding:6px;overflow-x:auto;} .fPGooQ .token.comment,.fPGooQ .token.prolog,.fPGooQ .token.doctype,.fPGooQ .token.cdata{color:slategray;} .fPGooQ .token.punctuation{color:#999;} .fPGooQ .token.namespace{opacity:.7;} .fPGooQ .token.property,.fPGooQ .token.tag,.fPGooQ .token.boolean,.fPGooQ .token.number,.fPGooQ .token.constant,.fPGooQ .token.symbol,.fPGooQ .token.deleted{color:#905;} .fPGooQ .token.selector,.fPGooQ .token.attr-name,.fPGooQ .token.string,.fPGooQ .token.char,.fPGooQ .token.builtin,.fPGooQ .token.inserted{color:#690;} .fPGooQ .token.operator,.fPGooQ .token.entity,.fPGooQ .token.url,.fPGooQ .language-css .token.string,.fPGooQ .style .token.string{color:#9a6e3a;background:hsla(0,0%,100%,.5);} .fPGooQ .token.atrule,.fPGooQ .token.attr-value,.fPGooQ .token.keyword{color:#07a;} .fPGooQ .token.function,.fPGooQ .token.class-name{color:#DD4A68;} .fPGooQ .token.regex,.fPGooQ .token.important,.fPGooQ .token.variable{color:#e90;} .fPGooQ .token.important,.fPGooQ .token.bold{font-weight:bold;} .fPGooQ .token.italic{font-style:italic;} .fPGooQ .token.entity{cursor:help;}
|
|
/* sc-component-id: typography__BlockQuote-sc-1pmaksm-16 */
|
|
.hAWDlt{background-color:#FBE2CF;margin-inline-start:0;margin-inline-end:0;padding:10px 16px;}
|
|
/* sc-component-id: typography__Table-sc-1pmaksm-17 */
|
|
.bnjLCb{border-collapse:collapse;border-spacing:1px;width:100%;}
|
|
/* sc-component-id: typography__TableHeaderCell-sc-1pmaksm-18 */
|
|
.kXxWox{padding:4px;text-align:left;background:#f7fcfb;font-weight:bold;border:1px solid #e1f0ee;}
|
|
/* sc-component-id: typography__TableBodyCell-sc-1pmaksm-19 */
|
|
.kxRoVr{padding:4px;text-align:left;border:1px solid #e1f0ee;}</style><style type="text/css">
|
|
.anchor.before {
|
|
position: absolute;
|
|
top: 0;
|
|
left: 0;
|
|
transform: translateX(-100%);
|
|
padding-right: 4px;
|
|
}
|
|
.anchor.after {
|
|
display: inline-block;
|
|
padding-left: 4px;
|
|
}
|
|
h1 .anchor svg,
|
|
h2 .anchor svg,
|
|
h3 .anchor svg,
|
|
h4 .anchor svg,
|
|
h5 .anchor svg,
|
|
h6 .anchor svg {
|
|
visibility: hidden;
|
|
}
|
|
h1:hover .anchor svg,
|
|
h2:hover .anchor svg,
|
|
h3:hover .anchor svg,
|
|
h4:hover .anchor svg,
|
|
h5:hover .anchor svg,
|
|
h6:hover .anchor svg,
|
|
h1 .anchor:focus svg,
|
|
h2 .anchor:focus svg,
|
|
h3 .anchor:focus svg,
|
|
h4 .anchor:focus svg,
|
|
h5 .anchor:focus svg,
|
|
h6 .anchor:focus svg {
|
|
visibility: visible;
|
|
}
|
|
</style><script>
|
|
document.addEventListener("DOMContentLoaded", function(event) {
|
|
var hash = window.decodeURI(location.hash.replace('#', ''))
|
|
if (hash !== '') {
|
|
var element = document.getElementById(hash)
|
|
if (element) {
|
|
var scrollTop = window.pageYOffset || document.documentElement.scrollTop || document.body.scrollTop
|
|
var clientTop = document.documentElement.clientTop || document.body.clientTop || 0
|
|
var offset = element.getBoundingClientRect().top + scrollTop - clientTop
|
|
// Wait for the browser to finish rendering before scrolling.
|
|
setTimeout((function() {
|
|
window.scrollTo(0, offset - 64)
|
|
}), 0)
|
|
}
|
|
}
|
|
})
|
|
</script><link as="script" rel="preload" href="/react-map-gl/webpack-runtime-53e1d5786ef6c6593773.js"/><link as="script" rel="preload" href="/react-map-gl/framework-47a7447cd78cae046a8b.js"/><link as="script" rel="preload" href="/react-map-gl/app-c33704d3a1abd6ea3046.js"/><link as="script" rel="preload" href="/react-map-gl/component---node-modules-gatsby-theme-ocular-src-react-templates-documentation-jsx-298d6a55a92e5d120c0e.js"/><link as="fetch" rel="preload" href="/react-map-gl/page-data/docs/upgrade-guide/page-data.json" crossorigin="anonymous"/><link as="fetch" rel="preload" href="/react-map-gl/page-data/sq/d/484347790.json" crossorigin="anonymous"/><link as="fetch" rel="preload" href="/react-map-gl/page-data/app-data.json" crossorigin="anonymous"/></head><body><div id="___gatsby"><div style="outline:none" tabindex="-1" id="gatsby-focus-wrapper"><div><div class="body__Body-lvm4v2-3 ckjqBY"><div class="header__HeaderContainer-sc-3r2dxq-1 kTxBVF"><div></div></div><div class="toc__TocContainer-c2gnov-5 hLObhf"><div><div title="Introduction" class="toc__TocEntry-c2gnov-1 jcCSEG"><svg viewBox="0 0 24 24" class="toc__TocChevron-c2gnov-0 ljEIIX" width="24" height="24"><title>Chevron Down</title><path transform="rotate(270, 12, 12)" fill-rule="evenodd" clip-rule="evenodd" d="M9 12C9 12.2652 9.10536 12.5196 9.29289 12.7071L13.2929 16.7071C13.6834 17.0976 14.3166 17.0976 14.7071 16.7071C15.0976 16.3166 15.0976 15.6834 14.7071 15.2929L11.4142 12L14.7071 8.70711C15.0976 8.31658 15.0976 7.68342 14.7071 7.29289C14.3166 6.90237 13.6834 6.90237 13.2929 7.29289L9.29289 11.2929C9.10536 11.4804 9 11.7348 9 12Z"></path></svg><span class="toc__TocHeader-c2gnov-2 cqPqff">Introduction</span></div><ul class="toc__TocSubpages-c2gnov-4 cpyGKT"><div><li><div title="Introduction" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="Introduction" href="/react-map-gl/docs">Introduction</a></div></div></li></div><div><li><div title="What's new" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="What's new" href="/react-map-gl/docs/whats-new">What's new</a></div></div></li></div><div><li><div title="Upgrade Guide" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 eYbFBV"><a aria-current="page" title="Upgrade Guide" class="" href="/react-map-gl/docs/upgrade-guide">Upgrade Guide</a></div></div></li></div><div><li><div title="Contributing to react-map-gl" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="Contributing to react-map-gl" href="/react-map-gl/docs/contributing">Contributing to react-map-gl</a></div></div></li></div></ul></div><div><div title="Developer Guide" class="toc__TocEntry-c2gnov-1 dkfbFn"><svg viewBox="0 0 24 24" class="toc__TocChevron-c2gnov-0 isdBno" width="24" height="24"><title>Chevron Down</title><path transform="rotate(270, 12, 12)" fill-rule="evenodd" clip-rule="evenodd" d="M9 12C9 12.2652 9.10536 12.5196 9.29289 12.7071L13.2929 16.7071C13.6834 17.0976 14.3166 17.0976 14.7071 16.7071C15.0976 16.3166 15.0976 15.6834 14.7071 15.2929L11.4142 12L14.7071 8.70711C15.0976 8.31658 15.0976 7.68342 14.7071 7.29289C14.3166 6.90237 13.6834 6.90237 13.2929 7.29289L9.29289 11.2929C9.10536 11.4804 9 11.7348 9 12Z"></path></svg><span class="toc__TocHeader-c2gnov-2 cqPqff">Developer Guide</span></div><ul class="toc__TocSubpages-c2gnov-4 FcGip"><div><li><div title="Get Started" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="Get Started" href="/react-map-gl/docs/get-started/get-started">Get Started</a></div></div></li></div><div><li><div title="About Mapbox Tokens" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="About Mapbox Tokens" href="/react-map-gl/docs/get-started/mapbox-tokens">About Mapbox Tokens</a></div></div></li></div><div><li><div title="State Management" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="State Management" href="/react-map-gl/docs/get-started/state-management">State Management</a></div></div></li></div><div><li><div title="Adding Custom Data" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="Adding Custom Data" href="/react-map-gl/docs/get-started/adding-custom-data">Adding Custom Data</a></div></div></li></div><div><li><div title="Tips and Tricks" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="Tips and Tricks" href="/react-map-gl/docs/get-started/tips-and-tricks">Tips and Tricks</a></div></div></li></div></ul></div><div><div title="API Reference" class="toc__TocEntry-c2gnov-1 dkfbFn"><svg viewBox="0 0 24 24" class="toc__TocChevron-c2gnov-0 isdBno" width="24" height="24"><title>Chevron Down</title><path transform="rotate(270, 12, 12)" fill-rule="evenodd" clip-rule="evenodd" d="M9 12C9 12.2652 9.10536 12.5196 9.29289 12.7071L13.2929 16.7071C13.6834 17.0976 14.3166 17.0976 14.7071 16.7071C15.0976 16.3166 15.0976 15.6834 14.7071 15.2929L11.4142 12L14.7071 8.70711C15.0976 8.31658 15.0976 7.68342 14.7071 7.29289C14.3166 6.90237 13.6834 6.90237 13.2929 7.29289L9.29289 11.2929C9.10536 11.4804 9 11.7348 9 12Z"></path></svg><span class="toc__TocHeader-c2gnov-2 cqPqff">API Reference</span></div><ul class="toc__TocSubpages-c2gnov-4 FcGip"><div><li><div title="default (Map)" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="default (Map)" href="/react-map-gl/docs/api-reference/map">default (Map)</a></div></div></li></div><div><li><div title="AttributionControl" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="AttributionControl" href="/react-map-gl/docs/api-reference/attribution-control">AttributionControl</a></div></div></li></div><div><li><div title="FullscreenControl" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="FullscreenControl" href="/react-map-gl/docs/api-reference/fullscreen-control">FullscreenControl</a></div></div></li></div><div><li><div title="GeolocateControl" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="GeolocateControl" href="/react-map-gl/docs/api-reference/geolocate-control">GeolocateControl</a></div></div></li></div><div><li><div title="Layer" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="Layer" href="/react-map-gl/docs/api-reference/layer">Layer</a></div></div></li></div><div><li><div title="MapProvider" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="MapProvider" href="/react-map-gl/docs/api-reference/map-provider">MapProvider</a></div></div></li></div><div><li><div title="Marker" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="Marker" href="/react-map-gl/docs/api-reference/marker">Marker</a></div></div></li></div><div><li><div title="NavigationControl" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="NavigationControl" href="/react-map-gl/docs/api-reference/navigation-control">NavigationControl</a></div></div></li></div><div><li><div title="Popup" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="Popup" href="/react-map-gl/docs/api-reference/popup">Popup</a></div></div></li></div><div><li><div title="ScaleControl" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="ScaleControl" href="/react-map-gl/docs/api-reference/scale-control">ScaleControl</a></div></div></li></div><div><li><div title="Source" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="Source" href="/react-map-gl/docs/api-reference/source">Source</a></div></div></li></div><div><li><div title="useControl" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="useControl" href="/react-map-gl/docs/api-reference/use-control">useControl</a></div></div></li></div><div><li><div title="useMap" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="useMap" href="/react-map-gl/docs/api-reference/use-map">useMap</a></div></div></li></div><div><li><div title="Types" class="toc__TocEntry-c2gnov-1 bdPEit"><div class="toc__TocLink-c2gnov-3 cowmvG"><a title="Types" href="/react-map-gl/docs/api-reference/types">Types</a></div></div></li></div></ul></div></div><div class="body__BodyContainerToC-lvm4v2-1 idNLwm"><div style="position:relative"><div class="typography__MarkdownBody-sc-1pmaksm-11 iTIrjR"><h1 id="upgrade-guide" style="position:relative" class="typography__H1-sc-1pmaksm-2 dMTgn"><a href="#upgrade-guide" aria-label="upgrade guide permalink" class="typography__A-sc-1pmaksm-0 dvhuEd anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Upgrade Guide</h1><h2 style="position:relative" id="upgrading-to-v70" class="typography__H2-sc-1pmaksm-3 jYCwIr"><a href="#upgrading-to-v70" aria-label="upgrading to v70 permalink" class="typography__A-sc-1pmaksm-0 dvhuEd anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Upgrading to v7.0</h2><p class="typography__P-sc-1pmaksm-8 cncNYa">v7 is a complete rewrite of the library. It is redesigned to be fast, lightweight, fully typed, to behave the same and expose the same APIs as the wrapped map library, and to provide the maximum compatibility with third-party plugins. To take advantages of these new features, you need to make some changes to your code that was previously depending on react-map-gl v5 and v6.</p><blockquote class="typography__BlockQuote-sc-1pmaksm-16 hAWDlt"><p class="typography__P-sc-1pmaksm-8 cncNYa">If you are using react-map-gl controls (<code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">Marker</code>, <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">Popup</code>, <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">NavigationControl</code> etc.) with deck.gl's <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">ContextProvider</code>, do not upgrade to this version. The old approach no longer works with v7. We are moving the support for this use case to a new project that does not depend on mapbox.</p></blockquote><h3 style="position:relative" id="dependencies" class="typography__H3-sc-1pmaksm-4 ePRhQs"><a href="#dependencies" aria-label="dependencies permalink" class="typography__A-sc-1pmaksm-0 dvhuEd anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Dependencies</h3><ul class="typography__List-sc-1pmaksm-9 hsOfQe"><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy">Add <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">mapbox-gl</code> (or a compatible fork) to your package.json. <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">react-map-gl</code> no longer lists a specific map renderer in its dependencies, so you are free to use it with Mapbox v1, v2 or Maplibre.</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">viewport-mercator-project</code> (an alias of <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">@math.gl/web-mercator</code>) is no longer a dependency. You can still install the library on the side as a utility for viewport-related math, but it's no longer required.</li></ul><h3 style="position:relative" id="module-exports" class="typography__H3-sc-1pmaksm-4 ePRhQs"><a href="#module-exports" aria-label="module exports permalink" class="typography__A-sc-1pmaksm-0 dvhuEd anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Module exports</h3><ul class="typography__List-sc-1pmaksm-9 hsOfQe"><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">InteractiveMap</code> and <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">StaticMap</code> are removed. Instead, import <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">Map</code>.</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">setRTLTextPlugin</code> is removed. Use the <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">Map</code> component's <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">RTLTextPlugin</code> prop (default enabled).</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">MapController</code> is removed. v7.0 has removed its own implementation of user input handling in favor of the <a href="https://docs.mapbox.com/mapbox-gl-js/api/handlers/" class="typography__A-sc-1pmaksm-0 dvhuEd">native handlers</a>. If you are using a custom implementation of <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">MapController</code>, check if the native handlers offer options to address your application's needs.</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">MapContext</code> and <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">useMapControl</code> are removed. Check out the new API <a class="typography__GatsbyA-sc-1pmaksm-1 dMoEUD" href="/react-map-gl/docs/api-reference/use-map">useMap</a> and <a class="typography__GatsbyA-sc-1pmaksm-1 dMoEUD" href="/react-map-gl/docs/api-reference/use-control">useControl</a>.</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy">The overlay components (<code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">HTMLOverlay</code>, <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">CanvasOverlay</code> and <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">SVGOverlay</code>) are removed. Check out <a href="https://github.com/visgl/react-map-gl/tree/7.0-release/examples/custom-overlay" class="typography__A-sc-1pmaksm-0 dvhuEd">this example</a> for implementing similar controls in your own application.</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">LinearInterpolator</code> and <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">FlyToInterpolator</code> are removed. Use <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">map.easeTo()</code> and <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">map.flyTo()</code> instead, see <a href="https://github.com/visgl/react-map-gl/tree/7.0-release/examples/viewport-animation" class="typography__A-sc-1pmaksm-0 dvhuEd">this example</a>.</li></ul><h3 style="position:relative" id="map" class="typography__H3-sc-1pmaksm-4 ePRhQs"><a href="#map" aria-label="map permalink" class="typography__A-sc-1pmaksm-0 dvhuEd anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Map</h3><p class="typography__P-sc-1pmaksm-8 cncNYa"><a class="typography__GatsbyA-sc-1pmaksm-1 dMoEUD" href="/react-map-gl/docs/api-reference/map">documentation</a></p><ul class="typography__List-sc-1pmaksm-9 hsOfQe"><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy">Renamed props for better consistency with the wrapped library:<ul class="typography__List-sc-1pmaksm-9 hsOfQe"><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">mapboxApiAccessToken</code> is now <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">mapboxAccessToken</code></li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">mapboxApiUrl</code> is now <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">baseApiUrl</code></li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">preventStyleDiffing</code> (default <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">false</code>) is replaced with <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">styleDiffing</code> (default <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">true</code>)</li></ul></li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">mapStyle</code> should be explicitly specified. The default value has changed from <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">"mapbox://styles/mapbox/light-v9"</code> to an empty style.</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy">The following props are removed and apps should use <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">style</code> instead:<ul class="typography__List-sc-1pmaksm-9 hsOfQe"><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">width</code></li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">height</code></li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">visible</code></li></ul></li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">onViewportChange</code>, <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">onViewStateChange</code> and <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">onInteractionStateChange</code> are removed. You can either use <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">Map</code> as an uncontrolled component with the new <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">initialViewState</code> prop, or if you need to manage the camera state externally (e.g. in Redux), use the <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">onMove</code> callback instead. See examples in <a class="typography__GatsbyA-sc-1pmaksm-1 dMoEUD" href="/react-map-gl/docs/get-started/state-management">state management</a>.</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">transition*</code> props are removed. Use <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">map.easeTo()</code> and <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">map.flyTo()</code> instead, see <a href="https://github.com/visgl/react-map-gl/tree/7.0-release/examples/viewport-animation" class="typography__A-sc-1pmaksm-0 dvhuEd">this example</a>.</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">mapOptions</code> is removed. Almost all of the options for the native <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">Map</code> class are exposed as props. </li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">onHover</code> is removed. Use <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">onMouseMove</code> or <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">onMouseEnter</code>.</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy">The event argument is changed for all interaction callbacks. See documentation for details.</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">getCursor</code> is removed as part of the effort to get <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">Map</code> behave the same as the native component. To set the cursor, use the <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">cursor</code> prop. Follow <a href="https://github.com/visgl/react-map-gl/tree/7.0-release/examples/custom-cursor" class="typography__A-sc-1pmaksm-0 dvhuEd">this example</a> to change cursor on hover.</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">touchAction</code> and <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">eventRecognizerOptions</code> are removed. Check out the <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">cooperativeGestures</code> prop.</li></ul><h3 style="position:relative" id="other-components" class="typography__H3-sc-1pmaksm-4 ePRhQs"><a href="#other-components" aria-label="other components permalink" class="typography__A-sc-1pmaksm-0 dvhuEd anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Other components</h3><ul class="typography__List-sc-1pmaksm-9 hsOfQe"><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">capture*</code> props are removed.</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">*label</code> props are removed. Use <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">Map</code>'s <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">locale</code> prop.</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy">All map controls' props are now strictly aligned with their mapbox-gl counterparts. In heading this direction, we are able to remove a significant amount of custom code and have the components behave more predictably for developers switching from the native library. If your application is relying on an old feature that is no longer supported, please open a topic on <a href="https://github.com/visgl/react-map-gl/discussions" class="typography__A-sc-1pmaksm-0 dvhuEd">Discussion</a> so we can review on a case-by-case basis.</li></ul><h2 style="position:relative" id="upgrading-to-v53v61" class="typography__H2-sc-1pmaksm-3 jYCwIr"><a href="#upgrading-to-v53v61" aria-label="upgrading to v53v61 permalink" class="typography__A-sc-1pmaksm-0 dvhuEd anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Upgrading to v5.3/v6.1</h2><ul class="typography__List-sc-1pmaksm-9 hsOfQe"><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">MapContext</code> is now an official API. The experimental <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">_MapContext</code> export will be removed in a future release.</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">react-virtualized-auto-sizer</code> is no longer a dependency.</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy">Inertia has been enabled by default on the map controller. To revert to the behavior in previous versions, set the <a href="/react-map-gl/docs/api-reference/interactive-map.md#interaction-options" class="typography__A-sc-1pmaksm-0 dvhuEd">interaction options</a>:</li></ul><div class="gatsby-highlight" data-language="js"><pre class="typography__Pre-sc-1pmaksm-14 fPGooQ language-js"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-js"><span class="token keyword">const</span> <span class="token constant">CONTROLLER_OPTS</span> <span class="token operator">=</span> <span class="token punctuation">{</span>
|
|
<span class="token literal-property property">dragPan</span><span class="token operator">:</span> <span class="token punctuation">{</span><span class="token literal-property property">inertia</span><span class="token operator">:</span> <span class="token number">0</span><span class="token punctuation">}</span><span class="token punctuation">,</span>
|
|
<span class="token literal-property property">dragRotate</span><span class="token operator">:</span> <span class="token punctuation">{</span><span class="token literal-property property">inertia</span><span class="token operator">:</span> <span class="token number">0</span><span class="token punctuation">}</span><span class="token punctuation">,</span>
|
|
<span class="token literal-property property">touchZoom</span><span class="token operator">:</span> <span class="token punctuation">{</span><span class="token literal-property property">inertia</span><span class="token operator">:</span> <span class="token number">0</span><span class="token punctuation">}</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">;</span>
|
|
|
|
<span class="token operator"><</span>MapGL <span class="token punctuation">{</span><span class="token operator">...</span><span class="token constant">CONTROLLER_OPTS</span><span class="token punctuation">}</span> <span class="token operator">...</span> <span class="token operator">/</span><span class="token operator">></span></code></pre></div><ul class="typography__List-sc-1pmaksm-9 hsOfQe"><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">Source</code> and <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">Layer</code> components no longer expose imperative methods via <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">ref</code> as part of the migration to functional components. This is to comply with the pattern recommended by the latest React.<ul class="typography__List-sc-1pmaksm-9 hsOfQe"><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy">If you used to call <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">sourceRef.getSource()</code>, it can be replaced with <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">mapRef().getMap().getSource(sourceId)</code>.</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy">If you used to call <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">layerRef.getLayer()</code>, it can be replaced with <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">mapRef().getMap().getLayer(layerId)</code>.</li></ul></li></ul><h2 style="position:relative" id="upgrading-to-v6" class="typography__H2-sc-1pmaksm-3 jYCwIr"><a href="#upgrading-to-v6" aria-label="upgrading to v6 permalink" class="typography__A-sc-1pmaksm-0 dvhuEd anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Upgrading to v6</h2><ul class="typography__List-sc-1pmaksm-9 hsOfQe"><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy">A valid Mapbox access token is always required.</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy">The default value of <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">InteractiveMap</code>'s <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">maxPitch</code> prop is changed to <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">85</code> from <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">60</code>.</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">mapbox-gl</code> v2 introduced a breaking change to the build system. Transpiling it may result in a crash in the production build with the message <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">m is not defined</code>. Find solutions in <a href="https://github.com/mapbox/mapbox-gl-js/issues/10173" class="typography__A-sc-1pmaksm-0 dvhuEd">this thread</a>.</li></ul><h2 style="position:relative" id="upgrading-to-v4" class="typography__H2-sc-1pmaksm-3 jYCwIr"><a href="#upgrading-to-v4" aria-label="upgrading to v4 permalink" class="typography__A-sc-1pmaksm-0 dvhuEd anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Upgrading to v4</h2><ul class="typography__List-sc-1pmaksm-9 hsOfQe"><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">onChangeViewport</code> is removed, use <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">onViewportChange</code> instead</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">Immutable.js</code> is no longer a dependency</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy">Export <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">experimental.MapControls</code> is removed, use <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">MapController</code> instead</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">InteractiveMap</code>'s <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">mapControls</code> prop is renamed to <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">controller</code></li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy">Removed support for the deprecated <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">interactive</code> property on the layer styles. Use the <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">interactiveLayerIds</code> prop to specify which layers are clickable.</li></ul><h2 style="position:relative" id="upgrading-to-v32" class="typography__H2-sc-1pmaksm-3 jYCwIr"><a href="#upgrading-to-v32" aria-label="upgrading to v32 permalink" class="typography__A-sc-1pmaksm-0 dvhuEd anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Upgrading to v3.2</h2><ul class="typography__List-sc-1pmaksm-9 hsOfQe"><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy">The latest mapbox-gl release requires stylesheet to be included at all times. See <a class="typography__GatsbyA-sc-1pmaksm-1 dMoEUD" href="/react-map-gl/docs/get-started/get-started">Get Started</a> for information about styling.</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy">Immutable.js is no longer a hard dependency and will be removed in the next major release. If you are importing immutable in your application, it is recommended that you explicitly list it in the application's dependencies.</li></ul><h2 style="position:relative" id="upgrading-to-v3" class="typography__H2-sc-1pmaksm-3 jYCwIr"><a href="#upgrading-to-v3" aria-label="upgrading to v3 permalink" class="typography__A-sc-1pmaksm-0 dvhuEd anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Upgrading to v3</h2><p class="typography__P-sc-1pmaksm-8 cncNYa">v3 is a major upgrade of react-map-gl. While we have tried to gently deprecated any changed or removed features, a few breaking changes could not be avoided.</p><h3 style="position:relative" id="version-requirements" class="typography__H3-sc-1pmaksm-4 ePRhQs"><a href="#version-requirements" aria-label="version requirements permalink" class="typography__A-sc-1pmaksm-0 dvhuEd anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Version Requirements</h3><ul class="typography__List-sc-1pmaksm-9 hsOfQe"><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy">The <strong>Node Version Requirement</strong> for <strong>building</strong> react-map-gl is now <strong>>=v6.4.0</strong>. Using prebuilt react-map-gl does <strong>NOT</strong> has this limitation. This is introduced by <a href="https://github.com/mapbox/mapbox-gl-js/releases/tag/v0.38.0" class="typography__A-sc-1pmaksm-0 dvhuEd">Mapbox GL JS v0.38.0</a></li></ul><h3 style="position:relative" id="mapgl-component" class="typography__H3-sc-1pmaksm-4 ePRhQs"><a href="#mapgl-component" aria-label="mapgl component permalink" class="typography__A-sc-1pmaksm-0 dvhuEd anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>MapGL Component</h3><ul class="typography__List-sc-1pmaksm-9 hsOfQe"><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><strong>Two Map Components</strong> - v3 now splits the Map component into two React components: <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">StaticMap</code> and <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">InteractiveMap</code>. <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">InteractiveMap</code> is the default export, and designed to be as compatible as possible with the v2 default component.</li></ul><h4 style="position:relative" id="onchangeviewport" class="typography__H4-sc-1pmaksm-5 dMIfYV"><a href="#onchangeviewport" aria-label="code classlanguage textonchangeviewportcode callback now includes code classlanguage textwidthcode and code classlanguage textheightcode permalink" class="typography__A-sc-1pmaksm-0 dvhuEd anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">onChangeViewport</code> callback now includes <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">width</code> and <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">height</code>.</h4><p class="typography__P-sc-1pmaksm-8 cncNYa">The <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">viewport</code> parameter passed to the <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">onChangeViewport</code> callback now includes <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">width</code> and <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">height</code>. Application code that composed the <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">viewport</code> with <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">width</code> and <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">height</code> may have to be updated. Please double check your render code if you relied on this behavior.</p><div class="gatsby-highlight" data-language="js"><pre class="typography__Pre-sc-1pmaksm-14 fPGooQ language-js"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-js"><span class="token comment">// BAD: 'width' and 'height' below will be overridden by what's in the 'viewport' object</span>
|
|
<span class="token operator"><</span>ReactMapGL width<span class="token operator">=</span><span class="token punctuation">{</span><span class="token number">500</span><span class="token punctuation">}</span> height<span class="token operator">=</span><span class="token punctuation">{</span><span class="token number">400</span><span class="token punctuation">}</span> <span class="token punctuation">{</span><span class="token operator">...</span>viewport<span class="token punctuation">}</span> <span class="token operator">/</span><span class="token operator">></span>
|
|
<span class="token comment">// GOOD: 'width' and 'height' below will override the values in 'viewport'</span>
|
|
<span class="token operator"><</span>ReactMapGL <span class="token punctuation">{</span><span class="token operator">...</span>viewport<span class="token punctuation">}</span> width<span class="token operator">=</span><span class="token punctuation">{</span><span class="token number">500</span><span class="token punctuation">}</span> height<span class="token operator">=</span><span class="token punctuation">{</span><span class="token number">400</span><span class="token punctuation">}</span> <span class="token operator">/</span><span class="token operator">></span></code></pre></div><h3 style="position:relative" id="overlays" class="typography__H3-sc-1pmaksm-4 ePRhQs"><a href="#overlays" aria-label="overlays permalink" class="typography__A-sc-1pmaksm-0 dvhuEd anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Overlays</h3><ul class="typography__List-sc-1pmaksm-9 hsOfQe"><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><strong>Some Overlays Moved to Examples</strong> - Some less frequently used overlays (<code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">DraggablePointsOverlay</code>, <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">ChoroplethOverlay</code>, <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">ScatterplotOverlay</code>), have been moved to examples. Most users are now using mapbox styles or deck.gl layers and removing these overlays reduces the size of the react-map-gl library for the majority of users that don't need them. If you still use them, simply copy the overlay source file(s) into your application.</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><strong>Overlays must be Children of the Map</strong> - Overlays <strong>must</strong> now be rendered as children of the main <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">react-map-gl</code> component to automatically sync with the map viewport.</li></ul><h3 style="position:relative" id="fitbounds" class="typography__H3-sc-1pmaksm-4 ePRhQs"><a href="#fitbounds" aria-label="code classlanguage textfitboundscode utility function permalink" class="typography__A-sc-1pmaksm-0 dvhuEd anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">fitBounds</code> utility function</h3><p class="typography__P-sc-1pmaksm-8 cncNYa">The <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">fitBounds</code> utility has been moved to the <a href="https://github.com/uber-web/math.gl" class="typography__A-sc-1pmaksm-0 dvhuEd">math.gl</a> library. The function can now be called as follows:</p><div class="gatsby-highlight" data-language="js"><pre class="typography__Pre-sc-1pmaksm-14 fPGooQ language-js"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-js"><span class="token keyword">import</span> WebMercatorViewport <span class="token keyword">from</span> <span class="token string">'viewport-mercator-project'</span><span class="token punctuation">;</span>
|
|
<span class="token keyword">const</span> viewport <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">WebMercatorViewport</span><span class="token punctuation">(</span><span class="token punctuation">{</span><span class="token literal-property property">width</span><span class="token operator">:</span> <span class="token number">600</span><span class="token punctuation">,</span> <span class="token literal-property property">height</span><span class="token operator">:</span> <span class="token number">400</span><span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token keyword">const</span> bound <span class="token operator">=</span> viewport<span class="token punctuation">.</span><span class="token function">fitBounds</span><span class="token punctuation">(</span>
|
|
<span class="token punctuation">[</span><span class="token punctuation">[</span><span class="token operator">-</span><span class="token number">73.9876</span><span class="token punctuation">,</span> <span class="token number">40.7661</span><span class="token punctuation">]</span><span class="token punctuation">,</span> <span class="token punctuation">[</span><span class="token operator">-</span><span class="token number">72.9876</span><span class="token punctuation">,</span> <span class="token number">41.7661</span><span class="token punctuation">]</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
|
|
<span class="token punctuation">{</span><span class="token literal-property property">padding</span><span class="token operator">:</span> <span class="token number">20</span><span class="token punctuation">,</span> <span class="token literal-property property">offset</span><span class="token operator">:</span> <span class="token punctuation">[</span><span class="token number">0</span><span class="token punctuation">,</span> <span class="token operator">-</span><span class="token number">40</span><span class="token punctuation">]</span><span class="token punctuation">}</span>
|
|
<span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token comment">// => bounds: instance of WebMercatorViewport</span>
|
|
<span class="token comment">// {longitude: -73.48760000000007, latitude: 41.268014439447484, zoom: 7.209231188444142}</span></code></pre></div><h3 style="position:relative" id="deprecations" class="typography__H3-sc-1pmaksm-4 ePRhQs"><a href="#deprecations" aria-label="deprecations permalink" class="typography__A-sc-1pmaksm-0 dvhuEd anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Deprecations</h3><p class="typography__P-sc-1pmaksm-8 cncNYa">We have started to deprecate a few React props. In all the cases below, the old <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">props</code> will still work (you'll get a warning in the console), but they will likely be removed in the next major version of react-map-gl so you should start using the new <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">props</code> as soon as possible.</p><table class="typography__Table-sc-1pmaksm-17 bnjLCb"><thead><tr><th class="typography__TableHeaderCell-sc-1pmaksm-18 kXxWox">Old Prop</th><th class="typography__TableHeaderCell-sc-1pmaksm-18 kXxWox">New Prop</th></tr></thead><tbody><tr><td class="typography__TableBodyCell-sc-1pmaksm-19 kxRoVr"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">onChangeViewport(<viewport>)</code></td><td class="typography__TableBodyCell-sc-1pmaksm-19 kxRoVr"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">onViewportChange(<viewport>)</code></td></tr><tr><td class="typography__TableBodyCell-sc-1pmaksm-19 kxRoVr"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">onHoverFeatures(<features>)</code></td><td class="typography__TableBodyCell-sc-1pmaksm-19 kxRoVr"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">onHover(<event>)</code></td></tr><tr><td class="typography__TableBodyCell-sc-1pmaksm-19 kxRoVr"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">onClickFeatures(<features>)</code></td><td class="typography__TableBodyCell-sc-1pmaksm-19 kxRoVr"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">onClick(<event>)</code></td></tr><tr><td class="typography__TableBodyCell-sc-1pmaksm-19 kxRoVr"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">perspectiveEnabled [default: false]</code></td><td class="typography__TableBodyCell-sc-1pmaksm-19 kxRoVr"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">dragRotate [default: true]</code></td></tr></tbody></table><h2 style="position:relative" id="upgrading-to-v2" class="typography__H2-sc-1pmaksm-3 jYCwIr"><a href="#upgrading-to-v2" aria-label="upgrading to v2 permalink" class="typography__A-sc-1pmaksm-0 dvhuEd anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Upgrading to v2</h2><p class="typography__P-sc-1pmaksm-8 cncNYa">v2 is API compatible with v1, however if you are still using <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">v1</code> of react-map-gl, make sure that you first upgrade:</p><ul class="typography__List-sc-1pmaksm-9 hsOfQe"><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy">Your <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">node</code> version to <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">v4</code> or higher</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy">Your <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">react</code> version to <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">15.4</code> or higher.</li></ul><p class="typography__P-sc-1pmaksm-8 cncNYa">Background: <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">mapbox-gl</code> 0.31.0 introduced a hard dependency on Node >= v4.</p><h2 style="position:relative" id="upgrading-to-v1" class="typography__H2-sc-1pmaksm-3 jYCwIr"><a href="#upgrading-to-v1" aria-label="upgrading to v1 permalink" class="typography__A-sc-1pmaksm-0 dvhuEd anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Upgrading to v1</h2><p class="typography__P-sc-1pmaksm-8 cncNYa">(Upgrading from 0.6.x)</p><ul class="typography__List-sc-1pmaksm-9 hsOfQe"><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><strong>Importing Overlays</strong> - The map overlay components (<code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">HTMLOverlay</code>, <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">CanvasOverlay</code>, <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">SVGOverlay</code> etc) are now named exports. They previously had to be imported via their relative source paths:</li></ul><div class="gatsby-highlight" data-language="js"><pre class="typography__Pre-sc-1pmaksm-14 fPGooQ language-js"><code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-js"><span class="token comment">// v1.0</span>
|
|
<span class="token keyword">import</span> MapGL<span class="token punctuation">,</span> <span class="token punctuation">{</span>SVGOverlay<span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'react-map-gl'</span><span class="token punctuation">;</span>
|
|
|
|
<span class="token comment">// v0.6</span>
|
|
<span class="token keyword">import</span> MapGL <span class="token keyword">from</span> <span class="token string">'react-map-gl'</span><span class="token punctuation">;</span>
|
|
<span class="token keyword">import</span> SVGOverlay <span class="token keyword">from</span> <span class="token string">'react-map-gl/src/api-reference/svg-overlay'</span><span class="token punctuation">;</span><span class="token punctuation">.</span></code></pre></div><ul class="typography__List-sc-1pmaksm-9 hsOfQe"><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy"><strong>Map State</strong> - The map state reported by <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">onViewportChanged</code> will now contain additional state fields (tracking not only <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">pitch</code> and <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">bearing</code> needed for perspective mode, but also transient information about how the projection is being changed by the user).<ul class="typography__List-sc-1pmaksm-9 hsOfQe"><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy">This information must be passed back to the react-map-gl component in the next render.</li><li class="typography__ListItem-sc-1pmaksm-10 kVRSNy">To simplify and future proof applications, it is recommended to simply save the entire <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">mapState</code> in your app store whenever it changes and then pass it back to the component rather than trying to keep track of individual fields (like <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">longitude</code>, <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">latitude</code> and <code class="typography__InlineCode-sc-1pmaksm-12 egvBsN language-text">zoom</code>).</li></ul></li></ul></div></div></div></div></div></div><div id="gatsby-announcer" style="position:absolute;top:0;width:1px;height:1px;padding:0;overflow:hidden;clip:rect(0, 0, 0, 0);white-space:nowrap;border:0" aria-live="assertive" aria-atomic="true"></div></div><script id="gatsby-script-loader">/*<![CDATA[*/window.pagePath="/docs/upgrade-guide";/*]]>*/</script><script id="gatsby-chunk-mapping">/*<![CDATA[*/window.___chunkMapping={"polyfill":["/polyfill-4b657be50967bad20dc3.js"],"app":["/app-c33704d3a1abd6ea3046.js"],"component---examples-clusters-src-app-tsx":["/component---examples-clusters-src-app-tsx-ae435c98aa31b91df409.js"],"component---examples-controls-src-app-tsx":["/component---examples-controls-src-app-tsx-0fc6f5753e0415fde950.js"],"component---examples-custom-cursor-src-app-tsx":["/component---examples-custom-cursor-src-app-tsx-bd123514f109e45b15c9.js"],"component---examples-draggable-markers-src-app-tsx":["/component---examples-draggable-markers-src-app-tsx-c08cc0293d6f625308f7.js"],"component---examples-draw-polygon-src-app-tsx":["/component---examples-draw-polygon-src-app-tsx-4287be5a2ea35fbe0113.js"],"component---examples-filter-src-app-tsx":["/component---examples-filter-src-app-tsx-28b144519a629b0e0c53.js"],"component---examples-geocoder-src-app-tsx":["/component---examples-geocoder-src-app-tsx-244936683de9dee32672.js"],"component---examples-geojson-animation-src-app-tsx":["/component---examples-geojson-animation-src-app-tsx-8eaab89aa0e2583bf5b2.js"],"component---examples-geojson-src-app-tsx":["/component---examples-geojson-src-app-tsx-96c6855ca732a70078ab.js"],"component---examples-heatmap-src-app-tsx":["/component---examples-heatmap-src-app-tsx-c7a35aaf435bc075107c.js"],"component---examples-interaction-src-app-tsx":["/component---examples-interaction-src-app-tsx-cbc73f781b670001e1cb.js"],"component---examples-layers-src-app-tsx":["/component---examples-layers-src-app-tsx-cf13aa48a159342af3e3.js"],"component---examples-side-by-side-src-app-tsx":["/component---examples-side-by-side-src-app-tsx-c948e78a1a5129b01a93.js"],"component---examples-terrain-src-app-tsx":["/component---examples-terrain-src-app-tsx-7b12f3bb393a8bb524f0.js"],"component---examples-viewport-animation-src-app-tsx":["/component---examples-viewport-animation-src-app-tsx-8c2f70b3ab14cbdc2a58.js"],"component---examples-zoom-to-bounds-src-app-tsx":["/component---examples-zoom-to-bounds-src-app-tsx-2d6b6e19aa1d94266910.js"],"component---node-modules-gatsby-theme-ocular-src-react-templates-documentation-jsx":["/component---node-modules-gatsby-theme-ocular-src-react-templates-documentation-jsx-298d6a55a92e5d120c0e.js"],"component---node-modules-gatsby-theme-ocular-src-react-templates-examples-jsx":["/component---node-modules-gatsby-theme-ocular-src-react-templates-examples-jsx-861d77d9a70335a1bb15.js"],"component---node-modules-gatsby-theme-ocular-src-react-templates-search-jsx":["/component---node-modules-gatsby-theme-ocular-src-react-templates-search-jsx-b867458182f2a5e115e0.js"],"component---src-home-js":["/component---src-home-js-d077024a439c8e9d840e.js"]};/*]]>*/</script><script src="/react-map-gl/polyfill-4b657be50967bad20dc3.js" nomodule=""></script><script src="/react-map-gl/component---node-modules-gatsby-theme-ocular-src-react-templates-documentation-jsx-298d6a55a92e5d120c0e.js" async=""></script><script src="/react-map-gl/app-c33704d3a1abd6ea3046.js" async=""></script><script src="/react-map-gl/framework-47a7447cd78cae046a8b.js" async=""></script><script src="/react-map-gl/webpack-runtime-53e1d5786ef6c6593773.js" async=""></script></body></html> |