Map utilities

These standalone functions from @tomtom-org/maps-sdk/map are tree-shaken out of your bundle unless you import them.

Padded bounds

Panels, sidebars and headers drawn over the map hide part of it. These utilities measure the part that stays visible, so you can centre on it or fit an area inside it.

Each returns null if the visible area is too small.

calculatePaddedBBox

Returns the [west, south, east, north] bounding box of the map area that no given element overlaps.

• map - A TomTomMap or a MapLibre map.
• surroundingElements - The elements over the map, or their DOM selectors.
• paddingPX - Optional extra padding around them and the map edges, 0 by default.

An element spanning the map's full width cuts the area from the top or bottom, and one spanning its full height from the left or right. Any other element, a panel touching one edge included, cuts it from its closest edge. On a rotated or tilted map, the box surrounds the visible area.

The red box below is the area that the left, top and right panels leave free.

calculatePaddedCenter

Returns the [longitude, latitude] centre of calculatePaddedBBox's box, to centre the map where it looks balanced against the panels. It takes map and surroundingElements.

calculateFittingBBox

Returns an expanded bounding box that shows toBeContainedBBox entirely inside the visible area when the map zooms to it. It takes map, toBeContainedBBox, surroundingElements and paddingPX (API reference).

Its latitudes stay within Web Mercator's ±85.051129. For a toBeContainedBBox across the antimeridian, with west greater than east, the returned east passes 180, which fitBounds takes as is.

The target area is blue. The red box is what the map zooms to so the target clears the panels.

import { calculateFittingBBox, TomTomMap } from '@tomtom-org/maps-sdk/map';

const map = new TomTomMap({ mapLibre: { container: 'map' } });

const fittingBBox = calculateFittingBBox({
    map,
    toBeContainedBBox: [4.8, 52.3, 4.95, 52.4],
    surroundingElements: ['#panel-left', '#panel-top', '#panel-right'],
    paddingPX: 20,
});

if (fittingBBox) {
    map.mapLibreMap.fitBounds(fittingBBox);
}

Selectors or elements

surroundingElements takes element references, DOM selectors or a mix:

calculatePaddedBBox({ map, surroundingElements: [document.getElementById('sidebar'), '#header'] });

How it works

1. The SDK measures each element's bounds relative to the map container. It ignores elements outside the container and selectors that match nothing.
2. The visible area shrinks past each element, plus paddingPX, from its closest map edge. That edge is the top or bottom for a full-width bar, the left or right for a full-height bar, and any edge for a floating or corner element.

API reference

• calculatePaddedBBox
• calculatePaddedCenter
• calculateFittingBBox

Related guides and examples

• Calculate map bounds that exclude surrounding UI panels
• Ensure a bounding box is visible between UI panels