Short answer

Layer toggles are the primary interface to a multi-layer Earth data map, and the design rule is simple: the control type must match the layer's logical role. Use radio buttons for things that should never stack (basemaps, alternative interpretations), checkboxes for additive overlays, group layers so the panel reflects how the data is actually used, and pair every toggle with a legend and an opacity control. Implement toggling with setLayoutProperty(..., 'visibility', ...) so layers stay loaded, and offer opacity blending plus a swipe tool for comparison rather than forcing users to stack semi-transparent rasters.

Toggles encode meaning, not just visibility

A toggle does more than show or hide; it tells the user how layers relate. If you give two competing interpretations, say two structural models, independent checkboxes, a user can switch both on and see an incoherent overlay that means nothing. The same two models behind radio buttons say "these are alternatives; pick one." So the first design decision is semantic: for each layer, is it additive (combine freely) or exclusive (one of a set)? That single distinction drives the whole control scheme.

  • Basemaps (satellite, topographic, blank): always radio. One at a time.
  • Reference overlays (roads, labels, boundaries): checkbox, additive.
  • Thematic data (geology, slope, a remote-sensing index): usually checkbox, but mutually exclusive radio when two layers occupy the same visual space and would obscure each other.
  • Alternative interpretations / model runs / dates: radio, because the user should compare them one at a time, not blend them by accident.

Group by task, order by stacking

A flat list of 15 layers is unusable. Group them into labelled sections that mirror the user's workflow, for example Base, Terrain, Geology, Remote sensing, Project. Within the panel, order matters because it should suggest the draw order: basemap at the bottom of the visual stack but conventionally listed at the bottom or top consistently, overlays above. Collapsible groups keep the panel short. The legend for the active thematic layer should be visible without an extra click, because a colour ramp with no legend is decoration, not information.

Implementing toggles in MapLibre

In MapLibre (and Mapbox GL), prefer toggling layout visibility over add/remove. The layer and its source stay loaded, so the toggle is instant and the data is not refetched:

function setLayerVisible(map, layerId, visible) {
  map.setLayoutProperty(layerId, 'visibility', visible ? 'visible' : 'none');
}

For a radio group (e.g. basemaps), hide all members then show the selected one:

function selectBasemap(map, basemapIds, chosenId) {
  basemapIds.forEach(id =>
    map.setLayoutProperty(id, 'visibility', id === chosenId ? 'visible' : 'none'));
}

Opacity is a separate paint property and is the right tool for blending, not for on/off:

map.setPaintProperty('slope', 'raster-opacity', 0.6);

A thematic layer that is really several MapLibre layers (fill + outline + labels) should toggle as a unit; track the grouping in your app state and iterate the member ids so a single user click flips all of them together.

When deck.gl or 3D enters the picture

For very large feature sets or animated/heatmap-style rendering, deck.gl layers can be toggled by setting their visible prop and re-rendering the layer array, which integrates with MapLibre as an overlay. Reach for 3D (Cesium, 3D Tiles) only when the task genuinely needs it, terrain perception, point clouds, globe context. A 3D scene complicates layer toggling (occlusion, draped vs extruded layers) and often a clean 2D comparison answers the question better. Add 3D for the task, not for the demo.

Comparison: opacity vs swipe

Two ways to compare layers, suited to different questions:

  • Opacity blending suits "how does B relate to A in the same place" (geology over hillshade). Give the top layer an opacity slider.
  • Swipe / spy suits "what changed between two states" (imagery from two dates, before/after a slope model). A vertical swipe divider reveals layer A on one side and B on the other, which reads change far more clearly than two transparent rasters fighting for the same pixels.

For change detection specifically, swipe almost always beats stacking, because superimposed semi-transparent layers blend the two signals into a muddy third image that represents neither.

Keep uncertainty and provenance one click away

A polished toggle panel can imply a confidence the data does not have. Attach a small info/metadata affordance to each layer that exposes source, date, resolution, and any confidence field. When a thematic layer is interpolated or low-confidence in places, say so, ideally with a confidence overlay the user can toggle, so the interface does not flatten the science into a clean lie.

Common pitfalls and why they happen

  • Checkboxes for mutually exclusive layers. Users stack alternatives that should not coexist and read meaning into the overlap. Use radio for one-of-a-set.
  • Add/remove layers on every toggle. This refetches sources and stutters. Toggle visibility instead; the data stays resident.
  • A flat, ungrouped layer list. Beyond ~6 layers it becomes unscannable. Group by task and make groups collapsible.
  • Colour ramps with no legend. The user cannot decode values, so the layer is decorative. Show the active legend by default.
  • Stacking transparent rasters for change detection. Blending two dates produces a third meaningless image. Use a swipe tool.
  • Defaulting to 3D. It adds occlusion and toggle complexity; use it only when the task needs depth.

QA validation

Confirm each layer's control type matches its role (radio for exclusive, checkbox for additive); grouped layers toggle as a unit; the active thematic legend is visible without extra clicks; toggling uses visibility not add/remove; comparison offers opacity and swipe appropriately; and every layer exposes source, date, and confidence metadata.

Bathyl perspective

We treat the layer panel as part of the analysis, not chrome around it. The control type carries meaning, so radio versus checkbox is a deliberate choice per layer; comparison defaults to swipe for change and opacity for context; and provenance is always one click away. The goal is an interface that lets a technical user inspect Earth data freely without ever being misled about what the layers can and cannot support.

Related reading

Sources