Module @nextgis/control-container

Control Container

size version

@nextgis/control-container is a universal library for creating and managing map controls layout.

It provides a flexible system for placing controls in map corners, creating grouped toolbars, nested panels, and switchable controls.

The library can be used standalone with any map engine and also serves as the foundation for framework-specific integrations:

Leaflet: @nextgis/leaflet-control-container
MapLibre GL JS: @nextgis/maplibre-gl-control-container
OpenLayers: @nextgis/ol-control-container

This allows using the same control layout patterns and APIs across different map engines.

╭───────────────────────────────────────────╮
│ top-left                        top-right │
│                   MAP                     │
│ bottom-left                  bottom-right │
╰───────────────────────────────────────────╯

Installation

npm install @nextgis/control-container

Import

import ControlContainer, {
  createButtonControl,
  createControl,
  createControlContainer,
  createToggleControl,
} from '@nextgis/control-container';

Basic usage

const controlContainer = new ControlContainer({
  map,
});

controlContainer.addTo('#map');

Positions

Available positions:

top-left
top-right
bottom-left
bottom-right

controlContainer.append('<div>Top right</div>', 'top-right');

Add HTML content

controlContainer.append(
  '<div class="map-label">Map tools</div>',
  'top-right',
);

const element = document.createElement('div');
element.textContent = 'Custom element';

controlContainer.append(element, 'top-right');

Order controls

The order option controls the order of controls in the same position or panel.

controlContainer.append('<div>First</div>', 'top-right', 0);
controlContainer.append('<div>Second</div>', 'top-right', 10);

For controls, pass order in the third argument.

controlContainer.addControl(firstControl, 'top-right', {
  order: 0,
});

controlContainer.addControl(secondControl, 'top-right', {
  order: 10,
});

Margin

Controls are attached to the map edge by default. Controls created with bar: true use the standard outer offset automatically. Set margin: false to keep a bar control attached to the map edge. This also works for button and toggle controls.

const panel = createControl(
  {
    onAdd() {
      return undefined;
    },

    onRemove() {},
  },
  {
    bar: true,
    margin: false,
  },
);

Custom control

A control is an object with an onAdd method. The method returns an HTML element.

const customControl = {
  onAdd() {
    const container = document.createElement('div');
    container.textContent = 'Custom control';
    return container;
  },

  onRemove() {},
};

controlContainer.addControl(customControl, 'bottom-right');

Button control

Use createButtonControl for simple button controls.

const button = createButtonControl({
  title: 'Action',
  html: 'Run',
  onClick() {
    console.log('Clicked');
  },
});

controlContainer.addControl(button, 'top-left');

Panels

Use createControl to create a panel for other controls.

A panel can be registered with an id when it is added to the control container. After that, other controls can be placed inside it with { inside: id }.

const panel = createControl(
  {
    onAdd() {
      return undefined;
    },

    onRemove() {},
  },
  {
    orientation: 'vertical',
    gap: 6,
    margin: true,
  },
);

controlContainer.addControl(panel, 'top-right', {
  id: 'tools-panel',
  order: 20,
});

Then add controls inside the panel.

const button = createButtonControl({
  title: 'Button',
  html: 'Button',
  onClick() {
    console.log('Button clicked');
  },
});

controlContainer.addControl(button, { inside: 'tools-panel' }, {
  order: 10,
});

Panel orientation

const horizontalPanel = createControl(
  {
    onAdd() {
      return undefined;
    },

    onRemove() {},
  },
  {
    orientation: 'horizontal', // 'vertical'
    gap: 0,
  },
);

controlContainer.addControl(horizontalPanel, 'top-right', {
  id: 'orientated-panel',
  order: 10,
});

Switch controls

Switch controls allow only one active control in the same group and target container.

const select = createToggleControl({
  html: {
    on: 'Select on',
    off: 'Select',
  },
  switch: 'tools',
  onClick(status) {
    console.log(status);
  },
});

const edit = createToggleControl({
  html: {
    on: 'Edit on',
    off: 'Edit',
  },
  switch: 'tools',
  onClick(status) {
    console.log(status);
  },
});

controlContainer.addControl(select, 'top-left');
controlContainer.addControl(edit, 'top-left');

Switch controls inside a panel

const panel = createControl(
  {
    onAdd() {
      return undefined;
    },

    onRemove() {},
  },
  {
    orientation: 'vertical',
    gap: 4,
  },
);

controlContainer.addControl(panel, 'top-right', {
  id: 'switch-panel',
});

const identify = createToggleControl({
  html: {
    on: 'Identify on',
    off: 'Identify',
  },
  switch: 'panel-tools',
});

const measure = createToggleControl({
  html: {
    on: 'Measure on',
    off: 'Measure',
  },
  switch: 'panel-tools',
});

controlContainer.addControl(identify, { inside: 'switch-panel' }, {
  order: 10,
});

controlContainer.addControl(measure, { inside: 'switch-panel' }, {
  order: 20,
});

Independent switch groups

Use different switch names for independent groups.

const draw = createToggleControl({
  html: 'Draw',
  switch: 'edit-tools',
});

const erase = createToggleControl({
  html: 'Erase',
  switch: 'edit-tools',
});

const info = createToggleControl({
  html: 'Info',
  switch: 'view-tools',
});

`disableOnSecondClick`

const measure = createToggleControl({
  html: {
    on: 'Measure on',
    off: 'Measure',
  },
  switch: 'tools',
  disableOnSecondClick: true,
});

Switch events

panel.onSwitchChange((event) => {
  console.log(event.group);
  console.log(event.status);
  console.log(event.activeControl);
});

Async toggle action

const asyncControl = createToggleControl({
  html: {
    on: 'Enabled',
    off: 'Disabled',
  },
  switch: 'layers',
  async onClick(status) {
    await Promise.resolve(status);
  },
});

Commercial support

Need to fix a bug or add a feature to @nextgis/control-container? We provide custom development and support for this software. Contact us to discuss options!