Styling and labels · Angular, React and OpenLayers

Separate label collision groups

Control cross-layer label collisions in OpenLayers vector tiles by assigning independent or shared declutter group identifiers in Angular and React.

Municipality boundaries around Kraków with contrasting municipality and overlay labels in separate groups.
A screenshot of the example. Municipal boundaries: Państwowy Rejestr Granic © GUGiK.

What this example shows

Two vector-tile layers render over Kraków and its surrounding municipalities: a base administrative layer labelling municipality names and a second layer adding a contrasting Overlay label to the same Kraków municipality. A toggle checkbox below the map switches the overlay layer between a dedicated collision group and the base layer’s collision group.

When both layers share a single group, only one of the two labels over Kraków survives the collision test; switching to separate groups keeps each layer decluttered internally and both labels appear.

When you need it

Multi-layer cartographic maps constantly balance legibility against completeness: sometimes user pins, live vehicle callouts or measurement labels must never be suppressed by base-map town names, and vice versa.

Enabling boolean decluttering on every layer throws all text and point symbols into one global collision tree where dense overlays can wipe out essential geographic context—or background labels can hide critical alerts. Named declutter groups give cartographers fine-grained control over which layers compete for screen space and which layers render independently.

The code

The example uses cc-openlayers, my Angular component library for OpenLayers: each aol-… element creates the OpenLayers object it names, updates it from its inputs and disposes of it with the component.

declutter-group.html
<aol-map height="480px" ariaLabel="Kraków municipality label groups">
  <aol-interaction-default />
  <aol-control-defaults />
  <aol-view projection="EPSG:4326" [zoom]="10">
    <aol-coordinate [x]="19.937" [y]="50.0614" srid="EPSG:4326" />
  </aol-view>
  <aol-layer-vectortile
    background="#d1d1d1"
    [declutter]="municipalityDeclutterGroup"
    [renderMode]="'vector'"
    [style]="municipalityStyle"
  >
    <aol-source-ogcvectortile
      [url]="tilesetUrl"
      projection="EPSG:4326"
      attributions="Boundaries: PRG, Główny Urząd Geodezji i Kartografii"
    >
      <aol-format-mvt />
    </aol-source-ogcvectortile>
  </aol-layer-vectortile>
  <aol-layer-vectortile [declutter]="overlayGroup()" [renderMode]="'vector'" [style]="overlayLabelStyle">
    <aol-source-ogcvectortile
      [url]="tilesetUrl"
      projection="EPSG:4326"
      attributions="Boundaries: PRG, Główny Urząd Geodezji i Kartografii"
    >
      <aol-format-mvt />
    </aol-source-ogcvectortile>
  </aol-layer-vectortile>
</aol-map>

<div class="example-controls">
  <fieldset>
    <legend>Declutter groups</legend>
    <label>
      <input
        type="checkbox"
        [checked]="separateGroup()"
        aria-describedby="declutter-group-help"
        (change)="setSeparateGroup($event)"
      />
      Keep overlay labels in a separate group
    </label>
    <span id="declutter-group-help"
      >Separate groups may overlap. Uncheck to let the layers share one collision group.</span
    >
  </fieldset>
  <output role="status" aria-live="polite">{{ status() }}</output>
</div>
declutter-group.scss
:host {
  display: block;
}
declutter-group.shared.ts
import type { FeatureLike } from 'ol/Feature.js';
import Fill from 'ol/style/Fill.js';
import Stroke from 'ol/style/Stroke.js';
import Style from 'ol/style/Style.js';
import Text from 'ol/style/Text.js';

export const municipalityTilesetPath = 'assets/krakow/municipality-tiles/WorldCRS84Quad.json';
export const municipalityDeclutterGroup = 'municipalities';
export const overlayDeclutterGroup = 'overlay';
export const krakowMunicipalityName = 'Kraków';
export const municipalityLabelColor = '#0b6e4f';
export const overlayLabelColor = '#c94f22';

const boundary = new Style({
  fill: new Fill({ color: '#f7f7e9' }),
  stroke: new Stroke({ color: '#8c8b8b', width: 0.8 }),
});

export const municipalityStyle = (feature: FeatureLike): Style[] => {
  const name = String(feature.get('name') ?? '');
  const text = new Text({
    text: name,
    font: '14px sans-serif',
    fill: new Fill({ color: name === krakowMunicipalityName ? municipalityLabelColor : '#26343b' }),
    stroke: new Stroke({ color: '#fff', width: 3 }),
  });
  return [boundary, new Style({ text })];
};

export const overlayLabelStyle = (feature: FeatureLike): Style | undefined => {
  if (feature.get('name') !== krakowMunicipalityName) return undefined;
  return new Style({
    text: new Text({
      text: 'Overlay',
      font: '14px sans-serif',
      offsetX: 44,
      fill: new Fill({ color: overlayLabelColor }),
      stroke: new Stroke({ color: '#fff', width: 3 }),
    }),
  });
};
declutter-group.ts
import { ChangeDetectionStrategy, Component, computed, signal } from '@angular/core';
import {
  CoordinateComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  FormatMVTComponent,
  LayerVectorTileComponent,
  MapComponent,
  SourceOGCVectorTileComponent,
  ViewComponent,
} from 'cc-openlayers';
import {
  municipalityDeclutterGroup,
  municipalityStyle,
  municipalityTilesetPath,
  overlayDeclutterGroup,
  overlayLabelStyle,
} from './declutter-group.shared';

/** Shows how labels in separate vector-tile layers can share or separate their collision groups. */
@Component({
  selector: 'app-declutter-group',
  imports: [
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    FormatMVTComponent,
    LayerVectorTileComponent,
    MapComponent,
    SourceOGCVectorTileComponent,
    ViewComponent,
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  templateUrl: './declutter-group.html',
  styleUrl: './declutter-group.scss',
})
export class DeclutterGroup {
  protected readonly separateGroup = signal(true);
  protected readonly overlayGroup = computed(() =>
    this.separateGroup() ? overlayDeclutterGroup : municipalityDeclutterGroup
  );
  protected readonly status = computed(() => `Overlay group: ${this.separateGroup() ? 'separate' : 'shared'}`);
  protected readonly tilesetUrl = new URL(municipalityTilesetPath, document.baseURI).href;
  protected readonly municipalityDeclutterGroup = municipalityDeclutterGroup;
  protected readonly municipalityStyle = municipalityStyle;
  protected readonly overlayLabelStyle = overlayLabelStyle;

  protected setSeparateGroup(event: Event): void {
    if (event.target instanceof HTMLInputElement) this.separateGroup.set(event.target.checked);
  }
}

Architecture and OpenLayers mechanics

In OpenLayers, the layer declutter property accepts not only true or a false value, but also an arbitrary string group identifier. During each render frame, OpenLayers builds a separate R-tree screen-space bounding-box index per distinct declutter group name.

Layers assigned identical truthy strings insert their text and icon boxes into the same R-tree in render order so earlier/higher-priority features block overlapping candidates across both layers. Assigning distinct group names isolates their collision trees: neither layer’s internal labels overlap siblings within the same layer, yet the two layers can overlap each other freely.

How it works

  • Both vector-tile layers consume a local OGC WorldCRS84Quad municipal boundary tileset around Kraków derived from GUGiK PRG data.
  • String declutter identifiers partition collision detection: matching group names merge cross-layer collision trees, whereas distinct group names isolate each layer’s label placement.
  • Toggling the UI control updates the overlay layer’s declutter group reactively and triggers an immediate redraw so you can inspect the label overlap behaviour at the current zoom.
  • Self-contained local vector tiles and styles demonstrate collision grouping cleanly without relying on external commercial basemap API keys.

Pitfalls

  • Placing two dense text layers in separate declutter groups intentionally permits cross-layer text collisions—pair separate groups with strong halo contrast, badges or translucent backgrounds so overlapping labels stay legible.
  • Remember that boolean true puts every layer using true into the same default collision bucket; pass explicit string names whenever a layer needs isolated collision rules.
  • Layer order matters inside a shared declutter group: double-check z-index and layer order so critical foreground annotations win collision checks over decorative background labels.

The same feature in the OpenLayers examples .

Background: state and lifecycle of maps in Angular with OpenLayers, which the components of cc-openlayers take care of.