What is ol-mapbox-style?
The ol-mapbox-style package allows you to use Mapbox Style objects with OpenLayers. It provides functionality to apply Mapbox styles to OpenLayers maps, making it easier to integrate Mapbox's rich styling capabilities with the OpenLayers mapping library.
What are ol-mapbox-style's main functionalities?
Apply Mapbox Style to OpenLayers Map
This feature allows you to apply a Mapbox style to an OpenLayers map. The code sample demonstrates how to use the `apply` function to load a Mapbox style from a URL and apply it to a map element with the ID 'map'.
const olms = require('ol-mapbox-style');
olms.apply('map', 'https://api.mapbox.com/styles/v1/mapbox/streets-v11?access_token=YOUR_MAPBOX_ACCESS_TOKEN');
Apply Mapbox Style to OpenLayers Layer
This feature allows you to apply a Mapbox style to a specific OpenLayers layer. The code sample demonstrates how to use the `applyStyle` function to load a Mapbox style from a URL and apply it to a vector layer.
const olms = require('ol-mapbox-style');
const layer = new ol.layer.Vector();
olms.applyStyle(layer, 'https://api.mapbox.com/styles/v1/mapbox/streets-v11?access_token=YOUR_MAPBOX_ACCESS_TOKEN');
Apply Mapbox Style from JSON
This feature allows you to apply a Mapbox style from a JSON object directly to an OpenLayers map. The code sample demonstrates how to use the `apply` function with a JSON style object instead of a URL.
const olms = require('ol-mapbox-style');
const styleJson = { /* JSON style object */ };
olms.apply('map', styleJson);
Other packages similar to ol-mapbox-style
mapbox-gl
The mapbox-gl package is the official Mapbox GL JS library for rendering interactive maps from vector tiles and Mapbox styles. Unlike ol-mapbox-style, which integrates Mapbox styles with OpenLayers, mapbox-gl is a standalone library that provides its own map rendering capabilities.
openlayers
The openlayers package is the core library for OpenLayers, which provides a high-performance, feature-packed library for all your mapping needs. While it does not natively support Mapbox styles, it can be extended with packages like ol-mapbox-style to achieve similar functionality.
leaflet
The leaflet package is a popular open-source JavaScript library for mobile-friendly interactive maps. It has its own ecosystem of plugins for various functionalities, including support for Mapbox tiles and styles, but it does not natively integrate with OpenLayers like ol-mapbox-style does.
ol-mapbox-style
Create OpenLayers maps from Mapbox Style Specification objects.
Getting started
Installation
To use the library in an application with an npm based dev environment, install it with
npm install ol-mapbox-style
When installed this way, just import the ol-mapbox-style module, like in the usage example below. To use a standalone build of ol-mapbox-style, just include 'dist/olms.js' on your HTML page, and access the exported functions from the global olms
object (e.g. olms.apply()
, olms.applyBackground()
). Note that the standalone build depends on the legacy build of OpenLayers.
ol-mapbox-style v9 requires OpenLayers version >= 7 < 8.
ol-mapbox-style v8 requires OpenLayers version >= 6.13.0 < 7.
Usage
See the API section for the full documentation.
The code below creates an OpenLayers map from Mapbox's Bright v9 style, using a https://
url:
import apply from 'ol-mapbox-style';
apply('map', 'https://api.mapbox.com/styles/v1/mapbox/bright-v9?access_token=YOUR_MAPBOX_TOKEN');
To assign style and source to a layer only, use applyStyle()
. mapbox://
urls are also supported:
import {applyStyle} from 'ol-mapbox-style';
import VectorTileLayer from 'ol/layer/VectorTile.js'
const layer = new VectorTileLayer({declutter: true});
applyStyle(layer, 'mapbox://styles/mapbox/bright-v9', {accessToken: 'YOUR_MAPBOX_TOKEN'});
To apply the properties of the Mapbox Style's background
layer to the map or a VectorTile
layer, use the applyBackground()
function.
There is also a low-level API available. To create a style function for individual OpenLayers vector or vector tile layers, use the stylefunction
module:
import {stylefunction} from 'ol-mapbox-style';
import VectorLayer from 'ol/layer/Vector.js';
import VectorSource from 'ol/source/Vector.js';
import GeoJSON from 'ol/format/GeoJSON.js';
const 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');
});
});
Note that this low-level API does not create a source for the layer, and extra work is required to set up sprite handling for styles that use icons.
Compatibility notes
Font handling
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.
Building the library
npm run build
The resulting distribution files will be in the dist/
folder. To see the library in action, navigate to dist/index.html
.
To run test locally, run
npm test
For debugging tests in the browser, run
npm run karma
and open a browser on the host and port indicated in the console output (usually http://localhost:9876/) and click the 'DEBUG' button to go to the debug environment.
API