Legend key

A standalone colour key: categorical swatches, or a sequential/diverging ramp with end labels.

Use when: When several charts (small multiples, a map and a bar chart, a dashboard row) share one colour encoding, show the key once above them and turn their own legends off.
Avoid when: A single chart: its built-in legend or, better, direct labels already do this. Do not list more than eight categories.

Preview

Source of electricity

Solar
Wind
Hydro
Gas
Other

import { LegendKey } from "insightcharts";

export function Example() {
  return (
    <LegendKey
      title="Source of electricity"
      items={[
        "Solar",
        "Wind",
        "Hydro",
        "Gas",
        { label: "Other", muted: true },
      ]}
    />
  );
}

{
  "type": "legend-key",
  "title": "Source of electricity",
  "items": [
    "Solar",
    "Wind",
    "Hydro",
    "Gas",
    { "label": "Other", "muted": true }
  ]
}

Render with import { Insight } from "insightcharts" and <Insight spec={spec} />. Nested specs resolve by name; nothing else to import.

Composition

Used in

1 molecule and 1 template use legend key.

Molecules

Small multiple grid

Repeats any chart spec once per value of a facet field, each panel with its own filtered rows and a title, in a grid that follows the container width.

Templates

A long article read by scrolling. It has a headline, then an ordered list of blocks in a reading column, then a source note. The blocks are prose, figures, charts with a callout, scrolly sequences, pull quotes, stat rows, small multiples and chapter breaks. Exhibits can be wider than the column.

ThroughSmall multiple grid

Installation

$ pnpm dlx shadcn@latest add @insightcharts/legend-key

The CLI copies the source into your project and needs the @insightcharts registry in components.json; see installation. With the package, import it by name:

import { LegendKey } from "insightcharts";

Examples

Sequential ramp

Share of electricity from renewables

import { LegendKey } from "insightcharts";

export function Example() {
  return (
    <LegendKey
      scale="sequential"
      title="Share of electricity from renewables"
      labels={["0%", "100%"]}
    />
  );
}

{
  "type": "legend-key",
  "scale": "sequential",
  "title": "Share of electricity from renewables",
  "labels": ["0%", "100%"]
}

Render with import { Insight } from "insightcharts" and <Insight spec={spec} />. Nested specs resolve by name; nothing else to import.

Diverging, stepped

Change in house prices, 2019 to 2024

import { LegendKey } from "insightcharts";

export function Example() {
  return (
    <LegendKey
      scale="diverging"
      stepped
      title="Change in house prices, 2019 to 2024"
      labels={["−20%", "No change", "+20%"]}
      width={300}
    />
  );
}

{
  "type": "legend-key",
  "scale": "diverging",
  "stepped": true,
  "title": "Change in house prices, 2019 to 2024",
  "labels": ["−20%", "No change", "+20%"],
  "width": 300
}

Render with import { Insight } from "insightcharts" and <Insight spec={spec} />. Nested specs resolve by name; nothing else to import.

Lines, vertical, explicit order

Germany
Spain
EU average

import { LegendKey } from "insightcharts";

export function Example() {
  return (
    <LegendKey
      orientation="vertical"
      shape="line"
      items={[
        { label: "Germany", index: 0 },
        { label: "Spain", index: 3 },
        { label: "EU average", muted: true },
      ]}
    />
  );
}

{
  "type": "legend-key",
  "orientation": "vertical",
  "shape": "line",
  "items": [
    { "label": "Germany", "index": 0 },
    { "label": "Spain", "index": 3 },
    { "label": "EU average", "muted": true }
  ]
}

Render with import { Insight } from "insightcharts" and <Insight spec={spec} />. Nested specs resolve by name; nothing else to import.

Props

Prop	Type	Default	Description
scale	"categorical" \| "sequential" \| "diverging"		Defaults to `categorical` when `items` is given, otherwise `sequential`.
items	(string \| { label, color?, index?, shape?, muted? })[]		Categorical entries. Colours come from the theme's categorical order by position (or `index`) unless given.
labels	string[]		Ramp end labels: `[low, high]` or `[low, middle, high]`.
colors	string[]		Ramp colours, low to high. Defaults to the theme's sequential or diverging ramp.
stepped	boolean	false	Discrete steps instead of a continuous gradient, for binned scales.
title	string		What the key encodes.
shape	"square" \| "line" \| "dot"	"square"	Default swatch shape: match the marks.
orientation	"horizontal" \| "vertical"	"horizontal"	Categorical layout.
width	number	240	Ramp width in px, capped at the container.
align	"left" \| "center"	"left"	Alignment within the container.