Styling and labels · Angular, React and OpenLayers
Decluttered polygon labels
Keep dense Polish voivodeship polygon labels readable across zoom levels in OpenLayers by combining layer decluttering with text overflow: true.

What this example shows
Across all 16 Polish voivodeships at zoom 6, every province name—including two-line hyphenated names such as kujawsko-pomorskie and warmińsko-mazurskie—fits cleanly without collision.
Zooming out to smaller national scales automatically hides colliding labels so remaining names stay crisp and legible while every underlying polygon border remains visible.
When you need it
Districts, cadastral parcels, postcode sectors and lakes crowd together rapidly whenever a user zooms out, turning un-decluttered text into an unreadable black smear.
Combining screen-space collision removal with overflow: true lets narrow polygons participate in labelling at medium scales without ever overlapping a neighbour’s text.
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.
vector-label-decluttering.tsimport { ChangeDetectionStrategy, Component } from '@angular/core';
import {
CoordinateComponent,
DefaultControlComponent,
DefaultInteractionComponent,
LayerVectorComponent,
MapComponent,
SourceGeoJSONComponent,
ViewComponent,
} from 'cc-openlayers';
import type { FeatureLike } from 'ol/Feature';
import Fill from 'ol/style/Fill';
import Stroke from 'ol/style/Stroke';
import Style from 'ol/style/Style';
import Text from 'ol/style/Text';
/** Voivodeship polygons whose labels are decluttered; `overflow` lets a label wider than its polygon take part. */
@Component({
selector: 'app-vector-label-decluttering',
imports: [
CoordinateComponent,
DefaultControlComponent,
DefaultInteractionComponent,
LayerVectorComponent,
MapComponent,
SourceGeoJSONComponent,
ViewComponent,
],
changeDetection: ChangeDetectionStrategy.OnPush,
template: `
<aol-map height="480px">
<aol-interaction-default />
<aol-control-defaults />
<aol-view [zoom]="6"><aol-coordinate [x]="19.9368" [y]="50.0614" srid="EPSG:4326" /></aol-view>
<aol-layer-vector background="white" [declutter]="true" [style]="style">
<aol-source-geojson url="assets/poland/voivodeships.geojson" />
</aol-layer-vector>
</aol-map>
`,
})
export class VectorLabelDecluttering {
private readonly areaStyle = new Style({
fill: new Fill({ color: 'rgba(255, 255, 255, 0.6)' }),
stroke: new Stroke({ color: '#319FD3', width: 1 }),
});
protected readonly style = (feature: FeatureLike): Style[] => {
const label = new Style({
text: new Text({
// The voivodeships' names are single words, the longest of them joined by a hyphen: they break after it.
text: String(feature.get('name')).split('-').join('-\n'),
font: '12px Calibri,sans-serif',
overflow: true,
fill: new Fill({ color: '#000' }),
stroke: new Stroke({ color: '#fff', width: 3 }),
}),
});
return [this.areaStyle, label];
};
} 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.
vector-label-decluttering.react.tsximport 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';
import {
Coordinate,
DefaultControls,
DefaultInteractions,
GeoJSONSource,
Map,
VectorLayer,
View,
} from 'cc-openlayers/react';
const areaStyle = new Style({
fill: new Fill({ color: 'rgba(255, 255, 255, 0.6)' }),
stroke: new Stroke({ color: '#319FD3', width: 1 }),
});
const style = (feature: FeatureLike): Style[] => {
const label = new Style({
text: new Text({
// The voivodeships' names are single words, the longest of them joined by a hyphen: they break after it.
text: String(feature.get('name')).split('-').join('-\n'),
font: '12px Calibri,sans-serif',
overflow: true,
fill: new Fill({ color: '#000' }),
stroke: new Stroke({ color: '#fff', width: 3 }),
}),
});
return [areaStyle, label];
};
/** Voivodeship polygons whose labels are decluttered; `overflow` lets a label wider than its polygon take part. */
export function VectorLabelDecluttering() {
return (
<Map height="480px">
<DefaultInteractions />
<DefaultControls />
<View zoom={6}>
<Coordinate x={19.9368} y={50.0614} srid="EPSG:4326" />
</View>
<VectorLayer background="white" declutter={true} style={style}>
<GeoJSONSource url="assets/poland/voivodeships.geojson" />
</VectorLayer>
</Map>
);
}How the React version works
Voivodeship labels decluttered so they do not overlap; overflow lets a label wider than its polygon take part, and names break after each hyphen.
What both versions share
OpenLayers renders the map and handles the interactions; the cc-openlayers/core layer gives both adapters the same view binding (MapViewBinding) and the same conversion of coordinates from EPSG:4326 to the map's projection.
From Angular to React
| Angular | React |
|---|---|
<aol-layer-vector> with <aol-source-geojson> | <VectorLayer> with <GeoJSONSource> |
<aol-layer-vector [declutter]="true"> | <VectorLayer declutter={true}> |
a style function as a class field bound to [style] | a style function constant in the module, passed as style; a new function in every render would restyle the layer each time |
Who creates, updates and disposes
Map creates the ol/Map in useLayoutEffect and disposes of it on unmount; each layer, source and interaction component adds its object to the parent it gets from context and removes it in its effect's cleanup, as ngOnDestroy does in Angular.
Architecture and OpenLayers mechanics
Enabling [declutter]="true" on the vector layer inserts each candidate label’s bounding box (including any background and padding) into a per-frame R-tree, dropping later candidates that intersect an already accepted label.
Setting overflow: true on the Text style lifts OpenLayers’ default rule that suppresses labels wider than their host polygon, while breaking hyphenated names onto two lines narrows their horizontal footprint so more provinces fit simultaneously.
How it works
[declutter]="true"on the vector layer automatically omits any label whose screen box collides with an earlier label.overflow: truepermits labels wider than their polygon’s interior span to enter collision detection instead of being discarded up front.- Splitting hyphenated province names across two lines creates compact boxes that survive further zoom-out before colliding.
- At zoom 6 the wider provinces keep their names while narrower neighbours start dropping out; zooming further out removes more colliding names while every polygon outline stays visible.
Pitfalls
- Decluttering is first-come, first-served in render order: sort features (or assign explicit style z-index / renderOrder) so major capitals or larger regions win space ahead of minor neighbours.
- Excessive text padding or wide background boxes enlarge each label’s collision rectangle and cause nearby labels to drop prematurely.
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.