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 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 text defined in the Mapbox Style object. It is the responsibility of the application to load other fonts.
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.
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 id
s 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 id
s
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
)
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.
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
JSON
(string | Object) 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]
.
Returns ol.Map The OpenLayers Map instance that will be populated with the
contents described in the Mapbox Style object.
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
.