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.

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.tsimport 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.tsimport { 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);
}
} The React version uses the library's React adapter, cc-openlayers/react: each component creates the OpenLayers object it names when it mounts, updates it from its props and disposes of it when it unmounts.
declutter-group.react.tsximport { useState } from 'react';
import {
Coordinate,
DefaultControls,
DefaultInteractions,
Map,
OGCVectorTileSource,
useMVTFormat,
VectorTileLayer,
View,
} from 'cc-openlayers/react';
import {
municipalityDeclutterGroup,
municipalityStyle,
municipalityTilesetPath,
overlayDeclutterGroup,
overlayLabelStyle,
} from './declutter-group.shared';
const TILESET_URL = new URL(municipalityTilesetPath, document.baseURI).href;
/** Shows how labels in separate vector-tile layers can share or separate their collision groups. */
export function DeclutterGroupReact() {
const [separateGroup, setSeparateGroup] = useState(true);
const format = useMVTFormat();
const overlayGroup = separateGroup ? overlayDeclutterGroup : municipalityDeclutterGroup;
return (
<>
<Map height="480px" ariaLabel="Kraków municipality label groups">
<DefaultInteractions />
<DefaultControls />
<View projection="EPSG:4326" zoom={10}>
<Coordinate x={19.937} y={50.0614} srid="EPSG:4326" />
</View>
<VectorTileLayer
background="#d1d1d1"
declutter={municipalityDeclutterGroup}
renderMode="vector"
style={municipalityStyle}
>
<OGCVectorTileSource
url={TILESET_URL}
projection="EPSG:4326"
attributions="Boundaries: PRG, Główny Urząd Geodezji i Kartografii"
format={format}
/>
</VectorTileLayer>
<VectorTileLayer declutter={overlayGroup} renderMode="vector" style={overlayLabelStyle}>
<OGCVectorTileSource
url={TILESET_URL}
projection="EPSG:4326"
attributions="Boundaries: PRG, Główny Urząd Geodezji i Kartografii"
format={format}
/>
</VectorTileLayer>
</Map>
<div className="example-controls">
<fieldset>
<legend>Declutter groups</legend>
<label>
<input
type="checkbox"
checked={separateGroup}
aria-describedby="declutter-group-help"
onChange={(event) => setSeparateGroup(event.currentTarget.checked)}
/>
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">
Overlay group: {separateGroup ? 'separate' : 'shared'}
</output>
</div>
</>
);
}declutter-group.shared.tsimport 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 }),
}),
});
};How the React version works
Two vector-tile layers show municipality names and an overlay label around Kraków using the existing local WorldCRS84Quad fixture. The labels deliberately overlap. Keep them in separate collision groups to allow both layers' labels, or uncheck the control to let the layers share collision handling. The map starts at Rynek Główny and retains PRG/GUGiK attribution.
What both versions share
The shared module supplies the local tileset path, group identifiers and styles. Both layers use truthy string identifiers for decluttering: equal values join one collision group, while different values keep groups independent. A contrasting overlay label is drawn for Kraków, and municipality outlines provide geographic context. OpenLayers owns the collision decisions across layers.
From Angular to React
| Angular | React |
|---|---|
MapComponent, vector-tile layers and OGC sources | Map, VectorTileLayer and OGCVectorTileSource wrappers |
| A signal stores the checkbox value | useState stores the checkbox value |
| Computed signals derive the overlay group and status | Rendered values derive the overlay group and status |
| A change handler reads the checked input | onChange reads event.currentTarget.checked |
Who creates, updates and disposes
The existing map, layer and source wrappers own their OpenLayers objects and lifecycle cleanup. The example owns the checkbox state and composes the shared styles. React mounts through its existing wrapper lifecycle, including StrictMode remounts; Angular renders its state through the component template.
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
trueputs every layer usingtrueinto 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.
Related examples
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.