# PointLabelLayer `PointLabelLayer` is a layer for rendering text labels with optional secondary labels around points. It extends the capabilities of deck.gl's `TextLayer` with features like automatic label positioning, collision detection, and support for dual-label layouts. ## Usage ```tsx import {DeckGL} from '@deck.gl/react'; import {CollisionFilterExtension} from '@deck.gl/extensions'; import {PointLabelLayer} from '@deck.gl/carto'; type Airport = { coordinates: [longitude: number, latitude: number]; name: string; abbrev: string; }; const AIRPORTS = 'https://raw.githubusercontent.com/visgl/deck.gl-data/master/examples/line/airports.json' function App({viewState}) { const layers = [ new ScatterplotLayer({ data: AIRPORTS, getPosition: d => d.coordinates, radiusMinPixels: 2 }), new PointLabelLayer({ data: AIRPORTS, extensions: [new CollisionFilterExtension()], getPosition: d => d.coordinates, getText: d => d.name, getSecondaryText: d => d.abbrev, getColor: d => [2, 5, 11], sizeScale: 13, getSecondaryColor: d => [102, 105, 111], secondarySizeScale: 10, getTextAnchor: 'start', fontSettings: {sdf: true}, outlineColor: [255, 255, 255], outlineWidth: 2 }), ]; return ; } ``` ## Installation To install the dependencies from NPM: ```bash npm install deck.gl # or npm install @deck.gl/core @deck.gl/layers @deck.gl/carto ``` ```js import {PointLabelLayer} from '@deck.gl/carto'; new PointLabelLayer({}); ``` To use pre-bundled scripts: ```html ``` ```js new deck.carto.PointLabelLayer({}); ``` ## Properties Inherits all properties from [`TextLayer`](../layers/text-layer.md), with additional properties noted below. ### Label Positioning #### `getRadius` ([Accessor<number>](../../developer-guide/using-layers.md#accessors), optional) {#getradius} * Default: `1` The radius around the point where the label should be positioned. This value is used in conjunction with `radiusScale`, `getTextAnchor`, and `getAlignmentBaseline` to determine the final label position. #### `radiusScale` (Number, optional) {#radiusscale} * Default: `1` A multiplier to scale all radii. Useful for adjusting all label positions uniformly. ### Secondary Label Properties #### `getSecondaryText` ([Accessor<string>](../../developer-guide/using-layers.md#accessors), optional) {#getsecondarytext} The text to display as a secondary label. If not provided, no secondary label is shown. #### `getSecondaryColor` ([Accessor<Color>](../../developer-guide/using-layers.md#accessors), optional) {#getsecondarycolor} * Default: `[0, 0, 0, 255]` The color of the secondary text, in `[r, g, b, [a]]` format. Each channel is a number between 0-255 and `a` is 255 if not supplied. #### `secondaryOutlineColor` (Array, optional) {#secondaryoutlinecolor} * Default: `[0, 0, 0, 255]` The outline color for the secondary text, in `[r, g, b, [a]]` format. Each channel is a number between 0-255 and `a` is 255 if not supplied. #### `secondarySizeScale` (Number, optional) {#secondarysizescale} * Default: `1` Text size multiplier for the secondary label relative to the primary label size. ### Label Layout The layer automatically positions labels based on the following properties: - `getTextAnchor`: Controls horizontal positioning ('start', 'middle', 'end') - `getAlignmentBaseline`: Controls vertical positioning ('top', 'center', 'bottom') - `getRadius`: Determines distance from the point - Background padding is automatically adjusted based on the anchor and alignment Example layouts: ```js // Right-aligned labels { getTextAnchor: 'start', getAlignmentBaseline: 'center' } // Labels above points { getTextAnchor: 'middle', getAlignmentBaseline: 'bottom' } // Labels with secondary text below { getTextAnchor: 'start', getAlignmentBaseline: 'center', getSecondaryText: d => d.subtitle } ``` ### Collision Detection The layer includes built-in collision detection that: - Uses an enhanced background layer for collision testing - Only renders visible labels in collision pass - Maintains visual hierarchy between primary and secondary labels ## Source [modules/carto/src/layers/point-label-layer.ts](https://github.com/visgl/deck.gl/tree/master/modules/carto/src/layers/point-label-layer.ts)