Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

The label block

The label block defines how feature labels are rendered.

These are the properties available to define label rendering. Point and line features are labeled directly; polygon labels are anchored at each polygon's centroid (or along lines with renderAsLines).

Type
Applies to
Description

color

string | auto | Interpolator

Points and lines

Optional. The label color

fontFamily

string

Points and lines

Optional. Currently ignored: labels always use Felt's label font (Atlas Grotesk, with Noto Sans as a fallback). Use fontWeight and fontStyle to vary it.

fontSize

number | Interpolator

Points and lines

Optional. The font size in pixels

fontStyle

"normal" | "italic"

Points and lines

Optional. The font style (case-insensitive). Values other than italic render as normal

fontWeight

number

Points and lines

Optional. The font weight: 400 (regular), 500 (medium) or 700 (bold). Other values render as regular.

haloColor

string | Interpolator

Points and lines

Optional. The label halo color

haloWidth

number | Interpolator

Points and lines

Optional. The label halo width in pixels

justify

"auto" | "left" | "right" | "center"

Points and lines

Optional. Text justification for multi-line labels

letterSpacing

number

Points and lines

Optional. Horizontal spacing behaviour between text characters

lineHeight

number

Points and lines

Optional. Sets the height of a line box

maxLineChars

number | Interpolator

Points and lines

Optional. Defines the max number of characters before a line break

maxZoom

number

Points and lines

Optional. The maximum zoom level at which the label will be shown. Defaults to 24

minZoom

number

Points and lines

Optional. The minimum zoom level at which the label will be shown. Defaults to 24 (see note below)

offset

[number, number] | number

Points and lines

Optional. In the case of points, this value must be an array of two numeric offsets that will be applied on the positive X and Y axis defined by the label placement (i.e. an offset of [3,4] with a label placement of NE moves the label 3pixels to the right and 4 pixels above of the anchor point. An offset of [3,4] with a label placement of SW moves the label 3pixels to the left and 4 pixels below of the anchor point). In case of lines, this value is a single number that moves the label following the label position (i.e. an offset of 3 with a label position of Above will move the label 3 pixels above the line following the line normal. An offset of 3 with a label position of Below will mode the label 3 pixels under the line following the line normal)

padding

number

Points and lines

Optional. Adds invisible padding around the label that's used to compute label collisions

placement

string[] | "auto" | string

Points and lines

Optional. On points: an array of placements to try ("N", "NE", "E", "SE", "S", "SW", "W", "NW", "Center") or "auto"; if all placements collide with existing labels, the label is not shown. On lines: a single placement relative to the line — "Above", "Center" or "Below"

renderAsLines

boolean

Polygons

Optional. Renders labels along lines instead of using the centroids

repeatDistance

number

Lines

Optional. The distance in pixels between label repetitions on a line

textTransform

"none" | "uppercase" | "lowercase"

Points and lines

Optional. Specifies how to capitalize the label

isClickable

boolean

Points, Lines and Polygons

Optional. A flag to tell if labels should be clickable

isHoverable

boolean

Points, Lines and Polygons

Optional. A flag to tell if labels should be hoverable

In addition, lines support maxAngle (number, default 30), the maximum angle change in degrees between adjacent characters of text following a curved line. Sharper turns aren't placed. See when a label isn't rendered.

See default values of these attributes on each label type.

Placement by geometry

placement is shaped differently depending on the geometry being labeled:

  • Points: an array of compass directions to try, e.g. ["E"] (right of the point), ["E", "W"], or ["Center"]. Felt uses the first placement that doesn't collide.

  • Lines: a single string relative to the line — "Above", "Center", or "Below". Tune repeatDistance (pixels between repeated labels) and maxAngle for curved text.

  • Polygons: ["Center"] places the label at the polygon's centroid.

When a label isn't rendered

A feature with a label value can still render no label. Three rules decide:

  • Collision. A label that overlaps one already placed is dropped rather than moved. padding sets how much space around the text counts as an overlap. Zooming in usually brings the label back.

  • Line length. Line labels are anchored every repeatDistance pixels and need enough of the run on screen to fit their glyphs. Short segments get nothing. A smaller fontSize or a lower repeatDistance makes room.

  • Curvature. maxAngle caps the angle change between adjacent characters, not the overall bend of the line. Sharper turns aren't placed, so tight meanders often go unlabeled at the default 30.

If a feature never labels at any zoom, check its config.labelAttribute value. Null or empty draws nothing.

Prefer "color": "auto" and "haloColor": "auto" so labels stay legible across themes and basemaps. See Colors & palettes.

If using a categorical or numeric visualization, the properties above may be arrays. If there's a single value in the array, that value is used in all categories. If there are as many values as categories, the corresponding value will be used for each category. You can see an example of a categorical viz here.

Default values

Name
Points
Lines
Centroids

color

"#333333"

"#333333"

"#333333"

fontFamily

"Atlas Grotesk LC"

"Atlas Grotesk LC"

"Atlas Grotesk LC"

fontSize

13

13

13

fontStyle

"Normal"

"Normal"

"Normal"

fontWeight

500

400

500

haloColor

"#fbfcfb"

"#fbfcfb"

"#fbfcfb"

haloWidth

1

1

1

justify

"auto"

"auto"

"auto"

letterSpacing

0

0

0

lineHeight

1.2

1.2

1.2

maxLineChars

10

-

10

maxAngle

-

30

-

maxZoom

24

24

24

minZoom

24

24

24

offset

[8, 8]

0

-

padding

2

1

0

placement

"auto"

"Above"

"Center"

repeatDistance

-

250

-

textTransform

"none"

"none"

"none"

The default minZoom and maxZoom are both 24 — an empty range, which is how labels are hidden by default. To show labels, set a real zoom range on the label block.

Last updated

Was this helpful?