Guides and legends

Appearance-only guides keyed by aesthetic. Compose declaration-only shells such as GuideLegend and GuideColorbar, or portable helpers such as guideLegend. Placement here is guide position (right/bottom) — not geom position adjustments (stack, dodge, jitter).

5 guides

All guides

• GuideLegend type "legend" · channels: color, fill, size, linewidth, alpha, shape, linetype · 8 options Discrete legend for one non-position aesthetic: title, placement rank, position, direction, key size, and collision. Default guide for categorical color, fill, size, shape, and other style channels.
• GuideColorbar type "colorbar" · channels: color, fill · 9 options Continuous color ramp for sequential color or fill scales. Shows ticks and labels along a vertical or horizontal bar; incompatible with discrete legends and binned colorsteps.
• GuideColorsteps type "colorsteps" · channels: color, fill · 8 options Binned color legend for binned color or fill scales. Step blocks with optional labels; use instead of legend or colorbar when the scale type is binned.
• GuideAxis type "axis" · channels: x, y · 5 options Axis guide for positional aesthetics x and y: title, tick marks, labels, and collision. Not valid on color, fill, or other style channels.
• GuideNone type "none" · channels: x, y, color, fill, size, linewidth, alpha, shape, linetype · no options Suppress the guide for one aesthetic entirely. Valid on every channel; useful to hide size or shape legends while keeping the mapping.

How to set a guide

Prefer a typed shell with a channel prop. Guides merge by channel; the value at a channel is replaced whole. Top-level guide children win over a scale-local guide on the same aesthetic.

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

<GGPlot data={rows} aes={{ x: "displ", y: "hwy", color: "class" }}>
  <GeomPoint />
  <GuideLegend channel="color" position="bottom" direction="horizontal" />
</GGPlot>

Portable helpers assemble the same JSON for the builder or normalize():

import { guideLegend, guides } from "@ggts-sh/spec";

guides({ color: guideLegend({ position: "bottom" }) })
// → { guides: { color: { type: "legend", position: "bottom" } } }

For a computed multi-channel bag, use the escape hatch <Guides value={…} />. Suppress one channel with GuideNone.

Legend focus, filter, and clear recovery

Discrete color and fill legends can host interaction controls when <GuideLegend focus /> or <GuideLegend filter /> is enabled for that aesthetic. Do not put legendFocus / legendFilter on <GGPlot> — those plot props are deprecated dual-reads. Focus is presentation emphasis only; Clear legend focus restores the unfocused view without changing data. Filter changes included rows. Authoring the guide itself is separate — see GuideLegend, the interaction reference, and the legend focus example.