---
url: /pawn/docs/guide/labels.md
description: 'The Labels plugin: HTML elements pinned to entities on screen.'
---

# Labels

`Labels` is a plugin that pins HTML elements to entities on screen: names,
values, buttons, tooltips. The elements are ordinary DOM, so they take CSS,
text selection and clicks; the plugin only moves them. An engine installs
it when an entity first gets a `Label`.

```ts
import { Label, Position, Visual } from "@pawnjs/core";

const tag = document.createElement("div");
tag.textContent = "Wind park · 19 MW";
engine.world.spawn(
  Position({ x: -7, z: 5 }),
  Visual(turbines),
  Label({ element: tag, offset: { y: 3 } }),
);
```

Late in the `render` phase, after transforms reach the scene, each label is
placed over its entity's world position plus `offset`. A label is hidden
(`visibility: hidden`) while its entity is off screen, behind the camera,
outside its view or has no position.

## `Label` options

| Option | Meaning |
|---|---|
| `element` | Element to move. |
| `offset` | World-space offset from the entity, e.g. `{ y: 2 }` above it. |
| `align` | Point of the element placed on the entity, as fractions of its size. Defaults to `{ x: 0.5, y: 1 }`: centered, above the point. |
| `view` | View to project through. Defaults to the first enabled view. |

The plugin sets `position: absolute`, `left`, `top`, `transform` and
`visibility` on the element; style everything else yourself.

## Many labels

For scenes with hundreds of labelled entities, `Labels` can show only the
ones that matter, configured by installing it yourself before the first
label:

```ts
import { Labels } from "@pawnjs/core";

engine.use(new Labels({ maxDistance: 40, maxVisible: 50 }));
```

* `maxDistance` hides labels farther than this from their view's camera,
  in world units.
* `maxVisible` shows at most this many labels, the nearest to the camera.
* Both default to `Infinity`. A label only rewrites its element's
  `transform` when its place on screen changes.

## Container

Labels are positioned in a container, by default the canvas's parent
element (give it `position: relative`). Pass another one with
`new Labels({ container })`. An element without a parent is appended to
the container and removed again with its label; an element already in the
page stays where it is and is only moved.

`engine.plugin(Labels)` returns the installed plugin, or installs a default one.

## World position

An entity is labelled at its [world position](./hierarchy.md#world-position),
so labels on `ChildOf` children follow their parents, with a `Visual` or
without one. An `Instance` is drawn in world space, so its `Position` is
its world position.

## Projecting points yourself

`engine.views.project(point, view?)` returns the client coordinates of a
world point and whether it is visible, or `null` without a canvas. Without
a view it projects through `engine.views.first`, the first view drawn:

```ts
const at = engine.views.project(new Vector3(0, 2, 0));
if (at?.visible) showTooltip(at.x, at.y);
```

In React, use [`<EntityLabel>`](/packages/react#entitylabel).
