ChartLegend

Data Display

Static or interactive series legends with values and caller-controlled filtering.

Interactive chart filteringStatic totalsHorizontal and verticalAll-series-hidden state

Responsive viewport — resize the window to explore. Direction and density apply only to this preview. Theme applies to the docs too.

chart-legend.tsx

"use client";

import { ChartLegend } from "@/components/ui/chart-legend";
import { useState } from "react";
const series = [
  { id: "direct", label: "Direct", color: "var(--primary)", value: "4,820" },
  {
    id: "referral",
    label: "Referral",
    color: "var(--warning)",
    value: "2,160",
  },
  {
    id: "organic",
    label: "Organic",
    color: "var(--muted-foreground)",
    value: "3,740",
  },
];
export default function ChartLegendExample() {
  const [hidden, setHidden] = useState<string[]>([]);
  return (
    <div className="w-full max-w-xl space-y-7">
      <div className="rounded-xl border bg-card p-5">
        <h3 className="font-semibold">Traffic sources</h3>
        <p className="mt-1 text-xs text-muted-foreground">
          Toggle a series to filter the chart.
        </p>
        <div
          role="img"
          aria-label={`Visible traffic series: ${
            series
              .filter((item) => !hidden.includes(item.id))
              .map((item) => item.label)
              .join(", ") || "none"
          }`}
          className="my-6 grid h-28 grid-cols-8 items-end gap-2"
        >
          {Array.from({ length: 8 }, (_, index) => (
            <span
              key={index}
              className="flex h-full flex-col justify-end gap-0.5"
            >
              {series
                .filter((item) => !hidden.includes(item.id))
                .map((item, position) => (
                  <span
                    key={item.id}
                    style={{
                      height: `${14 + ((index * 7 + position * 13) % 22)}%`,
                      backgroundColor: item.color,
                    }}
                    className="block rounded-sm"
                  />
                ))}
            </span>
          ))}
        </div>
        <ChartLegend
          label="Traffic series"
          series={series}
          hiddenIds={hidden}
          onHiddenIdsChange={setHidden}
        />
      </div>
      <div className="rounded-xl border p-4">
        <p className="mb-3 text-xs text-muted-foreground">STATIC · VERTICAL</p>
        <ChartLegend
          label="Traffic totals"
          series={series}
          orientation="vertical"
        />
      </div>
    </div>
  );
}

Usage

Provide unique series ids, labels, colors, and optional formatted values. A static legend uses ordinary list content. Supplying onHiddenIdsChange enables toggle buttons; own hiddenIds and use them to filter the actual chart data. The live example connects those controls to a stacked series preview. This component does not inspect or mutate a chart instance. Only pass color values from a trusted palette.

Import

import { ChartLegend } from "@/components/ui/chart-legend";

Shipped as editable source in src/components/ui/chart-legend.tsx in both apps. Copy the implementation below when moving it to another project. Copy the complete example from Source code for all imports and state. Add "use client" when using hooks or event handlers. See installation and theming for project setup.

Component source

The complete implementation is included in both apps. It uses the React, Radix, Lucide, and shared-core dependencies already installed in Apex. Keep your project’s semantic theme tokens when reusing it.

src/components/ui/chart-legend.tsx

"use client";
import { cn } from "@dashboardpack/core/lib/utils";
export interface LegendSeries {
  id: string;
  label: string;
  color: string;
  value?: string;
}
export interface ChartLegendProps {
  label: string;
  series: LegendSeries[];
  hiddenIds?: string[];
  onHiddenIdsChange?: (ids: string[]) => void;
  orientation?: "horizontal" | "vertical";
  className?: string;
}
export function ChartLegend({
  label,
  series,
  hiddenIds = [],
  onHiddenIdsChange,
  orientation = "horizontal",
  className,
}: ChartLegendProps) {
  return (
    <ul
      aria-label={label}
      className={cn(
        "flex gap-2",
        orientation === "vertical" ? "flex-col" : "flex-wrap",
        className,
      )}
    >
      {series.map((item) => {
        const hidden = hiddenIds.includes(item.id);
        const content = (
          <>
            <span
              aria-hidden
              style={{ backgroundColor: item.color }}
              className="size-2.5 shrink-0 rounded-sm"
            />
            <span className={cn("min-w-0 flex-1", hidden && "line-through")}>
              {item.label}
            </span>
            {item.value && (
              <span className="ms-3 text-xs tabular-nums text-muted-foreground">
                {item.value}
              </span>
            )}
          </>
        );
        const style = cn(
          "flex items-center gap-2 rounded-md px-2 py-1.5 text-start text-xs",
          hidden && "opacity-50",
        );
        return (
          <li key={item.id}>
            {onHiddenIdsChange ? (
              <button
                type="button"
                className={cn(
                  style,
                  "w-full outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring",
                )}
                aria-pressed={!hidden}
                onClick={() =>
                  onHiddenIdsChange(
                    hidden
                      ? hiddenIds.filter((id) => id !== item.id)
                      : [...hiddenIds, item.id],
                  )
                }
              >
                {content}
              </button>
            ) : (
              <span className={style}>{content}</span>
            )}
          </li>
        );
      })}
      {!series.length && (
        <li className="text-xs text-muted-foreground">No series available.</li>
      )}
    </ul>
  );
}

API reference

Common props and defaults. Slot-specific props are named below; native elements also accept their standard HTML attributes. The component TypeScript definitions are the complete type reference.

ChartLegend props
Prop	Type / Default	Description
label	`string` Default: required	Accessible list name.
series	`LegendSeries[]` Default: required	Unique id, label, CSS color, and optional display value.
hiddenIds	`string[]` Default: []	Controlled hidden series.
onHiddenIdsChange	`(ids: string[]) => void` Default: —	Enable interactive filtering actions.
orientation	`horizontal \| vertical` Default: horizontal	Legend arrangement.
className	`string` Default: —	Extend the container with semantic theme utilities.

Build with these too

LazyChart Sparkline Toggle