# @nextgis/control-container

> Placing control elements in the corners of the map container

Latest version **4.1.1** (published 2026-11-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install @nextgis/control-container
pnpm add @nextgis/control-container
yarn add @nextgis/control-container
bun add @nextgis/control-container
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.1.1 |
| Published | 2026-11-13 |
| First published | 2020-03-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 365.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 31 |
| Author | NextGIS |
| Maintainers | rendrom, maximdubinin, karavanjo |
| Keywords | NextGIS, MAP |

## Links

- npm: https://www.npmjs.com/package/@nextgis/control-container
- Repository: https://github.com/nextgis/nextgis_frontend
- Homepage: https://github.com/nextgis/nextgis_frontend/tree/master/packages/control-container#readme
- Issues: https://github.com/nextgis/nextgis_frontend/issues
- npm.io page: https://npm.io/package/@nextgis/control-container

## Dependencies (4)

- [events](https://npm.io/package/events.md) *
- [@nextgis/dom](https://npm.io/package/@nextgis/dom.md) 4.0.2
- [@types/events](https://npm.io/package/@types/events.md) ^3.0.0
- [@nextgis/utils](https://npm.io/package/@nextgis/utils.md) 4.1.1

## Recent versions

- 4.1.1 (latest) — 2026-11-13
- 4.0.2 — 2026-11-05
- 4.0.1 — 2026-11-02
- 4.0.0 — 2026-08-30
- 4.0.0-rc.2 — 2026-08-30
- 4.0.0-rc.1 — 2026-08-29
- 4.0.0-rc.0 — 2026-08-27
- 4.0.0-alpha.8 — 2026-08-25
- 4.0.0-alpha.6 — 2026-08-24
- 4.0.0-alpha.5 — 2026-08-21
- 4.0.0-alpha.2 — 2026-05-28
- 4.0.0-alpha.0 — 2026-05-12
- 3.1.0 — 2026-03-22
- 3.0.0 — 2025-07-26
- 3.0.0-alpha.22 — 2025-05-14
- … 119 more at https://npm.io/package/@nextgis/control-container/versions

## README

# Control Container

![version](https://img.shields.io/npm/v/@nextgis/control-container)

`@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.

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

## Installation

```bash
npm install @nextgis/control-container
```

## Import

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

## Basic usage

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

controlContainer.addTo('#map');
```

## Positions

Available positions:

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

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

## Add HTML content

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

```javascript
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.

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

For controls, pass `order` in the third argument.

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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 }`.

```javascript
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.

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

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

## Panel orientation

```javascript
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.

```javascript
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

```javascript
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.

```javascript
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`

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

## Switch events

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

## Async toggle action

```javascript
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](http://nextgis.com/contact/) to discuss options!

[![http://nextgis.com](https://nextgis.com/img/nextgis.png)](http://nextgis.com)

---
_Source: https://npm.io/package/@nextgis/control-container · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
