ggts
Navigate
On this page

Labels

“Label” means three different contracts in ggsvelte. Use the right surface so titles, ticks, and per-mark text do not get mixed up.

Three kinds of labels

Plot chrome
Labs title, subtitle, caption, and aesthetic titles (axes/legends). Not drawn from row data.
Tick labels
Scale breaks / labels / dateLabels choose values and format; GuideAxis chooses show/hide and collision (auto | preserve | ellipsis).
Data labels
Geoms that place aes.label at data coordinates: GeomText, GeomLabel, and their SF variants. Full param tables live on each geom page.

GeomText

One text mark per data row at (x, y). Requires x, y, and label channels. Labels draw exactly where placed unless you opt into checkOverlap (params.checkOverlap in JSON), which drops labels that would overlap an earlier one in the same layer and panel. Offset with dx/dy or position="nudge" plus positionParams.

Schema-derived defaults, params, and allowed stats: GeomText.

import { GeomPoint, GeomText, GGPlot, Labs } from "@ggts-sh/svelte";

<GGPlot data={cities} aes={{ x: "lon", y: "lat", label: "name" }}>
  <GeomPoint />
  <GeomText dy={-8} size={11} />
  <Labs title="City labels" x="Longitude" y="Latitude" />
</GGPlot>

GeomLabel

Same placement contract as text, including opt-in checkOverlap, with a rounded rectangular background box. color paints ink and box stroke; fill paints the box background when mapped.

Full reference: GeomLabel.

<GGPlot data={cities} aes={{ x: "lon", y: "lat", label: "name" }}>
  <GeomPoint />
  <GeomLabel dy={-10} size={11} />
</GGPlot>

Simple-features labels

  • GeomSfText — places aes.label at representative geometry points (Multi* → one label per part; stat_sf_coordinates).
  • GeomSfLabel — same placement with a measured rounded background rect.

The SF variants do not take checkOverlap. Runnable contracts: SF region labels and SF boxed labels.

Collision: geoms vs guides

Guide collision policies only apply to guide chrome. Axes use auto / preserve / ellipsis; legends and colorbars may use ellipsis, wrap, or error. A guide with collision: "error" that cannot fit fails with a guide-collision diagnostic rather than silently clipping (see Errors reference).

Data-label geoms measure each rendered text box after stats, positions, and coordinate projection. For GeomText the box is the glyph bounds; GeomLabel adds its padding and half the box stroke. Within one layer and one panel, overlapping marks emit the text-label-overlap warning; the message names the layer index and the number of unique overlapping marks. checkOverlap defaults to false, which draws every label and only warns. With checkOverlap: true, labels are kept greedily in draw order: a label that would overlap an earlier retained label is dropped, so earlier rows win, later collisions disappear, and the warning stays silent. Overlaps are never nudged or repelled — the opt-in only skips colliding marks. Layers and panels are measured independently, so labels in different layers or facets do not count as colliding.

Docs