ol-mapbox-style

ol-mapbox-style bridges the Mapbox/MapLibre Style Specification and OpenLayers, letting you drop a vector-tile style — whether hosted on Mapbox, a MapLibre-compatible provider like MapTiler or OpenFreeMap, or authored by hand — straight into an OpenLayers map without hand-rolling style functions. It parses the glyphs, sprite, sources, and layers definitions from a Style JSON object and converts each into OpenLayers vector, vector-tile, raster, or hillshade layers with equivalent paint and layout properties, including expression-based data-driven styling, sprite icons, and web-font text rendering.

Maintained by the core OpenLayers team, the library exposes both a high-level apply()/MapboxVectorLayer API for full-map or single-layer use, and a lower-level stylefunction() API for applying just the style logic to an existing OpenLayers vector or vector-tile layer, giving projects a path to adopt Mapbox/MapLibre styling incrementally alongside their own OpenLayers layer setup.

What You Get

• A single apply() function that turns a Style URL or object into a fully configured OpenLayers Map or LayerGroup
• MapboxVectorLayer, a drop-in VectorTileLayer that applies a Mapbox/MapLibre style and a single source in one step
• stylefunction() for applying Mapbox/MapLibre paint/layout rules directly to an existing OpenLayers Vector or VectorTile layer
• Support for mapbox://, https://, and inline Style JSON references, including token-based Mapbox Studio styles
• Sprite and glyph handling, with configurable webfont URL templates for text-font rendering without SDF glyphs

Common Use Cases

• Migrating a Mapbox GL project to OpenLayers - teams moving off Mapbox GL JS or MapLibre GL JS can reuse existing vector-tile styles instead of rewriting them as OpenLayers style functions
• Building basemaps from open vector tile providers - developers point apply() at free/open styles like OpenFreeMap or OpenMapTiles-based servers to get a full basemap in a few lines
• Adding a styled vector-tile overlay to an existing OpenLayers app - MapboxVectorLayer lets a single layer be dropped into an established OpenLayers map without re-architecting the rest of the app
• Rendering custom GeoJSON/WFS layers with GL-style rules - stylefunction() applies Mapbox/MapLibre paint and layout expressions to arbitrary vector layers instead of hand-coding OpenLayers style functions

Under The Hood

Architecture apply.js is the central orchestrator, importing OpenLayers primitives (Map, View, layer and source types) alongside internal modules: stylefunction.js converts GL paint/layout rules into OpenLayers style functions, mapbox.js normalizes mapbox:// URLs, rasterfunction.js builds hillshade/raster-op layers, text.js handles web-font glyph resolution, and util.js provides caching and resource fetching. index.js re-exports the public surface (apply, applyStyle, applyBackground, MapboxVectorLayer, stylefunction, styleConfig). MapboxVectorLayer.js composes applyStyle/applyBackground into a single VectorTileLayer subclass, showing the layered design: low-level style-computation primitives feed a higher-level facade. Function and filter caches in util.js avoid recomputing per-feature styles on every render, which matters for vector-tile performance. Because nearly every layer type delegates its rendering logic to stylefunction(), that module is the load-bearing abstraction — a change there ripples through apply.js and MapboxVectorLayer.js alike.

Tech Stack Plain ES modules with almost no runtime dependencies: @maplibre/maplibre-gl-style-spec handles style validation, layer dereferencing, and expression evaluation, and mapbox-to-css-font parses font shorthand; OpenLayers itself is a peerDependency (“ol”: ”*”) rather than bundled, so the library rides whatever ol version the host app already uses. TypeScript is used only for type-checking and generating .d.ts output (via tsc against JSDoc typedefs), Rollup builds the distributable bundle, and Webpack builds the interactive examples site. A custom tasks/style-spec.js script generates and restores type augmentations for the style-spec package around each build. Tests run under Karma + Mocha + should + sinon in a real Chrome instance rather than a DOM-mocking library, and ESLint is configured with the shared @openlayers/eslint-plugin and eslint-config-openlayers used across the wider OpenLayers project.

Code Quality Nine dedicated test files (apply, applyStyle, stylefunction, MapboxVectorLayer, mapbox, util, text, expressions, finalizeLayer) provide an unusually high test-to-source ratio for the ecosystem, and running against real browser rendering gives stronger confidence for canvas-adjacent code than DOM mocks would. JSDoc typedefs throughout (@typedef, @property) supply the type information consumed by tsc for the generated declaration files, in place of native TypeScript source. The pretest script chains lint, typecheck, and a style-spec consistency check before tests run, and a GitHub Actions workflow enforces this on every push. Failures surface through a dedicated ErrorEvent emitted on the layer rather than being silently swallowed.

API Design The public surface is deliberately layered: a high-level apply() for “just make it work” full-map use, a mid-level MapboxVectorLayer for single-layer drop-in use, and a low-level stylefunction() for teams that already manage their own OpenLayers sources and only want the GL style math applied. Naming mirrors the Mapbox/MapLibre spec directly (applyStyle, applyBackground, stylefunction), reducing the translation cost for developers already familiar with Mapbox GL JS or MapLibre GL JS. Getting started requires only a single apply(target, styleUrl) call, with mapbox://, https://, and inline JSON style references all accepted transparently. Documentation is generated via TypeDoc from the JSDoc comments and published at openlayers.org/ol-mapbox-style, backed by a runnable examples gallery covering GeoJSON, WFS, PMTiles, hillshading, ESRI sources, and sprite handling.