ggsvelte
GitHub
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. There is no collision detection — labels draw exactly where placed. Offset with dx/dy or position="nudge" plus positionParams.

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

import { GeomPoint, GeomText, GGPlot, Labs } from "@ggsvelte/svelte";

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

GeomLabel

Same placement contract as text, with a rounded rectangular background box. Still no collision detection. 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.

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. Data-label geoms never auto-dodge or drop overlapping marks — you author placement. A guide with collision: "error" that cannot fit fails with a guide-collision diagnostic rather than silently clipping (see Errors reference).

Docs