mapbox-gl

What is mapbox-gl?

The mapbox-gl npm package is a powerful library for interactive, customizable maps and geospatial data visualization. It leverages WebGL to render maps from vector tiles and allows for dynamic styling and interactivity.

What are mapbox-gl's main functionalities?

Display a Map

This code initializes a basic map using Mapbox GL JS. It sets the map container, style, center coordinates, and zoom level.

const mapboxgl = require('mapbox-gl');
mapboxgl.accessToken = 'your-access-token';
const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v11',
  center: [-74.5, 40],
  zoom: 9
});

Add a Marker

This code adds a marker to the map at the specified longitude and latitude coordinates.

const marker = new mapboxgl.Marker()
  .setLngLat([-74.5, 40])
  .addTo(map);

Add a Popup

This code creates a popup with a text message and attaches it to a specific location on the map.

const popup = new mapboxgl.Popup({ offset: 25 })
  .setText('Hello, World!')
  .setLngLat([-74.5, 40])
  .addTo(map);

Draw a Polygon

This code draws a polygon on the map by defining its coordinates and adding it as a layer when the map loads.

const polygon = {
  'type': 'Feature',
  'geometry': {
    'type': 'Polygon',
    'coordinates': [
      [
        [-74.5, 40],
        [-74.5, 41],
        [-73.5, 41],
        [-73.5, 40],
        [-74.5, 40]
      ]
    ]
  }
};
map.on('load', function () {
  map.addLayer({
    'id': 'polygon',
    'type': 'fill',
    'source': {
      'type': 'geojson',
      'data': polygon
    },
    'layout': {},
    'paint': {
      'fill-color': '#088',
      'fill-opacity': 0.8
    }
  });
});

Other packages similar to mapbox-gl

leaflet

Leaflet is a widely used open-source JavaScript library for mobile-friendly interactive maps. It is lightweight and easy to use, but it does not support vector tiles and WebGL rendering natively like mapbox-gl.

openlayers

OpenLayers is a high-performance, feature-rich library for displaying map data in web browsers. It supports a wide range of map types and data sources, including vector tiles, but it can be more complex to set up compared to mapbox-gl.

cesium

Cesium is a JavaScript library for creating 3D globes and 2D maps. It is highly performant and supports WebGL, making it suitable for complex geospatial visualizations. However, it is more focused on 3D rendering compared to mapbox-gl.

README

A WebGL JavaScript interactive maps library that can render Mapbox Vector Tiles.

Using mapbox-gl-js

Include the source via HTML tags:

<script src='https://api.tiles.mapbox.com/mapbox-gl-js/v0.16.0/mapbox-gl.js'></script>
<link href='https://api.tiles.mapbox.com/mapbox-gl-js/v0.16.0/mapbox-gl.css' rel='stylesheet' />

For more information, see the API documentation and examples.

Alternatively, you can npm install mapbox-gl and use it as a bundled dependency with browserify.

Style Reference

Developing mapbox-gl-js

Preparing your Development Environment

OSX

Install the Xcode Command Line Tools Package

xcode-select --install

Install node.js

brew install node

Clone the repository

git clone [e-mail]:mapbox/mapbox-gl-js.git

Install node module dependencies

cd mapbox-gl-js &&
npm install

Linux

Install git, node.js, GNU Make, and libglew-dev

sudo apt-get update &&
sudo apt-get install build-essential git nodejs libglew-dev

Clone the repository

git clone [e-mail]:mapbox/mapbox-gl-js.git

Install node module dependencies

cd mapbox-gl-js &&
npm install

Serving the Debug Page

Start the debug server

MAPBOX_ACCESS_TOKEN={YOUR MAPBOX ACCESS TOKEN} npm start

Open the debug page at http://localhost:9966

Creating a Standalone Build

A standalone build allows you to turn the contents of this repository into mapbox-gl.js and mapbox-gl.css files that can be included on an html page.

To create a standalone build, run

npm run production

Once that command finishes, you will have a standalone build at dist/mapbox-gl.js and dist/mapbox-gl.css

Running Tests

There are two test suites associated with Mapbox GL JS

• npm test runs quick unit tests
• npm run test-suite runs slower rendering tests from the mapbox-gl-test-suite repository

Running Benchmarks

See bench/README.md.

Writing Documentation

See docs/README.md.

Recommended Reading

Learning WebGL

• Greggman's WebGL articles
• WebGL reference card

GL performance

• Debugging and Optimizing WebGL applications
• Graphics Pipeline Performance

Misc

• drawing antialiased lines
• drawing text with signed distance fields
• label placement
• distance fields

Changelog

0.16.0 (March 24 2016)

Breaking Changes

• Replace Map#featuresAt and Map#featuresIn with Map#queryRenderedFeatures and map.querySourceFeatures (#2224)
  • Replace featuresAt and featuresIn with queryRenderedFeatures
  • Make queryRenderedFeatures synchronous, remove the callback and use the return value.
  • Rename layer parameter to layers and make it an array of layer names.
  • Remove the radius parameter. radius was used with featuresAt to account for style properties like line-width and circle-radius. queryRenderedFeatures accounts for these style properties. If you need to query a larger area, use a bounding box query instead of a point query.
  • Remove the includeGeometry parameter because queryRenderedFeatures always includes geometries.
• Map#debug is renamed to Map#showTileBoundaries (#2284)
• Map#collisionDebug is renamed to Map#showCollisionBoxes (#2284)

New Features & Improvements

• Improve overall rendering performance. (#2221)
• Improve performance of GeoJSONSource#setData. (#2222)
• Add Map#setMaxBounds method (#2234)
• Add isActive and isEnabled methods to interaction handlers (#2238)
• Add Map#setZoomBounds method (#2243)
• Add touch events (#2195)
• Add map.queryRenderedFeatures to query the styled and rendered representations of features (#2224)
• Add map.querySourceFeatures to get features directly from vector tiles, independent of the style (#2224)
• Add mapboxgl.Geolocate control (#1939)
• Make background patterns render seamlessly across tile boundaries (#2305)

Bugfixes

• Fix calls to setFilter, setLayoutProperty, and setLayerZoomRange on ref children (#2228)
• Fix undefined bucket errors after setFilter calls (#2244)
• Fix bugs causing hidden symbols to be rendered (#2246, #2276)
• Fix raster flickering (#2236)
• Fix queryRenderedFeatures precision at high zoom levels (#2292)
• Fix holes in GeoJSON data caused by unexpected winding order (#2285)
• Fix bug causing deleted features to be returned by queryRenderedFeatures (#2306)
• Fix bug causing unexpected fill patterns to be rendered (#2307)
• Fix popup location with preceding sibling elements (#2311)
• Fix polygon anti-aliasing (#2319)
• Fix slivers between non-adjacent polygons (#2319)
• Fix keyboard shortcuts causing page to scroll (#2312)