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

LayerSwitcher
- Parameters
- setMap
  - Parameters
- showPanel
- hidePanel
- renderPanel
- renderPanel
  - Parameters
- isBaseGroup
  - Parameters
- getGroupsAndLayers
  - Parameters
- forEachRecursive
  - Parameters
- uuid
LayerSwitcher#show
LayerSwitcher#hide
Options
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.

[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
}

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

Files

README.md

Latest commit

History

README.md

File metadata and controls

OpenLayers LayerSwitcher

Examples

Changelog

Install

Browser

JS

CSS

Parcel, Rollup, Webpack, TypeScript etc.

JS

CSS

TypeScript type definition

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

Tests

License

Also see

Publishing

Beta release