> For the complete documentation index, see [llms.txt](https://developers.felt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.felt.com/felt-style-language/style-definition-blocks/the-label-block.md).
# The label block
{% hint style="info" %}
The label block defines how feature labels are rendered.
{% endhint %}
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](/felt-style-language/zoom-based-styling/interpolators.md) | Points and lines | Optional. The label color |
| `fontFamily` | string | Points and lines | Optional. The font family to use |
| `fontSize` | number \| [Interpolator](/felt-style-language/zoom-based-styling/interpolators.md) | 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 |
| `haloColor` | string \| [Interpolator](/felt-style-language/zoom-based-styling/interpolators.md) | Points and lines | Optional. The label halo color |
| `haloWidth` | number \| [Interpolator](/felt-style-language/zoom-based-styling/interpolators.md) | 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](/felt-style-language/zoom-based-styling/interpolators.md) | 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 in degrees for text following a curved line.
See [default values](#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.
{% hint style="info" %}
Prefer `"color": "auto"` and `"haloColor": "auto"` so labels stay legible across themes and basemaps. See [Colors & palettes](/felt-style-language/colors-and-palettes.md).
{% endhint %}
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](/felt-style-language/types-of-visualizations/categorical-visualizations.md).
## 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" |
{% hint style="info" %}
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.
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://developers.felt.com/felt-style-language/style-definition-blocks/the-label-block.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.