OpenLayers LayerSwitcher

Grouped layer list control for an OpenLayer map.

To be shown in the LayerSwitcher layers should have a title property; base layers should have a type property set to base. Group layers (LayerGroup) can be used to visually group layers together; a group with a fold property set to either open or close will be displayed with a toggle.

See API documentation and Examples for usage.

Compatible with OpenLayers version 3, 4, 5 and 6 (see note in Install - Parcel, Webpack etc. regarding installing the appropriate version of ol-layerswitcher for OpenLayers).

Examples

The examples demonstrate usage and can be viewed online thanks to raw.githack.com:

• Basic usage
  • Create a layer switcher control. Each layer to be displayed in the layer switcher has a title property as does each Group; each base map layer has a type: 'base' property. See the comments in examples/layerswitcher.js for other layer/ group options including combine and fold.
• Add layer
  • Add a layer to an existing layer group after the layer switcher has been added to the map.
• Scrolling
  • Makes the panel scroll vertically, the height of the layer switcher is controlled by setting the max-height style (see examples/scroll.css) and it's position relative to the bottom of the map (see the .layer-switcher.shown selector in dist/ol-layerswitcher.css).
• Side bar
  • Demonstrates rendering the layer tree into a Turbo87/sidebar-v2 pane. This uses the static method LayerSwitcher.renderPanel which can be used to render the layer tree to any arbitrary HTML element.
• Collapse groups
  • Shows the effect of setting the fold property of a Group to allow the group to be collapsed.
• Selectable Groups
  • Demonstrates setting the groupSelectStyle option which determines if groups have a checkbox and how toggling a groups visibility affects it's children. The demo includes the ability to change the groupSelectStyle to easily see the effect of the different values.
• Bundling with ol package (Browserify, Parcel, Webpack...)
• Activate panel with click
  • Shows setting activationMode: 'click' (default is 'mouseover'). When using this mode the control's button persists in the panel - use collapseLabel to set its text (default is collapseLabel: '»', see the comments in examples/layerswitcher.js for other examples). The close button is positioned to the left of the panel, to move it to the right add the following to your CSS:

.layer-switcher.shown.layer-switcher-activation-mode-click {
  padding-right: 34px;
}
.layer-switcher.shown.layer-switcher-activation-mode-click > button {
  right: 0;
  border-left: 0;
}

• Start with panel active

  • Example with the layer switcher starting open using startActive: true. Here shown in combination with `activationMode: 'click' which, while not required, is probably the most common scenario.

• Multiple maps

  • Demonstrates creating two independent maps each with a layer switcher control.

• To use the layer switcher with the ol package and a module bundler such as Browserify, Parcel, Webpack, TypeScript etc. see ol-layerswitcher-examples.

The source for all examples can be found in examples.

Changelog

See CHANGELOG for details of changes in each release.

Install

Browser

JS

Load ol-layerswitcher.js after OpenLayers. The layerswitcher control is available as LayerSwitcher or ol.control.LayerSwitcher.

<script src="https://unpkg.com/ol-layerswitcher@4.1.2"></script>

CSS

<link rel="stylesheet" href="https://unpkg.com/ol-layerswitcher@4.1.2/dist/ol-layerswitcher.css" />

Parcel, Rollup, Webpack, TypeScript etc.

NPM package: ol-layerswitcher.

JS

Install the package via npm

npm install ol-layerswitcher --save

⚠️ If you're using the ol package prior to v5 you'll need to install ol-layerswitcher@v2.0.0.

CSS

The CSS file ol-layerswitcher.css can be found in ./node_modules/ol-layerswitcher/dist

To use the layerswitcher with the ol package and a module bundler such as Parcel, Webpack etc. see ol-layerswitcher-examples.

TypeScript type definition

TypeScript types are shipped with the project in the dist directory and should be automatically used in a TypeScript project. Interfaces are provided for LayerSwitcher Options as well as extend interfaces for BaseLayer and LayerGroup Options that include the LayerSwitcher specific properties such as title, combine etc.

These interfaces can be imported into your project and used to cast object literals passed to layer or group constructors:

import 'ol/ol.css';
import 'ol-layerswitcher/dist/ol-layerswitcher.css';

import Map from 'ol/Map';
import View from 'ol/View';
import LayerGroup from 'ol/layer/Group';
import LayerTile from 'ol/layer/Tile';
import SourceOSM from 'ol/source/OSM';
import SourceStamen from 'ol/source/Stamen';

import LayerSwitcher from 'ol-layerswitcher';
import { BaseLayerOptions, GroupLayerOptions } from 'ol-layerswitcher';

const osm = new LayerTile({
  title: 'OSM',
  type: 'base',
  visible: true,
  source: new SourceOSM()
} as BaseLayerOptions);

const watercolor = new LayerTile({
  title: 'Water color',
  type: 'base',
  visible: false,
  source: new SourceStamen({
    layer: 'watercolor'
  })
} as BaseLayerOptions);

const baseMaps = new LayerGroup({
  title: 'Base maps',
  layers: [osm, watercolor]
} as GroupLayerOptions);

const map = new Map({
  target: 'map',
  layers: [baseMaps]
});

const layerSwitcher = new LayerSwitcher({
  reverse: true,
  groupSelectStyle: 'group'
});
map.addControl(layerSwitcher);

See BaseLayerOptions and GroupLayerOptions.

API

Table of Contents

• LayerSwitcher
  • Parameters
  • setMap
    • Parameters
  • showPanel
  • hidePanel
  • renderPanel
  • renderPanel
    • Parameters
  • isBaseGroup
    • Parameters
  • getGroupsAndLayers
    • Parameters
  • forEachRecursive
    • Parameters
  • uuid
• LayerSwitcher#show
• LayerSwitcher#hide
• Options
  • activationMode
  • startActive
  • label
  • collapseLabel
  • tipLabel
  • collapseTipLabel
• RenderOptions
  • groupSelectStyle
  • reverse
• GroupSelectStyle
• BaseLayerOptions
  • title
  • type
• GroupLayerOptions
  • combine
  • fold

LayerSwitcher

Extends ol/control/Control~Control

OpenLayers LayerSwitcher Control, displays a list of layers and groups associated with a map which have a title property.

To be shown in the LayerSwitcher panel layers must have a title property; base map layers should have a type property set to base. Group layers (LayerGroup) can be used to visually group layers together; a group with a fold property set to either 'open' or 'close' will be displayed with a toggle.

See BaseLayerOptions for a full list of LayerSwitcher properties for layers (TileLayer, ImageLayer, VectorTile etc.) and GroupLayerOptions for group layer (LayerGroup) LayerSwitcher properties.

Layer and group properties can either be set by adding extra properties to their options when they are created or via their set method.

Specify a title for a Layer by adding a title property to it's options object:

var lyr = new ol.layer.Tile({
  // Specify a title property which will be displayed by the layer switcher
  title: 'OpenStreetMap',
  visible: true,
  source: new ol.source.OSM()
});

Alternatively the properties can be set via the set method after a layer has been created:

var lyr = new ol.layer.Tile({
  visible: true,
  source: new ol.source.OSM()
});
// Specify a title property which will be displayed by the layer switcher
lyr.set('title', 'OpenStreetMap');

To create a LayerSwitcher and add it to a map, create a new instance then pass it to the map's addControl method.

var layerSwitcher = new LayerSwitcher({
  reverse: true,
  groupSelectStyle: 'group'
});
map.addControl(layerSwitcher);

Parameters

• opt_options Options? LayerSwitcher options, see LayerSwitcher Options and RenderOptions which LayerSwitcher Options extends for more details.

setMap

Set the map instance the control is associated with.

Parameters

• map Map The map instance.

Returns void

showPanel

Show the layer panel. Fires 'show' event.

Returns void

hidePanel

Hide the layer panel. Fires 'hide' event.

Returns void

renderPanel

Re-draw the layer panel to represent the current state of the layers.

Returns void

renderPanel

[static] - Re-draw the layer panel to represent the current state of the layers.

Parameters

• map Map The OpenLayers Map instance to render layers for
• panel HTMLElement The DOM Element into which the layer tree will be rendered
• options RenderOptions Options for panel, group, and layers

Returns void

isBaseGroup

[static] - Determine if a given layer group contains base layers

Parameters

• grp LayerGroup Group to test

Returns boolean

getGroupsAndLayers

[static] - Get an Array of all layers and groups displayed by the LayerSwitcher (has a 'title' property) contained by the specified map or layer group; optionally filtering via filterFn

Parameters

• grp (Map | LayerGroup) The map or layer group for which layers are found.
• filterFn function (lyr: BaseLayer, idx: number, arr: Array<BaseLayer>): boolean Optional function used to filter the returned layers

Returns Array<BaseLayer>

forEachRecursive

[static] - Call the supplied function for each layer in the passed layer group recursing nested groups.

Parameters

• lyr (Map | LayerGroup) The layer group to start iterating from.
• fn function (lyr: BaseLayer, idx: number, arr: Array<BaseLayer>): void Callback which will be called for each layer found under lyr.

Returns void

uuid

[static] - Generate a UUID Adapted from http://stackoverflow.com/a/2117523/526860

Returns String UUID

LayerSwitcher#show

Event triggered after the panel has been shown. Listen to the event via the on or once methods; for example:

var layerSwitcher = new LayerSwitcher();
map.addControl(layerSwitcher);

layerSwitcher.on('show', (evt) => {
  console.log('show', evt);
});

LayerSwitcher#hide

Event triggered after the panel has been hidden.

Options

Extends ControlOptions, RenderOptions

[interface] - LayerSwitcher Options specified when creating a LayerSwitcher instance, extends RenderOptions and Control Options.

Default values:

{
  activationMode: 'mouseover',
  startActive: false,
  label: ''
  collapseLabel: '\u00BB',
  tipLabel: 'Legend',
  collapseTipLabel: 'Collapse legend',
  groupSelectStyle: 'children',
  reverse: false
}

activationMode

Event to use on the button to collapse or expand the panel. Defaults to "mouseover".

Type: ("mouseover" | "click")

startActive

Whether panel is open when created. Defaults to false.

Type: boolean

label

Text label to use for the button that opens the panel. E.g.: '' (default), '«' or '\u00AB', '+'.

Type: string

collapseLabel

Text label to use for the button that closes the panel. E.g.: '»' (default) or '\u00BB', '-' or '\u2212'. Only used when activationMode: 'mouseover'.

Type: string

tipLabel

The button tooltip when the panel is closed.

Type: string

collapseTipLabel

The button tooltip when the panel is open.

Type: string

RenderOptions

[interface] - LayerSwitcher Render Options as passed to LayerSwitcher constructor as part of Options and static LayerSwitcher.renderPanel

groupSelectStyle

How layers and groups behave when a given layer's visibility is set. See GroupSelectStyle type for possible values.

Type: GroupSelectStyle

reverse

Should the order of layers in the panel be reversed?

Type: boolean

GroupSelectStyle

[type] - How layers and groups behave when a given layer's visibility is set, either:

• 'none' - groups don't get a checkbox,
• 'children' (default) groups have a checkbox and affect child visibility or
• 'group' groups have a checkbox but do not alter child visibility (like QGIS).

Type: ("none" | "children" | "group")

BaseLayerOptions

Extends ol/layer/Base~Options

[interface] - Extended BaseLayer Options interface adding properties used by the LayerSwitcher

title

Title of the layer displayed in the LayerSwitcher panel

Type: string

type

Type of the layer, a layer of type: 'base' is treated as a base map layer by the LayerSwitcher and is displayed with a radio button

Type: "base"

GroupLayerOptions

Extends ol/layer/Group~Options, BaseLayerOptions

[interface] - Extended LayerGroup Options interface adding properties used by the LayerSwitcher.

combine

When true child layers are not shown in the Layer Switcher panel

Type: boolean

fold

Fold state of the group, if set then the group will be displayed with a button to allow the user to show/ hide the child layers.

Type: ("open" | "close")

Tests

To run the tests you'll need to install the dependencies via npm. In the root of the repository run:

npm install

Then run the tests by opening test/index.html in a browser.

License

MIT (c) Matt Walker.

Also see

If you find the layer switcher useful you might also like the ol-popup.

Publishing

npm run build
# Open ./tests/ in browser
# Open examples and manually test
# Determine new version number (check current with `git tag --list`, check npm and GitHub)
# Update version number in `package.json` and `README.md`
# Add entry to CHANGELOG.md
git commit package.json CHANGELOG.md README.md
git tag vX.Y.Z
git push origin master --tags
npm publish

Beta release

npm run build
# Tests/ examples
# Beta version should be X.Y.Z-beta.N
# Update version number in `package.json` and `README.md`
# Add entry to CHANGELOG.md
git commit package.json CHANGELOG.md README.md
git tag vX.Y.Z-beta.N
git push --tags
npm publish --tag beta
# To list all version on npm
npm show ol-layerswitcher versions --json