Migrate to maplibre in JavaScript

<!DOCTYPE html> <html> <head>  <meta charset="utf-8" /> <link rel="canonical" href="https://plotly.com/javascript/maplibre-migration/" /> <link rel="preconnect" href="https://fonts.googleapis.com" /> <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin /> <link href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@1,500&display=swap" rel="stylesheet" />  <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <script src="/all_static/javascripts/algolia/instantsearch.js"></script> <script src="/all_static/javascripts/algolia/polyfill.min.js"></script> <script src="//ajax.googleapis.com/ajax/libs/jquery/2.2.0/jquery.min.js"></script> <script src="https://cdn.jsdelivr.net/npm/popper.js@1.16.0/dist/umd/popper.min.js" integrity="sha384-Q6E9RHvbIyZFJoft+2mJbHaEWldlvI9IOYy5n3zV9zzTtmI3UksdQRVvoxMfooAo" crossorigin="anonymous"></script> <script> const theme = localStorage.getItem('theme'); if (theme === "dark-mode") { var root = document.getElementsByTagName('html')[0]; // '0' to assign the first (and only `HTML` tag) root.setAttribute('class', 'dark-mode'); } </script> <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css" crossorigin="anonymous"> <script src="https://stackpath.bootstrapcdn.com/bootstrap/3.3.6/js/bootstrap.min.js" crossorigin="anonymous"></script> <link href="https://esm.sh/@markprompt/css@0.18.0?css" rel="stylesheet" /> <link href="/all_static/css/markprompt.css" rel="stylesheet" />    <script type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_CHTML"></script> <script src="//cdnjs.cloudflare.com/ajax/libs/d3/3.5.17/d3.min.js"></script>  <script src="https://cdn.plot.ly/plotly-3.0.1.min.js"></script>   <link href="//fonts.googleapis.com/css?family=Open+Sans:400,300,300italic,400italic,600,600italic,700,700italic,800,800italic|Ubuntu+Mono:400,700|Asap" rel="stylesheet" type="text/css" /> <link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css" />  <link rel="stylesheet" type="text/css" href="/all_static/css/main.css?version=false" /> <link rel="stylesheet" type="text/css" href="/all_static/css/improve.css?version=2025-03-21-13-40">    <link rel="shortcut icon" href="https://dash.plotly.com/assets/favicon.ico" />   <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= 'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-N6T2RXG');</script>      <title> Migrate to maplibre in JavaScript </title> <meta name="description" content=How to migrate from Mapbox traces to Maplibre traces.>  <meta name="msvalidate.01" content="D319859A832F9F1D15A7646E2A42150A" />  <meta property="og:title" content= Migrate to maplibre in JavaScript /> <meta property="og:type" content="website"/> <meta property="og:image" content="https://images.plot.ly/plotly-documentation/thumbnail/area.jpg"> <meta property="og:description" content=How to migrate from Mapbox traces to Maplibre traces./> <meta property="og:url" /> <meta property="fb:admins" content="1123751525"/> <meta property="fb:admins" content="22418"/>  <meta name="twitter:card" content="photo" /> <meta name="twitter:title" content= Migrate to maplibre in JavaScript /> <meta name="twitter:url" content="https://plotly.com/javascript/maplibre-migration/"/> <meta name="twitter:description" content=How to migrate from Mapbox traces to Maplibre traces./> <meta name="twitter:image" content="https://images.plot.ly/plotly-documentation/thumbnail/area.jpg"> <meta name="twitter:site" content="@plotlygraphs"/> </head> <body data-spy="scroll" data-target=".watch" style="position:relative;" class="darkmode">  <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-N6T2RXG" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>   <div class="menu-mobile"> <div class="switch-mode"> <div class="icon-dark"></div> <div class="switch"></div> <div class="icon-light"></div> </div> <div class="close-menu"></div> <ul> <li><a style="font-weight: bold;" href="https://community.plotly.com/c/plotly-js/6">Forum</a> </li> <li><a style="font-weight: bold;" href="https://plotly.com/get-pricing/">Pricing</a></li> <li><a style="font-weight: bold;" href="https://dash.plotly.com">Dash</a></li>  </ul> </div> <div class="header-container"> <header class="header-main --default"> <div class="--wrap"> <div class="--wrap-left"> <div class="-identity"> <a href="https://plotly.com/"><img src="/all_static/images/graphing_library_dark.svg" style="height: 30px;" class="logo-dark"></a> <a href="/graphing-libraries/"><img src="/all_static/images/graphing_library.svg" style="height: 30px;" class="logo-white"></a> </div> </div> <div class="--wrap-right"> <nav class="--nav-meta" role="navigation"> <ul> <li class="languages"> <a class="plotly_js"> <div class="icon"></div> Javascript (v3.0.1) </a> <ul> <li> <a href="https://plotly.com/python/" class="python"> <div class="icon"></div>Python (v6.0.1) </a> </li> <li> <a href="https://plotly.com/r/" class="r"> <div class="icon"></div>R </a> </li> <li> <a href="https://plotly.com/julia/" class="julia"> <div class="icon"></div>Julia </a> </li> <li> <a href="https://plotly.com/javascript/" class="plotly_js"> <div class="icon"></div>Javascript (v3.0.1) </a> </li> <li> <a href="https://plotly.com/ggplot2/" class="ggplot2"> <div class="icon"></div>ggplot2 </a> </li> <li> <a href="https://plotly.com/matlab/" class="matlab"> <div class="icon"></div>MATLAB </a> </li> <li> <a href="https://plotly.com/fsharp/" class="fsharp"> <div class="icon"></div>F# </a> </li> <li> <a href="https://dash.plotly.com/" class="dash"> <div class="icon"></div>Dash </a> </li> </ul> </li> <li><a style="font-weight: bold;" href="https://community.plotly.com/c/plotly-js/6">Forum</a> </li> <li><a style="font-weight: bold;" href="https://plotly.com/get-pricing/">Pricing</a></li> <li><a style="font-weight: bold;" href="https://dash.plotly.com">Dash</a></li>  <iframe src="https://ghbtns.com/github-btn.html?user=plotly&repo=plotly.js&type=star&count=true&size=large" style="padding-top: 5px;" frameborder="0" scrolling="0" width="160px" height="40px"></iframe> </ul> <div class="switch-mode"> <div class="icon-dark"></div> <div class="switch"></div> <div class="icon-light"></div> </div> </nav> </div> <div class="menu-icon"> <span></span><span></span><span></span> </div> </div> </header> </div> <main class="--page page--single --index"> <div class="--wrap">  <aside class="--sidebar-container"> <div class="--sidebar-fixed reference" data-spy="affix" id="where"> <div class="brand"> <a href="/graphing-libraries/"><img src="/all_static/images/graphing_library.svg" style="height: 30px;"></a> </div> <button id="modal-button" type="button" data-toggle="modal" data-target="#myModal"> <input id="modal-input" style="border-radius: 5px; width: 100%;" type="text" placeholder=" Search..." readonly /> </button> <details style="color: white;margin-top: 20px;" > <summary>Quick Reference</summary> <nav class="--sidebar-body watch" id="where"> <ul class="--sidebar-list" style="margin-left: 15px;">  <li class="--sidebar-item"> <a href="/javascript/getting-started" class="js-splash--navigation-item">Getting Started</a> </li> <li class="--sidebar-item"> <a href="/javascript/is-plotly-free" class="js-splash--navigation-item">Is Plotly Free?</a> </li>  <li class="--sidebar-item"> <a href="/javascript/reference/index/" class="js-splash--navigation-item">Figure Reference</a> </li>   <li class="--sidebar-item"> <a href="/javascript/plotlyjs-function-reference/" class="js-splash--navigation-item">Function Reference</a> </li> <li class="--sidebar-item"> <a href="/javascript/plotlyjs-events" class="js-splash--navigation-item">Event Reference</a> </li> <li class="--sidebar-item"> <a href="/javascript/configuration-options/" class="js-splash--navigation-item">Configuration Options</a> </li>     <li class="--sidebar-item"> <a target="_blank" href="https://github.com/plotly/plotly.js/" class="js-splash--navigation-item">GitHub</a> </li> <li class="--sidebar-item"> <a target="_blank" href="http://community.plotly.com/" class="js-splash--navigation-item">community.plotly.com</a> </li> </ul> </nav> </details> <details style="color: white;margin-top: 20px;" open> <summary>On This Page</summary> <nav class="--sidebar-body watch" id="where"> <ul class="--sidebar-list" id="nav_header_insertion_list"></ul> </nav> </details> </div> <a href="https://go.plotly.com/elevate-your-analytics?utm_source=Webinar:%20Dash%20Enterprise%205.7&utm_medium=graphing_libraries&utm_content=sidebar" target="_blank"> <img src="https://images.prismic.io/plotly-marketing-website-2/Z9mL0DiBA97Gimoh_Square_ads.jpg?auto=format,compress" style="width: 200px; height: 200px; position: fixed; bottom: 10px; left: 50px" alt="Sign up for the upcoming webinar: Elevate Your Analytics with Plotly Dash Enterprise 5.7"> </a> </aside>  <section class="--page-body --tutorial-index --base"> <header class="--welcome"> <div class="--welcome-body">  <div class="--title"> <div class="--body"> <div class="nav-breadcrumb-container"> <div> <div class="breadcrumb-nav"> <a href="/javascript"> JavaScript </a> > <a href="/javascript/maps">Maps</a> > <span>Migrate to Maplibre</span> </div> </div> <div class="nav-breadcrumb-right"> <div class="--fork"> <a id="forklink" href="https://github.com/plotly/graphing-library-docs/tree/master/_posts/plotly_js/maps/maplibre-migration/"> <div class="icon"> <svg style="width:20px;height:20px" viewbox="0 0 24 24"> <path fill="#000000" d="M2.6,10.59L8.38,4.8L10.07,6.5C9.83,7.35 10.22,8.28 11,8.73V14.27C10.4,14.61 10,15.26 10,16A2,2 0 0,0 12,18A2,2 0 0,0 14,16C14,15.26 13.6,14.61 13,14.27V9.41L15.07,11.5C15,11.65 15,11.82 15,12A2,2 0 0,0 17,14A2,2 0 0,0 19,12A2,2 0 0,0 17,10C16.82,10 16.65,10 16.5,10.07L13.93,7.5C14.19,6.57 13.71,5.55 12.78,5.16C12.35,5 11.9,4.96 11.5,5.07L9.8,3.38L10.59,2.6C11.37,1.81 12.63,1.81 13.41,2.6L21.4,10.59C22.19,11.37 22.19,12.63 21.4,13.41L13.41,21.4C12.63,22.19 11.37,22.19 10.59,21.4L2.6,13.41C1.81,12.63 1.81,11.37 2.6,10.59Z"> </path> </svg> </div> <span>Suggest an edit to this page</span> </a> </div> </div> </div> <h1> Migrate to Maplibre in JavaScript </h1> <p>How to migrate from Mapbox traces to Maplibre traces. </p> <br>  <details> <summary><span style="cursor: pointer; color: #506784 !important">New to Plotly?</span></summary> <p>Plotly is a <a href="/javascript/is-plotly-free/">free and open-source</a> graphing library for JavaScript. We recommend you read our <a href="/javascript/getting-started/">Getting Started guide</a> for the latest installation or upgrade instructions, then move on to our <a href="/javascript/plotly-fundamentals/">Plotly Fundamentals tutorials</a> or dive straight in to some <a href="/javascript/basic-charts/">Basic Charts tutorials</a>.</p> </details> </div> </div> </div> </header>  <section class="tutorial-content"> <p>With the release of Plotly.js v2.35.0, we are introducing a new set of trace types for maps with tile underlays:</p> <ul> <li>Choroplethmap</li> <li>Scattermap</li> <li>Densitymap</li> </ul> <p>These traces replace the existing Mapbox traces, <code>Choroplethmapbox</code>, <code>Scattermapbox</code>, <code>Densitymapbox</code>, but use <a href="https://maplibre.org">MapLibre</a> as the map renderer rather than Mapbox. </p> <p>When switching to the new traces, keep an eye out for improved rendering performance, WebGL2 support, and over time, improved features in the Plotly map traces inherited from the MapLibre renderer, including projection support, globe views, terrain support, and support for modern mapping standards.</p> <p>You can learn more about the motivations for this change in our <a href="https://plotly.com/blog/plotly-is-switching-to-maplibre/">announcement post</a>.</p> <p>As a result of removing Mapbox as the rendering engine, we're also removing the Mapbox branding from these trace names. This means that migrating from Mapbox traces to MapLibre traces will require some code changes in your projects.</p> <ol> <li>Change trace names from <code>*mapbox</code> to <code>*map</code>. For any existing trace name ending in <code>*mapbox</code>, ensure you've removed the "box" suffix. </li> <li>If in use, update <code>layout.mapbox</code> argument in your layout configuration to <code>layout.map</code>. The nested properties are identical in the new map traces, so no other changes should be required.</li> <li>If in use, update <code>mapbox_style</code> to <code>map_style</code>.</li> <li>Verify your <code>map_style</code> settings. With <code>mapbox</code> traces, we bundle <code>basic</code>, <code>streets</code>, <code>outdoors</code>, <code>light</code>, <code>dark</code>, <code>satellite</code>, and <code>satellite-streets</code> styles, using Mapbox styling. These style names are still available, but they now reference slightly different styles provided by other tools. </li> </ol> <p>Note that Mapbox API keys are no longer required for Plotly-provided styles, but using external styles in your Plotly maps remains supported with the existing API.</p> </section> <a href="https://dash.plotly.com/tutorial?utm_medium=graphing_libraries&utm_content=javascript_footer"><img width="100%" style="margin-top: 20px;" src="/all_static/images/dash_2023.png" /></a>  </section> </div> </main> <script> var array = []; $('.tutorial-content :header:not(h6)').each(function (i, e) { var item = $(e); var itemText = item.text(); var hash = itemText.replace(/[^a-z0-9\s]/gi, '').replace(/[_\s]/g, '-').replace(/^-+|-+$/g, '').toLowerCase(); item.attr("id", hash); array.push({text: itemText, tag: item.prop("tagName"), hash: hash}); }); $("#nav_header_insertion_list").html(array.map(function(entry) { var text = entry.text.replace(/[^a-z0-9\s\.:\-\?\!)]/gi, ''); if(entry.tag.toLowerCase() < "h4"){ return('<li class="--sidebar-item"><a href="#' + entry.hash + '">' + text + '</a></li>'); } else { return('<li class="--sidebar-item"><a href="#' + entry.hash + '">' + text + '</a></li>'); } }).join("")); //$(".tutorial-content :header:not(h6)").append( "\<div class=\"icon copy\" data-tooltip=\"Click to copy direct link\"><svg style=\"width:24px;height:24px\" viewBox=\"0 0 24 24\"><path fill=\"#000000\" d=\"M10.59,13.41C11,13.8 11,14.44 10.59,14.83C10.2,15.22 9.56,15.22 9.17,14.83C7.22,12.88 7.22,9.71 9.17,7.76V7.76L12.71,4.22C14.66,2.27 17.83,2.27 19.78,4.22C21.73,6.17 21.73,9.34 19.78,11.29L18.29,12.78C18.3,11.96 18.17,11.14 17.89,10.36L18.36,9.88C19.54,8.71 19.54,6.81 18.36,5.64C17.19,4.46 15.29,4.46 14.12,5.64L10.59,9.17C9.41,10.34 9.41,12.24 10.59,13.41M13.41,9.17C13.8,8.78 14.44,8.78 14.83,9.17C16.78,11.12 16.78,14.29 14.83,16.24V16.24L11.29,19.78C9.34,21.73 6.17,21.73 4.22,19.78C2.27,17.83 2.27,14.66 4.22,12.71L5.71,11.22C5.7,12.04 5.83,12.86 6.11,13.65L5.64,14.12C4.46,15.29 4.46,17.19 5.64,18.36C6.81,19.54 8.71,19.54 9.88,18.36L13.41,14.83C14.59,13.66 14.59,11.76 13.41,10.59C13,10.2 13,9.56 13.41,9.17Z\"/> </svg> </div>"); </script> <footer class="--footer-main"> <section class="--footer-top"> <div class="--wrap"> <ul class="--footer-body"> <li class="--footer-column"> <h6 style="color:#119dff" class="--footer-heading">JOIN OUR MAILING LIST</h6>			 <ul> 				 <li> <p class="subscribe-text"> Sign up to stay in the loop with all things Plotly — from Dash Club to product updates, webinars, and more!</p> <a href="https://go.plot.ly/subscription" class="subscribe-button" target="_blank"> Subscribe </a> </li> </ul> </li> 		 <li class="--footer-column"> <h6 style="color:#e763fa" class="--footer-heading">Products</h6>			 <ul> <li><a href="https://plotly.com/dash/" target="_self">Dash</a></li> 				 				 <li><a href="https://plotly.com/consulting-and-oem/" target="_self">Consulting and Training</a></li> </ul> </li> 		 <li class="--footer-column"> <h6 style="color:#636efa" class="--footer-heading">Pricing</h6>			 <ul> <li><a href="https://plotly.com/get-pricing/" target="_self">Enterprise Pricing</a></li> 				 </ul> </li> 		 <li class="--footer-column"> <h6 style="color:#00cc96" class="--footer-heading">About Us</h6>			 <ul> <li><a href="https://plotly.com/careers" target="_self">Careers</a></li> 				 <li><a href="https://plotly.com/resources/" target="_self">Resources</a></li> 				 <li><a href="https://medium.com/@plotlygraphs" target="_self">Blog</a></li> 				 </ul> </li> 		 <li class="--footer-column"> <h6 style="color:#EF553B" class="--footer-heading">Support</h6>			 <ul> <li><a href="https://community.plot.ly/" target="_self">Community Support</a></li> 				 <li><a href="https://plotly.com/graphing-libraries" target="_self">Documentation</a></li> 				 </ul> </li> </ul> </div> </section> <section class="--footer-meta"> <div class="--wrap"> <div class="left"> <article class="--copyright">Copyright © 2025 Plotly. All rights reserved.</article> </div> <div class="right"> <article class="--tos"><a href="https://community.plotly.com/tos" target="_blank">Terms of Service</a> </article> <article class="--privacy"><a href="https://plotly.com/privacy/" target="_blank">Privacy Policy</a> </article> </div> </div> <div id="markprompt" /> </section> </footer> <div class="modal" id="myModal" tabindex="-1" role="dialog" aria-labelledby="myModalLabel"> <div class="modal-dialog" role="document"> <div class="modal-content" id="modal-content"> <div class="modal-header"> <button type="button" class="close" data-dismiss="modal" aria-label="Close"><span aria-hidden="true">×</span></button> <span style="float: left; padding-top:13px; padding-right:10px;"><i class="fa fa-search fa-lg"></i></span> <input id="search-input" class="search-input" type="text" placeholder="" /> </div> <div class="modal-body" id="modal-body"> <div id="search-results" class="search-results"> <div id="primary-search-results" class="primary-search-results"></div> <div id="schema-search-results" class="schema-search-results"></div> </div> </div> </div> </div> </div> <script> window.plotly_doc_language = "plotly_js"; </script>  <script> window.ALGOLIA_CONFIG = { 'applicationId': '7EK9KHJW8M', 'indexName': 'js_docs', 'apiKey': '4dae07ded6a721de73bde7356eec9280', 'baseurl': '/' } </script> <script id="algolia__template" type="text/template"> <div class="algolia__result"> <a class="algolia__result-link" onClick="$('#myModal').modal('toggle')" href="/{{ permalink }}">{{{ _highlightResult.name.value }}}</a> <div class="algolia__result-text">{{{ _highlightResult.description.value }}}</div> </div> </script> <script id="algolia__secondary-template" type="text/template"> <div class="algolia__secondary-result"> <a class="algolia__result-link" onClick="$('#myModal').modal('toggle')" href="/{{ permalink }}">{{{ _highlightResult.name.value }}}</a> <div class="algolia__result-text">{{{ _highlightResult.description.value }}}</div> </div> </script> <script id="algolia__template--no-results" type="text/template">No results found.</script> <script src="//cdn.jsdelivr.net/hogan.js/3.0.2/hogan.min.js"></script> <script src="/all_static/javascripts/algolia/algolia.js"></script>  <script src="/all_static//javascripts/hash_offset.js"></script>  <script src="/all_static/javascripts/imghover.js"></script> <script src="/all_static/javascripts/improve.js?version=2025-03-21-13-40"></script>   <script src="/all_static/javascripts/highlight/highlight.min.js"></script> <script src="/all_static/javascripts/highlight/julia.min.js"></script> <script src="/all_static/javascripts/highlight.line-numbers.js"></script> </body> </html>

CINXE.COM

Migrate to maplibre in JavaScript