The label block
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).
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.
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.
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". TunerepeatDistance(pixels between repeated labels) andmaxAnglefor 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.
paddingsets how much space around the text counts as an overlap. Zooming in usually brings the label back.Line length. Line labels are anchored every
repeatDistancepixels and need enough of the run on screen to fit their glyphs. Short segments get nothing. A smallerfontSizeor a lowerrepeatDistancemakes room.Curvature.
maxAnglecaps 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 default30.
If a feature never labels at any zoom, check its config.labelAttribute value. Null or empty draws nothing.
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
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"
Last updated
Was this helpful?