Pyramid

Ranked-tier pyramid. Tiers stack top-to-bottom; widths can grow toward the base (widening) or shrink (narrowing). Pure SVG; no heavy peer dep. Distinct from Funnel — Pyramid encodes RANK, Funnel encodes FLOW.

Installation

pnpm

pnpm dlx @hex-core/cli add pyramid

Usage

tsx

import { Pyramid } from "@/components/ui/pyramid"

Maslow's hierarchy

Classic widening pyramid with 5 tiers.

tsx

<Pyramid tiers={[
  { id: "a", label: "Self-actualization" },
  { id: "e", label: "Esteem" },
  { id: "l", label: "Love & belonging" },
  { id: "s", label: "Safety" },
  { id: "p", label: "Physiological" },
]} />

Inverted pyramid (narrowing) for ranked output

Use "narrowing" when the most important tier sits at the top.

tsx

<Pyramid shape="narrowing" tiers={[
  { id: "north-star", label: "North star" },
  { id: "okrs", label: "OKRs" },
  { id: "projects", label: "Projects" },
  { id: "tasks", label: "Tasks" },
]} />

API Reference

Prop	Type	Default	Description
`tiers`required	`object`	—	Ordered top-to-bottom array of { id, label, value? }. The first entry is the apex.
`shape`	`"widening" \| "narrowing"`	widening	Tier-width direction — "widening" grows toward the base; "narrowing" shrinks toward it.
`width`	`number`	480	SVG pixel width.
`height`	`number`	360	SVG pixel height.
`gap`	`number`	4	Pixel gap between tiers.
`showValues`	`boolean`	true	Show each tier's `value` next to its label when present.
`onTierClick`	`function`	—	Called with the clicked PyramidTier.
`className`	`string`	—	Additional CSS classes on the SVG element.

AI Guidance

When to use

Visualize a ranked categorical hierarchy where tier order is meaningful but each tier is a distinct level (not a subset of the previous). Maslow-style needs hierarchy, organizational tiers, content hierarchy (north star → tasks).

When not to use

Don't use for conversion drop-off where each stage is a strict subset of the previous (use Funnel — it shows the conversion ratio between stages). Don't use for value-scaled hierarchies (use TreeMap or Sunburst). Don't use for >7 tiers — labels become unreadable.

Common mistakes

Confusing Pyramid with Funnel — Funnel encodes FLOW (value moves between stages); Pyramid encodes RANK (each tier is a distinct level)
Tier order matters — the first array element is the apex. Reversing the array flips the meaning
Passing values that don't actually rank — Pyramid doesn't sort; it trusts your order

Accessibility

The SVG carries role="img" with a <title> and <desc> summarizing tier count and shape. For agent outputs, also expose a parallel ordered list (<ol>) of labels so screen-reader users get the rank order without relying on visual position.

Related components

Token budget: 260

Verified against @hex-core/components@1.12.0

Edit this page on GitHub