With more than 160 pull requests from 14 contributors, this release brings improved support for using OpenLayers in Node.js environments, a new WKB (well known binary) format, TypeScript declarations in the ol package, and more efficient vector tile rendering. In addition, several examples were added or improved, and many bugs were fixed.

Upgrade notes

Included TypeScript declarations

The ol package now includes TypeScript declarations as *.d.ts files.

If desired, e.g. when you don't want to adjust your code after upgrading from a previous version where you used @types/ol, you can opt out of the included types and use third-party types by specifying aliases in the compilerOptions section of tsconfig.json, e.g.

    "baseUrl": "./",
    "paths": {
      "ol": ["node_modules/@types/ol"],
      "ol/*": ["node_modules/@types/ol/*"]
    },

Deprecation of undefinedHTML option for the MousePosition control

The undefinedHTML option for the MousePosition control has been deprecated and will be removed in a future release. Use the new placeholder option instead.

New placeholder option for the MousePosition control

When the mouse position is not available, the control renders a non-breaking space. To render something else instead, set the placeholder option. If you want to retain the last position when the mouse leaves the viewport, set placeholder: false. This will be the default behavior in a future release.

The placeholder option has no effect if the deprecated undefinedHTML option is also used. You should use the placeholder option instead of undefinedHTML.

Deprecation of image render mode for vector tile layers

renderMode: 'image' for vector tile layers has been deprecated. Applications continue to work, but a warning will be issued to the console. To get rid of the warning, simply remove the renderMode option.

New features and improvements

• New create-ol-app package to create a new app with an OpenLayers map.
• Improved rendering quality of regular shapes and circles.
• New placeholder option for better control of the MousePosition control's output.
• TypeScript generated .d.ts files are now included in the ol package.
• Improved zDirection option on tile sources to control when the tile z changes on fractional zoom levels.
• Template mode for the TileDebug source for better debugging of tile coordinate issues.
• More efficient vector tile rendering to save battery on mobile devices and memory.
• New 'properties' option on layers for easier use of arbitrary properties in typed environments.
• Hit detection support when using OffscreenCanvas and workers for rendering.
• The ol package now uses "type": "module" in package.json for easier use of OpenLayers in Node.js.
• New WKB (Well-Known Binary) format parser and serializer.
• Console warning when map container's width or height are zero.
• New snapToPointer option on the Modify interaction to control user experience when clicking a vertex far away from its center.

List of all changes

• #12442 - Fix layer render extent when it is not at all in view (@MoonE)
• #12492 - Use create-ol-app to create a new app (@tschaub)
• #12467 - Fixes / improvements for RegularShape (@MoonE)
• #12491 - Add a new placeholder option and deprecate undefinedHTML for the mouse position control (@tschaub)
• #12430 - Event listener typing (@simonseyock)
• #12488 - MousePosition: allow rendering of empty string (@JakobMiksch)
• #12464 - Make zDirection option available for all tile sources (@mike-000)
• #12489 - Update ol-mapbox-style to v6.4.0 (@ahocevar)
• #12484 - Add GeoSolutions as a monthly sponsor (@tschaub)
• #12480 - Fix gap in tiles due to floating point math (@MoonE)
• #12453 - Allow multiple LinearRings per innerBoundaryIs (@MoonE)
• #12466 - Fix getVectorContext on TileLayer with pixelRatio != 1 (@MoonE)
• #12463 - Improve animation examples (@MoonE)
• #12459 - Fix documentation for GML class. (@simonseyock)
• #12455 - Consistent use of quotes in example description (@mike-000)
• #12373 - Rework TileDebug to allow TMS coordinates and to fix reprojection (@mike-000)
• #12441 - Style-based measure example (@mike-000)
• #12438 - typo (@jipexu)
• #12431 - Add tsc-generated type definitions for opt-in (@ahocevar)
• #12417 - Use html2canvas instead of dom-to-image (@ahocevar)
• #12413 - Fix hitdetection image invalidation (@MoonE)
• #12405 - VectorTile getSourceTiles behaviour with loading source tiles (@ahocevar)
• #12212 - Ignore empty gx:coord elements in KML files (@voegelas)
• #12418 - Fix icon tinting with pixelRatio < 1 (@MoonE)
• #12409 - Fix WMTS wrapX detection if WGS84BoundingBox is not set (@M393)
• #12237 - Fix Modify interaction with hitDetection (@M393)
• #12416 - Use generics to limit event types in on(), once() and un() (@ahocevar)
• #12408 - Do not fire modifystart when nothing is being modified (@ahocevar)
• #12414 - Replace getChangeEventType() with add/removeChangeListener methods (@ahocevar)
• #12194 - Respect pixel ratio with immediate render (@MoonE)
• #12298 - Fix JSDoc generated links (@tschaub)
• #12231 - Move tolerance should not increase with higher pixel ratio (@MoonE)
• #12282 - Fix DragZoom with view padding (@M393)
• #12223 - generic source parameters for options (@simonseyock)
• #12219 - Add 'properties' to Layer constructors (@ahocevar)
• #12284 - Layers should inherit group z-index (@MoonE)
• #12304 - New example: Scale and Rotate using Modify Interaction (@mike-000)
• #12378 - Correct .split() calls to only split numeric srid for ArcgisRest (@mike-000)
• #12393 - Scale up static Image and round to nearest pixel to avoid rounding errors (@mike-000)
• #12394 - Ensure VectorSource getUrl() corresponds to last setUrl() (@mike-000)
• #12357 - Use calculateElevation function in Shaded Relief example (@mike-000)
• #12375 - Fix Vector Tile Selection example on old browsers (@mike-000)
• #12364 - Simpler and faster VectorTile loading (@ahocevar)
• #12359 - Fix broken link in docs (@mike-000)
• #12330 - Do not require PointerEvent constructor (@ahocevar)
• #12355 - document descending order of resolutions array (@simonseyock)
• #12349 - Document the input to an attribution function (@mike-000)
• #12340 - Fix raster example tooltips (@MoonE)
• #12338 - Do not use proto to restore instances after main thread - worker transfer (@ahocevar)
• #12339 - Fix confusing import in Mapbox Style example (@mike-000)
• #12306 - Fix layer canvas reuse (@M393)
• #12334 - More consistent example for ol/layer/MapboxVector (@MoonE)
• #12315 - Improve attribution accessibility (@MoonE)
• #12313 - Hitdetection offscreencanvas worker (@vittrup88)
• #12297 - Add condition option to Translate interaction (@mike-000)
• #12283 - Add link to yey'maps as a sponsor (@tschaub)
• #12277 - Lint the index file after generating the legacy build (@tschaub)
• #12266 - Fix legacy build (@MoonE)
• #12273 - Use lowercase module names for modules without a default export (@tschaub)
• #12264 - Run selected format tests in Node (@tschaub)
• #12263 - Fix the next-dev-version.js script (@tschaub)
• #12241 - Use modules everywhere (@tschaub)
• #12250 - Do not set projection extent in WMTS optionsFromCapabilities (@mike-000)
• #12259 - Make it clearer what fails in webgl point layer test (@tschaub)
• #12258 - Following the recommendation to run on a merge commit (@tschaub)
• #12251 - Test reorganization (@tschaub)
• #12249 - Update the name of the build job (@tschaub)
• #12248 - Avoid naming required checks with a changing version (@tschaub)
• #12238 - Use proxy url as interim fix for mixed content in the MapGuide example (@mike-000)
• #12239 - Add example showing how to Draw and Modify geodesic circles (@mike-000)
• #12247 - Build on Node 16 and update dev dependencies (@tschaub)
• #12230 - Fix @types/estree version and remove skipLibCheck: false from tsconfig (@ahocevar)
• #11952 - Draw 800km circles around both poles in Tissot example (@mike-000)
• #12229 - Prevent TypeScript Compiler from erroring out due to lib checks (@ahocevar)
• #12224 - Use a better maintained loader for test coverage (@ahocevar)
• #12227 - Fix event handling for map in shadow root (@MoonE)
• #12214 - Do not set invalid style (@ahocevar)
• #12216 - Fix ZoomSlider layout (@MoonE)
• #12217 - Fix building of examples with latest copy-webpack-plugin (@MoonE)
• #12198 - Add attributionsCollapsible option to source/TileWMS and source/WMTS (@sbx320)
• #12176 - Allow private class members to be mangled (@bz2)
• #12178 - Add WKB (Well-Known Binary) format (@kikuchan)
• #12180 - Fix rendering of MultiPolygon text styles (@MoonE)
• #12185 - MapBrowserEvent#preventDefault() behaves the same as with native events (@ahocevar)
• #12181 - Build for ie11 again (@MoonE)
• #12028 - Overview map no initial target (@MoonE)
• #12175 - Refresh available examples before each compilation (@MoonE)
• #12172 - Fix icon displacement (@ahocevar)
• #12170 - Link to GitHub sponsors page (@tschaub)
• #12168 - VectorSource#getFeatures() consistently returns a new array (@ahocevar)
• #12164 - Fix offscreen-canvas example (@ahocevar)
• #12163 - Fix how renderMode is derived from options (@ahocevar)
• #12137 - Load less tiles when low on frame budget (@ahocevar)
• #12143 - Fix singleclick and doubleclick events (@ahocevar)
• #12141 - call the success callback after the features are added (@kikitte)
• #12135 - Update webpack (@tschaub)
• #11405 - Fixes extent calculation in WMTS optionsFromCapabilities when BoundingBox exists (@amir-ba)
• #12128 - Package lockfile version update (@tschaub)
• #12102 - Update eslint-config-openlayers (@simonseyock)
• #12089 - Fix common misspellings (@marcjansen)
• #12062 - Fix kml-timezone example tooltip (@M393)
• #12088 - Fix broken url/description of ImageArcGISRest documentation (@dbretschneider)
• #12083 - Simplify event handling for custom elements (@ahocevar)
• #12080 - Add a minimum distance config to the cluster source (@MoonE)
• #12084 - Only preventDefault when event is cancelable (@ahocevar)
• #12079 - Change IGN WMTS example to use PLANIGNV2 layer (@mike-000)
• #12016 - Fix VectorLayer hitdetect problems (@MoonE)
• #11845 - Call finishCondition for all types for Draw interaction (@MoonE)
• #12066 - Always return Promise from getFeatures (@M393)
• #12057 - TileQueue tests with events instead of setTimeout (@ahocevar)
• #12058 - Fix map loading for basemap.at and add attributions (@M393)
• #12024 - Add a tile grid method for getting a tile range given a tile coord and zoom level (@tschaub)
• #12023 - Avoid collisions between user variables and internal names in WebGL shaders (@tschaub)
• #12027 - Update / fix links to external ressources (@MoonE)
• #11996 - Update links to external resources (@MoonE)
• #12025 - Remove watch option from webpack serve script (@fredj)
• #12021 - Allow source projection to be set after construction (@tschaub)
• #12022 - Throw when WebGL style parsing encounters an unexpected type (@tschaub)
• #12020 - Fix WebGL buffer deletion (@tschaub)
• #12018 - Only render vector tile image when needed (@ahocevar)
• #12019 - Always use same order for renderedTiles (@ahocevar)
• #12012 - Fix documentation for account parameter in ol/source/CartoDB (@geraldo)
• #11995 - Fix hitdetect inaccuracy for VectorLayer's getFeatures (@MoonE)
• #11990 - Remove renderMode: 'image' for vector tile layers (@ahocevar)
• #12007 - Report all features being modified (@ahocevar)
• #11991 - Fix some typings in format and format/WKT (@simonseyock)
• #11992 - Improve measure example ux (@MoonE)
• #11974 - Fix polyfill inconsistencies (@mike-000)
• #11987 - Respect opacity for vector instructions (@ahocevar)
• #11989 - Correct pixel ratio descriptions (@mike-000)
• #11988 - Warn when map container's width or height are zero (@ahocevar)
• #11978 - Add snapToPointer option (@ahocevar)
• #11981 - Add descriptions for properties. (@simonseyock)
• #11979 - Jsdoc types syntax (@simonseyock)
• #11977 - More consistent JSDoc syntax (@tschaub)
• #11975 - jsdoc linting (@simonseyock)
• #11967 - Simplify popup positioning in Icon Scale example (@mike-000)
• #11954 - Simplify icon example (@ahocevar)
• #11965 - Handle view rotation in d3 Integration example (@mike-000)
• #11950 - Make polygons in the GeoJSON example comply to GeoJSON specification (@mike-000)
• #11948 - Improve layer typings (@simonseyock)
• #11955 - Fix URLs in ol/source/CartoDB pointing to CartoDB API docs (@geraldo)
• #11947 - Demonstrates how to get the coordinates been clustered. (@yukihiratype2)
• #11938 - Take view padding into account for calculateExtent() (@ahocevar)
• #11941 - Fix loading flag for vector loading strategies (@ahocevar)
• #11925 - Mention unit of radius for Polygon.circular() (@kannes)
• #11914 - Fix image with text decluttering (@ahocevar)
• #11911 - Do not clip declutter executor groups (@ahocevar)
• #11856 - Use tilegrid extent as default attributionExtent for TileJSON (@mike-000)
• #11900 - Update pratique key to choisirgeoportail in the IGN WMTS example (@mike-000)
• #11913 - Handle null geometry in TopoJSON (@mike-000)
• #11893 - Pass the renderer function to the cloned style (@mjjurkoic)
• #11901 - Fix handling of VectorTile renderBuffer (@ahocevar)
• #11899 - Update HERE Map Tile API example to use API key (@mike-000)
• #11890 - Fix WFS writeFilter (@walkermatt)
• #11892 - Restore stopClick functionality (@ahocevar)
• #11882 - Improved documentation for feature load events. (@simonseyock)
• #11886 - Throw an error if shaders fail to compile or program fails to link (@tschaub)
• #11874 - Hit lines even if they are dashed (@tschaub)
• #11873 - Update Mapbox-gl Layer example to mapbox-gl-js version 1.13.0 and add note about why an old version is used (@mike-000)
• #11865 - Use ol/array#includes instead of Array.prototype.includes() (@mike-000)
• #11872 - Legacy build for legacy browsers (@ahocevar)
• #11871 - Fix examples and build for ie11 (@MoonE)