ggsvelte
GitHub
Navigate
On this page

GuideLegend

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.

Channels

Bind this guide with the shell channel prop (or the matching key under guides in JSON). Only these aesthetics validate:

  • color
  • fill
  • size
  • linewidth
  • alpha
  • shape
  • linetype

On color / fill, a discrete or ordinal scale is required. Sequential scales need GuideColorbar; binned scales need GuideColorsteps. Positional x / y use GuideAxis.

Svelte component

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

<GGPlot data={rows} aes={{ x: "displ", y: "hwy", color: "class" }}>
  <GeomPoint />
  <GuideLegend channel="color" title="Label" order={1} />
</GGPlot>

JSON and helpers

import { guideLegend, guides } from "@ggsvelte/spec";

guides({ color: guideLegend({ title: "Label", order: 1 }) })
// → { guides: { color: { type: "legend", … } } }
{
  "guides": {
    "color": {
      "type": "legend"
    }
  }
}

Helper: guideLegend (alias guide_legend). Schema type: LegendGuideSpec. Portable type: "legend".

Props

Every shell takes a required channel prop (not part of the portable guide object — it is the key under guides). Options below map 1:1 to the guide JSON fields.

channel required

"color" | "fill" | "size" | "linewidth" | "alpha" | "shape" | "linetype"

Aesthetic this guide configures. Must be one of the channels listed above.

title

string

Optional guide title string (max 256 characters). Omit to use the scale or labs title.

order

integer

Integer placement rank among sibling guides (−1024…1024). Lower values sort earlier. Not the plot-wide Legend entry-sort enum.

position

"auto" | "right" | "bottom"

Guide placement relative to the panel: "auto", "right", or "bottom". Auto picks a side from available space.

direction

"auto" | "vertical" | "horizontal"

Layout of keys or the color ramp: "auto", "vertical", or "horizontal". Bottom placement usually forces horizontal.

keySize

number

Legend key glyph size in pixels (4…48).

collision

"ellipsis" | "wrap" | "error"

How long labels behave when they do not fit: ellipsis, wrap (legend only), preserve (axis), auto (axis), or error.

force

boolean

When true, keep this guide even if the scale would normally suppress it (for example a single-level discrete scale).

theme

GuideThemeSpec

Bounded presentation overrides for this guide block (title/label size, gaps, colorbar size).

Legend focus

When the plot enables legendFocus, discrete color and fill legends host HTML controls for preview and commit. Clear legend focus removes presentation emphasis only — it does not reset legendFilter or data. See the interaction reference and legend focus example.

← All guides · Positions · Scales and guides

Docs