DataLabelOptions

Defined in: map/base-engine.ts:165

Engine-owned text labels for plot() / geoMap() (#223) — the data-driven analogue of network.labels(). You supply the data and d3-style accessors; the engine measures each label’s text once (no magic-number metrics), places + culls collisions on every pan/zoom (the shared LabelLayer machinery), and routes to the active backend — an HTML overlay on WebGL, native <text>/fillText on SVG/Canvas so labels survive toSVG()/toPNG() export. Styling mirrors network.labels(): a built-in default look, an inline style override, or a full-CSS className. Plain labels are vertically centred on the anchor (offset sits them beside the glyph); set rotationOf for the oriented (rotated) model.

Type Parameters

D

D = unknown

Properties

anchorOf

anchorOf: (d, i) => [number, number] | null | undefined

Defined in: map/base-engine.ts:170

The label’s REFERENCE (world / pre-transform) anchor [x, y]; null/undefined skips it. For geoMap this is a projected point (e.g. projection(feature.geometry.coordinates)).

Parameters

d

D

i

number

Returns

[number, number] | null | undefined

className?

optional className?: string

Defined in: map/base-engine.ts:200

Advanced overlay styling: a CSS class that SKIPS the built-in inline style (font, color and halo included) so the class’s CSS has full control on the overlay (combine with style for inline overrides). Native text and exports still draw font/color/halo.

color?

optional color?: string

Defined in: map/base-engine.ts:206

Label fill colour on every backend (#577). Defaults to style’s colour, then the default.

font?

optional font?: string

Defined in: map/base-engine.ts:204

Label font on every backend (#577): the WebGL overlay, SVG/Canvas, and every export — a CSS font shorthand with a px size. Also the font used to MEASURE label boxes. Defaults to style’s font, then the built-in default.

halo?

optional halo?: LabelHalo

Defined in: map/base-engine.ts:210

Legibility halo stroked behind the label text on every backend (#571): the WebGL overlay (a CSS text stroke), SVG/Canvas, and every export. width is the half-stroke in px; 0 draws none. Default { color: "#ffffff", width: 1 }, or none when style sets textShadow: "none".

importanceOf?

optional importanceOf?: (d, i) => number

Defined in: map/base-engine.ts:172

Importance for collision priority and, when max caps, ranking (higher wins). Default 0.

Parameters

d

D

i

number

Returns

number

keepUpright?

optional keepUpright?: boolean

Defined in: map/base-engine.ts:189

Oriented labels only: flip 180° to keep text upright (radial-tree readability flip).

labelOf

labelOf: (d, i) => string | null | undefined

Defined in: map/base-engine.ts:167

The label text for a datum, or null/"" to skip it (no label for that datum).

Parameters

d

D

i

number

Returns

string | null | undefined

max?

optional max?: number

Defined in: map/base-engine.ts:191

Cap the number of shown labels to the top-k by importance (default: no cap — collision thins).

offset?

optional offset?: [number, number] | ((d, i) => [number, number])

Defined in: map/base-engine.ts:174

Constant screen-px offset [dx, dy] from the anchor, or a per-datum accessor. Default [0, 0].

rotationOf?

optional rotationOf?: (d, i) => number

Defined in: map/base-engine.ts:178

Oriented labels: reading-direction angle (radians) per datum — switches to the rotated collision/render model (text runs along the axis, vertically centred on the anchor). Drawn at that angle on every backend and in every export.

Parameters

d

D

i

number

Returns

number

rotationStep?

optional rotationStep?: number

Defined in: map/base-engine.ts:184

Oriented labels: round each rotationOf angle to a multiple of this many degrees (default 1; 0 keeps it exact). The browser rasterizes glyphs per angle, so labels that share an angle paint much faster: 2,000 rotated labels at 1° paint 1.2–2.5× faster than at free angles, and the overlay ~6× faster at 5°. A label then runs up to half a step off its angle (0.9 px at the end of a 100 px label at 1°). Rounded once per labels() call, never per frame.

style?

optional style?: LabelStyle

Defined in: map/base-engine.ts:196

Inline overlay CSS (camelCased property → value), merged over the built-in label look — a partial override keeps the rest. Applied once per element at creation, never per frame. Its font and color style every backend when font/color are not given (#577); any other property styles the overlay only.

textAnchor?

optional textAnchor?: TextAnchor

Defined in: map/base-engine.ts:187

Which way text runs from the anchor (default "start"). Also places a PLAIN label’s box — "middle" centres it on the anchor — with the CSS transform derived to match (#204).