Web applications

Mapbox provides a number of tools to build maps into your website or web-based application. Mapbox GL JS and Mapbox.js are both open source JavaScript libraries you can use to display your Mapbox maps, add interactivity, and customize the map experience in your application. We also provide a number of plugins for extending your web map’s functionality with drawing tools and interfaces to Mapbox web services APIs like the Mapbox Geocoding API or Mapbox Directions API. Building web pages or web applications with our JavaScript libraries will require writing code, but this guide is designed to provide you with the resources to get started.

Web app using Mapbox GL JS
Combine our JavaScript library with HTML, CSS, and JavaScript

This web application uses a combination of HTML, CSS, basic JavaScript, and Mapbox GL JS, our GL-based JavaScript library. If you are interested in learning more about how to build an application like this one, check out our step-by-step Build a store locator tutorial.

How web apps work

A web mapping library allows you to add a map to a web page and define the data it contains, its appearance, and a variety of functionality. Think of it like a toolbox filled with many different map-making tools that can be used together to build beautiful and interactive custom experiences.

Mapbox GL JS

Mapbox GL JS is a JavaScript library for building web applications with our modern mapping technology. This guide walks through some of Mapbox GL JS’s essential functions and common patterns, highlighting some of the core concepts that distinguish Mapbox GL JS from other map libraries. For those with experience using Leaflet, Mapbox.js, or OpenLayers, the next few sections will introduce some of the differences in Mapbox GL JS as well as features that should look familiar.

Client-side rendering

At the heart of Mapbox GL JS is client-side rendering. In web apps using Mapbox GL JS, maps are rendered on the fly by combining vector tiles with style rules using JavaScript and WebGL. Rendering maps in the browser rather than on a server makes it possible to change the map’s style and the data it displays on the fly and in response to user interaction.

The camera

The camera represents the map’s field of view. While the viewpoint in systems like Leaflet or Mapbox.js is determined by the map’s centerpoint and zoom level, Mapbox GL JS also includes parameters like pitch and bearing for adjusting the map’s perspective.

  • Center: in longitude, latitude order.
  • Zoom: any number within the zoom range, including decimals. For example, 1.5 or 6.2 are valid zoom levels.
  • Bearing: a value between 0 and 360 degrees that determines the map’s bearing, or rotation.
  • Pitch: a value between 0 and 60 degrees that determines the map’s tilt, or pitch.

Here’s an example of combining bearing and zoom:

Layers

Traditional JavaScript map libraries often have two distinct categories of what are called “layers”: baselayers, or image tiles that provide the foundation of the map, and overlays, which are often vector data like GeoJSON that are displayed on top of baselayers, sometimes obscuring details like labels.

Mapbox GL JS has no distinction between baselayers and overlay layers. This means that map details like labels and icons and elements like streets and buildings can be modified with JavaScript, just like overlays in earlier mapping libraries. Each layer provides rules about how certain data should be drawn in the browser, and the renderer uses these layers to actually draw the map on the screen.

Mapbox GL JS and Mapbox GL Native

Mapbox GL JS and Mapbox GL Native are two different projects for rendering maps build to the Mapbox Style Specification. They are similar, but are used for different purposes and do not have 100% feature parity.

  • Mapbox GL JS is a JavaScript library for making maps for the web. It can read the Mapbox Style Specification and uses WebGL to render your maps in modern browsers.
  • Mapbox GL Native is the backbone of the Mapbox iOS and Android SDKs. It supports the iOS and Android mobile platforms using OpenGL ES.

Mapbox.js

Mapbox.js is a web mapping library that extends the popular Leaflet.js library. Mapbox.js boasts the power of Leaflet.js, but is also heavily integrated with the Mapbox stack. If you’ve created a custom style in Mapbox Studio Classic Mapbox.js has tools for building web maps with those layers that add additional functionality. You can learn more about Mapbox.js in the API documentation.

Creating a web app

To create a web map, you’ll need to have some familiarity with HTML, CSS, and JavaScript. If you are new to web maps, check out our tutorials to help you get started.

Mapbox GL JS

Before getting started coding up your Mapbox GL JS map, you’ll need to include the relevant JavaScript and CSS files in your web page. Mapbox provides hosted versions of each that you can include in the <head> of your HTML file:

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

The basis of every Mapbox GL JS project is the mapboxgl.Map class. The example code in this section demonstrates the minimum you need to add a map to your page.

var map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-9',
  center: [-74.50, 40],
  zoom: 9
});
  • Container: This is the HTML element where you would like to place your map. In the example above, it is an element with id="map".
  • Style: The map loads a style via the URL mapbox://styles/mapbox/streets-v9. This is a URL to a remote file that the map will download in order to determine the tilesets it includes and how they are styled for the end-user. Mapbox GL JS permits URLs instead of literal data in several places, including data sources.
  • Center: Where Mapbox GL JS handles coordinates as arrays (here [-74.50, 40]), it assumes that the coordinates are in longitude, latitude order (vs latitude, longitude in Leaflet and Mapbox.js). This order corresponds to the order of coordinates in GeoJSON and every other geospatial format, as well as math’s X, Y ordering.
  • Zoom: The zoom level at which the map should be initialized. With Mapbox GL JS, can be a decimal value.

Adding layers to the map

You can add layers to the map using the addLayer() method. addLayer has only one required parameter: a Mapbox style layer object. It also accepts an optional before parameter, which is the ID of an existing layer to insert the new layer before. If this argument is omitted, the layer will be drawn on top of the map. The following sections describe the elements of a Mapbox style layer object.

Asynchronous
map.on('load', function() {
  map.addLayer({
    id: 'terrain-data',
    type: 'line',
    source: {
      type: 'vector',
      url: 'mapbox://mapbox.mapbox-terrain-v2'
    },
    'source-layer': 'contour'
  });
});

Since these resources are remote, they are asynchronous. Therefore, code that connects to Mapbox GL JS often uses event binding in order to change the map at the right time. For instance:

The above code uses the map.on('load', function() { code to call map.addLayer only after the map’s resources, including the style, have been loaded. If it were to run the map.addLayer method immediately, it would trigger an error because the style to which you would like to add a layer would not yet exist.

Specifying a source

You will need to define a source when you add a new layer. A source accepts a type and a url (a GeoJSON source will not have a url). There are five types of sources, each with its own properties:

Tilesets can include multiple subsets of data called source layers (the Mapbox Streets tileset contains source layers for roads, parks, etc). To make sure your layers are referencing the correct source layers, your layer object also needs to include a source-layer (often the name of the original file). See this example:

map.on('load', function() {
  map.addLayer({
    id: 'rpd_parks',
    type: 'fill',
    source: {
      type: 'vector',
      url: 'mapbox://mapbox.3o7ubwm8'
    },
    'source-layer': 'RPD_Parks'
  });
});

For more information on each source type, check out the Sources section of the Mapbox Style Specification.

Specifying layout and paint properties

Layers feature two special properties that enable data styling: paint and layout. These are used to define how data will be rendered on the map. layout properties refer to placement and visibility, among other high-level preferences, and are applied early in the rendering process. paint properties are more fine-grained style attributes like opacity, color, and translation. They are less processing-intensive and are rendered later.

The following code adds a layer to the map to style the parks data with a green fill.

map.on('load', function() {
  map.addLayer({
    id: 'rpd_parks',
    type: 'fill',
    source: {
      type: 'vector',
      url: 'mapbox://mapbox.3o7ubwm8'
    },
    'source-layer': 'RPD_Parks',
    layout: {
      visibility: 'visible'
    },
    paint: {
      'fill-color': 'rgba(61,153,80,0.55)'
    }
  });
});

The final product: a map zoomed to San Francisco with a parks layer with a green fill. The layer is based on a vector source of the city’s park lands data.

See the tutorials section for more Mapbox GL JS resources.

Mapbox.js

Add a map to the page

The core function of Mapbox.js is adding a map to your HTML page. Using one line of JavaScript, you can add a map to your webpage with a basemap that pans and zooms, set to a specific location and zoom level.

See this example for how to add a simple map with Mapbox.js.

Add and style custom data

If you want to add your own data to your Mapbox.js map, you can! Mapbox.js supports a few different formats, including GeoJSON. You can then style your GeoJSON data by adding style properties to the GeoJSON in the simplestyle specification or by using the built-in setStyle method.

See this example for how to add GeoJSON data to a map and style it using the simple style specification.

Extend your web app with plugins

Mapbox GL JS and Mapbox.js both support a rich ecosystem of plugins you can use to extend the functionality of your web map. There are plugins for adding interactive drawing tools, adding inset maps, integrating with the Mapbox Geocoding API and the Mapbox Directions API, and more! Check out the Mapbox GL JS plugins page and the Mapbox.js plugins page for more information.