SDKs overview

Mapbox GL JS is a JavaScript library that enables the creation of interactive, customizable vector maps in web browsers. It renders maps using WebGL, allowing for dynamic styling, smooth zooming, and the display of large datasets with improved performance compared to traditional raster-based mapping libraries. The core of Mapbox GL JS is its official JavaScript SDK, which provides the foundational tools for map initialization, layer management, data integration, and user interaction.

The SDK is designed to work with Mapbox's ecosystem, including Mapbox Studio for map design, Mapbox Tiling Service for custom data processing, and various Mapbox APIs for functionalities like geocoding and directions. While the primary SDK is in JavaScript, its flexibility allows for integration into different web frameworks and environments. Community efforts have also produced wrappers and extensions that facilitate its use in frameworks like React, Vue, and Angular, further expanding its applicability.

Developers utilize Mapbox GL JS to build applications ranging from simple location displays to complex geospatial analysis tools, leveraging its capabilities for custom data overlays, 3D extrusions, and real-time data visualization. The library's architecture supports a plugin-based approach, encouraging the development of additional functionalities by the community.

Official SDKs by language

Mapbox GL JS is primarily offered as a JavaScript library, making it directly consumable in web environments. Mapbox maintains this official SDK, providing comprehensive documentation and regular updates to ensure compatibility and introduce new features. The JavaScript SDK is foundational for all web-based applications using Mapbox GL JS capabilities.

Other Mapbox products, such as the Mapbox Maps SDK for Android and iOS, are separate native SDKs designed for mobile platforms, though they share similar principles and styling capabilities with Mapbox GL JS. For web development, the JavaScript SDK is the main interface.

Official Mapbox GL JS SDK
Language Package Maturity
JavaScript mapbox-gl Stable, Actively Maintained

Installation

Integrating Mapbox GL JS into a web project can be achieved through a Content Delivery Network (CDN) for quick setup or by installing it via a package manager for more controlled dependency management. Both methods provide access to the core library and its functionalities.

Via CDN

For rapid prototyping or simple integrations, including Mapbox GL JS directly from a CDN is the quickest method. This involves adding <link> and <script> tags to your HTML file's <head> section. It is important to include both the CSS and JavaScript files to ensure the map renders correctly and has access to all styling and interactive features.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Mapbox GL JS CDN Example</title>
    <meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no">
    <link href="https://api.mapbox.com/mapbox-gl-js/v3.4.0/mapbox-gl.css" rel="stylesheet">
    <script src="https://api.mapbox.com/mapbox-gl-js/v3.4.0/mapbox-gl.js"></script>
    <style>
      body { margin: 0; padding: 0; }
      #map { position: absolute; top: 0; bottom: 0; width: 100%; }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <script>
      // Your Mapbox GL JS code here
    </script>
  </body>
</html>

Replace v3.4.0 with the specific version of Mapbox GL JS you wish to use. The current stable version can be found on the Mapbox GL JS API reference.

Via Package Manager (npm)

For modern JavaScript projects, installing Mapbox GL JS via npm (Node Package Manager) is the recommended approach. This allows for better version control, bundling with other project assets, and integration into build pipelines. After installing, you can import Mapbox GL JS into your JavaScript modules.

npm install mapbox-gl

Once installed, you can import the library and its CSS into your JavaScript file:

import mapboxgl from 'mapbox-gl'; // eslint-disable-line import/no-webpack-loader-syntax
import 'mapbox-gl/dist/mapbox-gl.css';

In this setup, a bundler like Webpack or Rollup is typically used to manage these imports and compile the project. For more detailed instructions on installation and setup, refer to the Mapbox GL JS installation guide.

Quickstart example

This example demonstrates how to initialize a basic Mapbox GL JS map in a web page. It covers setting up a container, providing an access token, and defining initial map properties such as the center coordinates and zoom level. A valid Mapbox access token is required for the map to load tiles and functionality.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Display a map</title>
    <meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no">
    <link href="https://api.mapbox.com/mapbox-gl-js/v3.4.0/mapbox-gl.css" rel="stylesheet">
    <script src="https://api.mapbox.com/mapbox-gl-js/v3.4.0/mapbox-gl.js"></script>
    <style>
        body { margin: 0; padding: 0; }
        #map { position: absolute; top: 0; bottom: 0; width: 100%; }
    </style>
</head>
<body>
    <div id="map"></div>
    <script>
        // TO MAKE THE MAP APPEAR YOU MUST
        // ADD YOUR ACCESS TOKEN BELOW
        mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN'; // Replace with your actual token
        const map = new mapboxgl.Map({
            container: 'map', // container ID
            style: 'mapbox://styles/mapbox/streets-v12', // style URL
            center: [-74.0060, 40.7128], // starting position [lng, lat]
            zoom: 9 // starting zoom
        });
    </script>
</body>
</html>

This snippet initializes a map centered on New York City with a default street style. Remember to replace 'YOUR_MAPBOX_ACCESS_TOKEN' with your actual Mapbox public access token. For more immediate examples and interactive demos, the Mapbox GL JS official examples page is a valuable resource.

Community libraries

The Mapbox GL JS ecosystem is enriched by a variety of community-contributed libraries and plugins. These extend the core functionality of Mapbox GL JS, offering specialized tools for data visualization, UI components, and integration with popular JavaScript frameworks. While not officially maintained by Mapbox, these libraries often address common development patterns and specific use cases.

  • React-Map-GL: A React wrapper for Mapbox GL JS, providing React components for map rendering and interaction. This library simplifies integration into React applications, abstracting away direct DOM manipulation. It is developed and maintained by Uber and can be found on its vis.gl project page for React Map GL.
  • Mapbox GL Draw: A plugin for drawing and editing features on a Mapbox GL JS map. It provides UI and logic for creating points, lines, and polygons, making it useful for applications requiring user-defined spatial data input. More information is available in the Mapbox GL JS Draw example documentation.
  • Mapbox GL Geocoder: A control that adds a geocoding search input to the map, allowing users to search for locations by name or address. This integrates with the Mapbox Geocoding API. Details can be found in the Mapbox GL JS Geocoder example.
  • Mapbox GL Language: A plugin for automatically localizing the labels on Mapbox Street, Dark, Light, Outdoors, and Satellite Streets styles. It detects the user's browser language and adjusts map labels accordingly. The Mapbox GL JS language example showcases its use.
  • Deck.gl: While not exclusively a Mapbox GL JS library, Deck.gl is a powerful WebGL-powered framework for large-scale data visualization, often used in conjunction with Mapbox GL JS. It provides a set of highly performant data visualization layers. Its integration with Mapbox GL JS allows for sophisticated 2D and 3D data rendering on top of base maps, as described in the Google Maps Platform Deck.gl tutorial.

These community resources demonstrate the extensibility of Mapbox GL JS and the active developer community contributing to its broader utility. When using community libraries, it is advisable to check their maintenance status, documentation, and compatibility with your specific Mapbox GL JS version.