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 "@ggsvelte/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 "@ggsvelte/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 and clear recovery

Discrete color and fill legends can host interaction controls when legendFocus or legendFilter is enabled on the plot. Focus is presentation emphasis only; Clear legend focus restores the unfocused view without changing data. Authoring the guide itself is separate — see GuideLegend, the interaction reference, and the legend focus example.