ol-mapbox-style

Create OpenLayers maps from Mapbox Style objects.

Getting started

To use a standalone build of ol-mapbox-style, just include 'dist/olms.js' on your HTML page. Otherwise just import the ol-mapbox-style module, like in the snippet below.

The code below creates an OpenLayers map from Mapbox's Bright v9 style:

import { apply } from 'ol-mapbox-style';

var key = 'Your Mapbox Access Token here';
apply('map', 'https://api.mapbox.com/styles/v1/mapbox/bright-v9?access_token=' + key);

Only commonly available system fonts and Google Fonts will automatically be available for any text-font defined in the Mapbox Style object. It is the responsibility of the application to load other fonts. Because ol-mapbox-style uses system and web fonts instead of PBF/SDF glyphs, the font stack is treated a little different: style and weight are taken from the primary font (i.e. the first one in the font stack). Subsequent fonts in the font stack are only used if the primary font is not available/loaded, and they will be used with the style and weight of the primary font.

To apply a subset of the layers defined in the Mapbox Style layer to a custom OpenLayers layer, use the applyStyle() function.

To apply the properties of the Mapbox Style's background layer to the map, use the applyBackground() function.

To create a style function for individual OpenLayers vector or vector tile layers, use the stylefunction module:

import stylefunction from 'ol-mapbox-style/stylefunction';
// OpenLayers imports from https://npmjs.com/package/ol
import VectorLayer from 'ol/layer/Vector';
import VectorSource from 'ol/source/Vector';
import GeoJSON from 'ol/format/GeoJSON';

var layer = new VectorLayer({
  source: new VectorSource({
    format: new GeoJSON(),
    url: 'data/states.geojson'
  })
});

fetch('data/states.json').then(function(response) {
  response.json().then(function(glStyle) {
    stylefunction(layer, glStyle, 'states');
  });
});

API

applyStyle

Applies a style function to an ol.layer.VectorTile or ol.layer.Vector with an ol.source.VectorTile or an ol.source.Vector. The style function will render all layers from the glStyle object that use the specified source, or a subset of layers from the same source. The source needs to be a "type": "vector", "type": "geojson" or "type": "raster" source.

Parameters

• layer ol.layer.VectorTile OpenLayers layer.
• glStyle (string | Object) Mapbox Style object.
• source string source key or an array of layer ids from the Mapbox Style object. When a source key is provided, all layers for the specified source will be included in the style function. When layer ids are provided, they must be from layers that use the same source.
• path string Path of the style file. Only required when a relative path is used with the "sprite" property of the style. (optional, default undefined)
• resolutions Array<number> Resolutions for mapping resolution to zoom level. (optional, default undefined)

Returns Promise Promise which will be resolved when the style can be used for rendering.

applyBackground

Applies properties of the Mapbox Style's first background layer to the map.

Parameters

• map ol.Map OpenLayers Map.
• glStyle Object Mapbox Style object.

apply

Loads and applies a Mapbox Style object to an OpenLayers Map. This includes the map background, the layers, the center and the zoom.

The center and zoom will only be set if present in the Mapbox Style document, and if not already set on the OpenLayers map.

Layers will be added to the OpenLayers map, without affecting any layers that might already be set on the map.

Layers added by apply() will have two additional properties:

• mapbox-source: The id of the Mapbox Style document's source that the OpenLayers layer was created from. Usually apply() creates one OpenLayers layer per Mapbox Style source, unless the layer stack has layers from different sources in between.
• mapbox-layers: The ids of the Mapbox Style document's layers that are included in the OpenLayers layer.

The map returned by this function will have an additional mapbox-style property which holds the Mapbox Style object.

Parameters

• map (ol.Map | HTMLElement | string) Either an existing OpenLayers Map instance, or a HTML element, or the id of a HTML element that will be the target of a new OpenLayers Map.
• style (string | Object) JSON style object or style url pointing to a Mapbox Style object. When using Mapbox APIs, the url must contain an access token and look like https://api.mapbox.com/styles/v1/mapbox/bright-v9?access_token=[your_access_token_here]. When passed as JSON style object, all OpenLayers layers created by apply() will be immediately available, but they may not have a source yet (i.e. when they are defined by a TileJSON url in the Mapbox Style document). When passed as style url, layers will be added to the map when the Mapbox Style document is loaded and parsed.

Returns ol.Map The OpenLayers Map instance that will be populated with the contents described in the Mapbox Style object.

getLayer

Get the OpenLayers layer instance that contains the provided Mapbox Style layer. Note that multiple Mapbox Style layers are combined in a single OpenLayers layer instance when they use the same Mapbox Style source.

Parameters

• map ol.Map OpenLayers Map.
• layerId string Mapbox Style layer id.

Returns ol.layer.Layer layer OpenLayers layer instance.

getSource

Get the OpenLayers source instance for the provided Mapbox Style source.

Parameters

• map ol.Map OpenLayers Map.
• sourceId string Mapbox Style source id.

Returns ol.layer.Layer layer OpenLayers layer instance.

stylefunction

Creates a style function from the glStyle object for all layers that use the specified source, which needs to be a "type": "vector" or "type": "geojson" source and applies it to the specified OpenLayers layer.

Parameters

• olLayer (ol.layer.Vector | ol.layer.VectorTile) OpenLayers layer to apply the style to. In addition to the style, the layer will get two properties: mapbox-source will be the id of the glStyle's source used for the layer, and mapbox-layers will be an array of the ids of the glStyle's layers.
• glStyle (string | Object) Mapbox Style object.
• source (string | Array<string>) source key or an array of layer ids from the Mapbox Style object. When a source key is provided, all layers for the specified source will be included in the style function. When layer ids are provided, they must be from layers that use the same source.
• resolutions Array<number> Resolutions for mapping resolution to zoom level. (optional, default [78271.51696402048,39135.75848201024, 19567.87924100512,9783.93962050256,4891.96981025128,2445.98490512564, 1222.99245256282,611.49622628141,305.748113140705,152.8740565703525, 76.43702828517625,38.21851414258813,19.109257071294063,9.554628535647032, 4.777314267823516,2.388657133911758,1.194328566955879,0.5971642834779395, 0.29858214173896974,0.14929107086948487,0.07464553543474244])
• spriteData Object Sprite data from the url specified in the Mapbox Style object's sprite property. Only required if a sprite property is specified in the Mapbox Style object. (optional, default undefined)
• spriteImageUrl Object Sprite image url for the sprite specified in the Mapbox Style object's sprite property. Only required if a sprite property is specified in the Mapbox Style object. (optional, default undefined)
• getFonts function (Array<string>): string Function that receives a font stack as arguments, and returns a (modified) font stack that is available. Font names are the names used in the Mapbox Style object. If not provided, the font stack will be used as-is. This function can also be used for loading web fonts. (optional, default undefined)

Returns ol.style.StyleFunction Style function for use in ol.layer.Vector or ol.layer.VectorTile.

Building the library

npm install

The resulting binary (olms.js) will be in the dist/ folder. To see the library in action, navigate to example/index.html.