# dashboardcn

> Dashboard and analytics components for shadcn/ui. KPI cards, charts, funnels, tables, and the pieces around them. Installed with the shadcn CLI, so you own the code.

# Introduction

Dashboard and analytics components for shadcn/ui, distributed through a shadcn-compatible registry.

## What it is

dashboardcn is a set of components for the parts of a product that shadcn/ui leaves to you: KPI cards, time series charts, funnels, ranked lists, calendar heatmaps, and data tables.

It is not a component library you install from npm. Each component is copied into your project with the shadcn CLI, exactly like shadcn/ui itself. You get the source, the styling lives in your Tailwind theme, and there is nothing to upgrade against.

## Why

This project started from a gap. When building a product dashboard, there was no obvious place to find components for presenting data well: KPI tiles, trend charts, funnels, ranked lists, and the cards that combine them. Where such collections existed, they were sold behind a license.

User interface code should be free. shadcn/ui set that expectation for the base primitives, and dashboardcn extends it to the data-heavy parts of a product. Everything here is MIT licensed, copied into your project as source, and yours to change.

## Foundations

- Tailwind CSS v4 and the shadcn/ui theme variables.
- shadcn/ui primitives such as Card, Table, and Chart.
- recharts for charts, through shadcn's chart wrapper.
- TanStack Table v9 for data tables.

## Radix or Base UI

Components that render only HTML and CSS work with either the Radix or Base UI flavor of shadcn/ui. Components that depend on shadcn primitives pull the flavor your project already uses.

Continue to [Installation](https://dashboardcn.com/docs/installation.md).

# Installation

Add dashboardcn components to any project that has shadcn/ui set up.

## Prerequisites

You need a project with shadcn/ui initialized. If you do not have one yet, run:

```bash
npx shadcn@latest init
```

## Add a component by URL

Every component page shows its install command. The CLI downloads the files, installs any npm dependencies, and pulls in the shadcn/ui components it needs.

```bash
npx shadcn@latest add https://dashboardcn.com/r/kpi-card.json
```

The URL form is `https://dashboardcn.com/r/<name>.json`.

## Add the registry namespace

To use the shorter `@dashboardcn/` form, register the namespace once in your `components.json`:

```json
{
  "registries": {
    "@dashboardcn": "https://dashboardcn.com/r/{name}.json"
  }
}
```

Then install by name:

```bash
npx shadcn@latest add @dashboardcn/kpi-card
```

## Agents

Every docs page is available as Markdown by appending `.md` to its URL, and [llms.txt](https://dashboardcn.com/llms.txt) indexes them all.

A skill teaches a coding agent how to pick, install, and compose the components. With the namespace registered, install it into `.claude/skills` with the shadcn CLI:

```bash
npx shadcn@latest add @dashboardcn/skill
```

Or for any agent, with the skills CLI:

```bash
npx skills add NoahGdev/dashboardcn
```

shadcn's MCP server reads every registry in `components.json`, so once the namespace is registered it can search and install from this registry too:

```bash
npx shadcn@latest mcp init --client claude
```

# Components

The primitives. Each one installs with a single command.

# Activity Heatmap

A calendar heatmap of daily activity, in the style of a contribution graph.

A calendar heatmap for shadcn/ui in the style of GitHub's contribution graph. Give it dated values and it lays out the year in weeks, with a tooltip per day and intensity steps drawn from your theme color.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/activity-heatmap.json
```

Also installs `tooltip` from shadcn/ui if missing.

## Usage

```tsx
import { ActivityHeatmap } from "@/components/ui/activity-heatmap"

<ActivityHeatmap
  data={[
    { date: "2026-09-01", value: 12 },
    { date: "2026-09-02", value: 3 },
  ]}
  unit="deploys"
/>
```

## Examples

### Default

```tsx
import { ActivityHeatmap } from "@/components/ui/activity-heatmap"

// Deterministic sample data so the demo is stable between renders.
function sampleData(days: number, end: Date) {
  let seed = 42
  const random = () => {
    seed = (seed * 1664525 + 1013904223) % 4294967296
    return seed / 4294967296
  }
  return Array.from({ length: days }, (_, i) => {
    const date = new Date(end)
    date.setDate(end.getDate() - (days - 1 - i))
    const weekend = date.getDay() === 0 || date.getDay() === 6
    const base = weekend ? 2 : 10
    const value = random() < 0.25 ? 0 : Math.round(random() * base * 3)
    const key = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`
    return { date: key, value }
  })
}

const end = new Date(2026, 8, 2)
const data = sampleData(365, end)

export default function ActivityHeatmapDemo() {
  return (
    <div className="w-full">
      <ActivityHeatmap data={data} endDate={end} unit="deploys" />
    </div>
  )
}
```

## Source

### components/ui/activity-heatmap.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

export interface ActivityDatum {
  /** ISO date, YYYY-MM-DD. */
  date: string
  value: number
}

export interface ActivityHeatmapProps extends React.ComponentProps<"div"> {
  data: ActivityDatum[]
  /** Last day shown. Defaults to today. */
  endDate?: Date
  /** Number of week columns. Ignored when `startDate` is set. */
  weeks?: number
  /** First day shown. Overrides `weeks`. */
  startDate?: Date
  /** Any CSS color. Levels are mixed from this and `--muted`. Defaults to chart-1. */
  color?: string
  /**
   * Explicit color per level, from empty to most active.
   * Overrides `color`. Length sets the number of levels.
   */
  colors?: string[]
  /** How values map to levels. `sqrt` spreads out small values. */
  scale?: "linear" | "sqrt"
  /** Cell size in px. */
  cellSize?: number
  /** Gap between cells in px. */
  gap?: number
  valueFormatter?: (value: number) => string
  /** Label for the value in the tooltip, e.g. "events". */
  unit?: string
  showMonthLabels?: boolean
  /** Which weekday labels to show along the left edge. */
  weekdayLabels?: "mwf" | "all" | "none"
  showLegend?: boolean
  /** Scroll to the most recent weeks when the grid overflows. */
  scrollToEnd?: boolean
  /** Replace the tooltip body. Return `null` to hide it for that cell. */
  renderTooltip?: (datum: { date: Date; value: number }) => React.ReactNode
  onCellClick?: (datum: { date: Date; value: number }) => void
}

const DAY = 24 * 60 * 60 * 1000
const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]

function toKey(date: Date) {
  const y = date.getFullYear()
  const m = String(date.getMonth() + 1).padStart(2, "0")
  const d = String(date.getDate()).padStart(2, "0")
  return `${y}-${m}-${d}`
}

function startOfDay(date: Date) {
  return new Date(date.getFullYear(), date.getMonth(), date.getDate())
}

function addDays(date: Date, days: number) {
  return new Date(date.getTime() + days * DAY)
}

function levelFor(
  value: number,
  max: number,
  levels: number,
  scale: "linear" | "sqrt"
) {
  if (value <= 0 || max <= 0) return 0
  let t = value / max
  if (scale === "sqrt") t = Math.sqrt(t)
  return Math.min(levels - 1, Math.max(1, Math.ceil(t * (levels - 1))))
}

function mixedColors(color: string, levels: number) {
  return Array.from({ length: levels }, (_, level) => {
    if (level === 0) return "var(--muted)"
    const pct = Math.round(25 + ((level - 1) / (levels - 2)) * 75)
    return `color-mix(in oklab, ${color} ${pct}%, var(--muted))`
  })
}

function ActivityHeatmap({
  data,
  endDate,
  weeks = 52,
  startDate,
  color = "var(--chart-1)",
  colors,
  scale = "linear",
  cellSize = 12,
  gap = 3,
  valueFormatter = (value) => formatNumber(value),
  unit = "events",
  showMonthLabels = true,
  weekdayLabels = "mwf",
  showLegend = true,
  scrollToEnd = true,
  renderTooltip,
  onCellClick,
  className,
  ...props
}: ActivityHeatmapProps) {
  const endTime = startOfDay(endDate ?? new Date()).getTime()
  const startTime = startDate
    ? startOfDay(startDate).getTime()
    : endTime - (weeks * 7 - 1) * DAY

  const values = React.useMemo(
    () => new Map(data.map((d) => [d.date, d.value])),
    [data]
  )
  const max = React.useMemo(
    () => data.reduce((acc, d) => Math.max(acc, d.value), 0),
    [data]
  )

  // Columns are full weeks, Sunday first. Days before `start` in the first
  // week and after `end` in the last are left empty rather than filled in.
  const columns = React.useMemo(() => {
    const start = new Date(startTime)
    const end = new Date(endTime)
    const result: (Date | null)[][] = []
    let cursor = addDays(start, -start.getDay())
    while (cursor <= end) {
      const week: (Date | null)[] = []
      for (let i = 0; i < 7; i++) {
        const day = addDays(cursor, i)
        week.push(day < start || day > end ? null : day)
      }
      result.push(week)
      cursor = addDays(cursor, 7)
    }
    return result
  }, [startTime, endTime])

  // Month labels span the weeks whose first shown day falls in that month.
  const months = React.useMemo(() => {
    const groups: { label: string; from: number; to: number }[] = []
    const formatter = new Intl.DateTimeFormat("en-US", { month: "short" })
    columns.forEach((week, index) => {
      const first = week.find((d): d is Date => d !== null)
      if (!first) return
      const key = `${first.getFullYear()}-${first.getMonth()}`
      const last = groups[groups.length - 1]
      if (last && last.label === key) {
        last.to = index
      } else {
        groups.push({ label: key, from: index, to: index })
      }
    })
    return groups
      .filter((g) => g.to - g.from >= 1)
      .map((g) => ({
        ...g,
        label: formatter.format(columns[g.from]!.find(Boolean) as Date),
      }))
  }, [columns])

  const palette = colors && colors.length > 1 ? colors : mixedColors(color, 5)
  const levels = palette.length

  const dateFormatter = new Intl.DateTimeFormat("en-US", {
    weekday: "short",
    month: "short",
    day: "numeric",
    year: "numeric",
  })

  const scrollRef = React.useRef<HTMLDivElement>(null)
  React.useLayoutEffect(() => {
    const node = scrollRef.current
    if (!node || !scrollToEnd) return
    node.scrollLeft = node.scrollWidth
  }, [scrollToEnd, columns.length, cellSize, gap])

  const hasHeader = showMonthLabels
  const hasWeekdays = weekdayLabels !== "none"
  const fontSize = Math.max(10, Math.min(12, cellSize))

  return (
    <div
      data-slot="activity-heatmap"
      className={cn("flex min-w-0 flex-col gap-2 text-xs", className)}
      {...props}
    >
      <div className="flex min-w-0">
        {hasWeekdays ? (
          <div
            aria-hidden
            className="grid shrink-0 pr-1"
            style={{
              gap,
              gridTemplateRows: `${hasHeader ? `${fontSize}px` : "0px"} repeat(7, ${cellSize}px)`,
            }}
          >
            <div />
            {WEEKDAYS.map((day, index) => (
              <div
                key={day}
                className="text-muted-foreground flex items-center leading-none whitespace-nowrap"
                style={{ fontSize }}
              >
                {weekdayLabels === "all" || index % 2 === 1 ? day : ""}
              </div>
            ))}
          </div>
        ) : null}
        <div
          ref={scrollRef}
          className="min-w-0 flex-1 overflow-x-auto overscroll-x-contain [scrollbar-width:thin]"
        >
          <TooltipProvider delayDuration={100} skipDelayDuration={0}>
            <div
              role="group"
              aria-label="Activity heatmap"
              className="grid w-max"
              style={{
                gap,
                gridTemplateColumns: `repeat(${columns.length}, ${cellSize}px)`,
                gridTemplateRows: `${hasHeader ? `${fontSize}px` : "0px"} repeat(7, ${cellSize}px)`,
              }}
            >
              {hasHeader
                ? months.map((month) => (
                    <div
                      key={`${month.from}-${month.label}`}
                      className="text-muted-foreground self-end leading-none whitespace-nowrap"
                      style={{
                        gridRow: 1,
                        gridColumn: `${month.from + 1} / ${month.to + 2}`,
                        fontSize,
                      }}
                    >
                      {month.label}
                    </div>
                  ))
                : null}

              {columns.map((week, weekIndex) =>
                week.map((day, dayIndex) => {
                  const style = {
                    gridColumn: weekIndex + 1,
                    gridRow: dayIndex + 2,
                  }
                  if (!day) {
                    return <div key={dayIndex} aria-hidden style={style} />
                  }
                  const value = values.get(toKey(day)) ?? 0
                  const level = levelFor(value, max, levels, scale)
                  const datum = { date: day, value }
                  const body = renderTooltip ? (
                    renderTooltip(datum)
                  ) : (
                    <>
                      <span className="font-medium tabular-nums">
                        {valueFormatter(value)} {unit}
                      </span>
                      <span className="text-background/70 block">
                        {dateFormatter.format(day)}
                      </span>
                    </>
                  )
                  const label = `${valueFormatter(value)} ${unit} on ${dateFormatter.format(day)}`

                  const cell = (
                    <button
                      type="button"
                      aria-label={label}
                      data-level={level}
                      data-date={toKey(day)}
                      onClick={onCellClick ? () => onCellClick(datum) : undefined}
                      className={cn(
                        "focus-visible:ring-ring/60 ring-inset rounded-[2px] outline-none transition-[filter] duration-100 hover:brightness-110 focus-visible:ring-2 dark:hover:brightness-125",
                        "inset-ring-foreground/6 inset-ring",
                        onCellClick ? "cursor-pointer" : "cursor-default"
                      )}
                      style={{ ...style, backgroundColor: palette[level] }}
                    />
                  )

                  if (body === null) {
                    return <React.Fragment key={dayIndex}>{cell}</React.Fragment>
                  }

                  return (
                    <Tooltip key={dayIndex}>
                      <TooltipTrigger asChild>{cell}</TooltipTrigger>
                      <TooltipContent sideOffset={4} className="text-left">
                        {body}
                      </TooltipContent>
                    </Tooltip>
                  )
                })
              )}
            </div>
          </TooltipProvider>
        </div>
      </div>

      {showLegend ? (
        <div
          className="text-muted-foreground flex items-center justify-end gap-1"
          style={{ fontSize }}
        >
          <span className="mr-0.5">Less</span>
          {palette.map((fill, level) => (
            <span
              key={level}
              className="inset-ring-foreground/6 inset-ring rounded-[2px]"
              style={{
                width: cellSize,
                height: cellSize,
                backgroundColor: fill,
              }}
            />
          ))}
          <span className="ml-0.5">More</span>
        </div>
      ) : null}
    </div>
  )
}

export { ActivityHeatmap }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Activity Rings

Concentric progress rings, one per goal, in the style of a fitness watch.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/activity-rings.json
```

## Usage

```tsx
import { ActivityRings } from "@/components/ui/activity-rings"

<ActivityRings
  rings={[
    { label: "Move", value: 1592, max: 1800, color: "var(--color-pink-500)" },
    { label: "Exercise", value: 105, max: 120, color: "var(--color-lime-500)" },
    { label: "Stand", value: 9, max: 12, color: "var(--color-sky-500)" },
  ]}
>
  <span className="text-2xl font-semibold">82%</span>
  <span className="text-muted-foreground text-xs">of goals</span>
</ActivityRings>
```

## Examples

### Default

```tsx
import { ActivityRings } from "@/components/ui/activity-rings"

export default function ActivityRingsDemo() {
  return (
    <ActivityRings
      rings={[
        { label: "Move", value: 1592, max: 1800, color: "var(--color-pink-500)" },
        { label: "Exercise", value: 105, max: 120, color: "var(--color-lime-500)" },
        { label: "Stand", value: 9, max: 12, color: "var(--color-sky-500)" },
      ]}
    >
      <span className="text-2xl font-semibold tabular-nums">82%</span>
      <span className="text-muted-foreground text-xs">of goals</span>
    </ActivityRings>
  )
}
```

## Source

### components/ui/activity-rings.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"

export interface ActivityRing {
  label: string
  /** Progress toward `max`. Values past `max` draw a full ring. */
  value: number
  /** Goal for the ring. Defaults to 100. */
  max?: number
  /** Any CSS color. Defaults to chart-1 through chart-5 in order. */
  color?: string
}

export interface ActivityRingsProps
  extends Omit<React.ComponentProps<"div">, "children"> {
  /** Outermost ring first. */
  rings: ActivityRing[]
  /** Diameter in pixels. */
  size?: number
  /** Stroke width of each ring in pixels. */
  thickness?: number
  /** Space between rings in pixels. */
  gap?: number
  /** Opacity of the unfilled track, drawn in the ring's color. */
  trackOpacity?: number
  /** Ring drawn at full strength while the rest dim. `null` shows every ring. */
  activeIndex?: number | null
  onActiveIndexChange?: (index: number | null) => void
  /** Content rendered in the middle. */
  children?: React.ReactNode
}

const defaultColors = [
  "var(--chart-1)",
  "var(--chart-2)",
  "var(--chart-3)",
  "var(--chart-4)",
  "var(--chart-5)",
]

// Round so server and client render identical attributes.
const round = (n: number) => Math.round(n * 1000) / 1000

/** Concentric progress rings, one per goal, in the style of a fitness watch. */
function ActivityRings({
  rings,
  size = 160,
  thickness = 12,
  gap = 4,
  trackOpacity = 0.2,
  activeIndex: activeProp,
  onActiveIndexChange,
  className,
  children,
  ...props
}: ActivityRingsProps) {
  const [activeState, setActiveState] = React.useState<number | null>(null)
  const active = activeProp === undefined ? activeState : activeProp
  const setActive = (index: number | null) => {
    setActiveState(index)
    onActiveIndexChange?.(index)
  }

  const center = size / 2
  const label = rings
    .map((ring) => {
      const max = ring.max ?? 100
      return `${ring.label} ${Math.round((ring.value / (max || 1)) * 100)}%`
    })
    .join(", ")

  return (
    <div
      data-slot="activity-rings"
      className={cn("relative inline-flex shrink-0", className)}
      style={{ width: size, height: size }}
      {...props}
    >
      <svg
        width={size}
        height={size}
        viewBox={`0 0 ${size} ${size}`}
        role="img"
        aria-label={label}
        className="absolute inset-0 -rotate-90"
      >
        {rings.map((ring, index) => {
          const max = ring.max ?? 100
          const fraction = Math.min(1, Math.max(0, ring.value / (max || 1)))
          const r = center - thickness / 2 - index * (thickness + gap)
          if (r <= 0) return null
          const color = ring.color ?? defaultColors[index % defaultColors.length]
          const dimmed = active !== null && active !== index
          return (
            <g
              key={ring.label}
              data-ring=""
              data-active={active === index || undefined}
              onMouseEnter={() => setActive(index)}
              onMouseLeave={() => setActive(null)}
              className="transition-opacity duration-200"
              style={{ opacity: dimmed ? 0.35 : 1 }}
            >
              <circle
                cx={center}
                cy={center}
                r={round(r)}
                fill="none"
                stroke={color}
                strokeOpacity={trackOpacity}
                strokeWidth={thickness}
              />
              {fraction > 0 ? (
                <circle
                  cx={center}
                  cy={center}
                  r={round(r)}
                  fill="none"
                  stroke={color}
                  strokeWidth={thickness}
                  strokeLinecap="round"
                  pathLength={1}
                  strokeDasharray="1 1"
                  strokeDashoffset={round(1 - fraction)}
                  className="transition-[stroke-dashoffset] duration-700 ease-out"
                />
              ) : null}
            </g>
          )
        })}
      </svg>
      {children ? (
        <div className="pointer-events-none absolute inset-0 flex flex-col items-center justify-center text-center">
          {children}
        </div>
      ) : null}
    </div>
  )
}

export { ActivityRings }
```

# Bar Chart

A single-series bar chart with gradient or striped fills, highlighted bars, and a hover marker.

A single-series bar chart for shadcn/ui with gradient or striped fills, a highlighted subset of bars, and a hover marker. Use it for spend by week, signups by day, or anything where one series and a highlighted period tell the story.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/bar-chart.json
```

Also installs `chart` from shadcn/ui if missing.

npm dependencies: `recharts`.

## Usage

```tsx
import { BarChart } from "@/components/ui/bar-chart"

<BarChart
  data={data}
  xKey="week"
  yKey="spend"
  groupKey="month"
  color="var(--color-orange-500)"
  highlight={(row) => row.month === "Mar"}
  yFormatter={(value) => formatNumber(value, { format: "currency" })}
/>
```

## Examples

### Default

```tsx
"use client"

import { BarChart } from "@/components/ui/bar-chart"
import { formatNumber } from "@/lib/format"

const months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]

const data = months.flatMap((month, m) =>
  Array.from({ length: 4 }, (_, w) => ({
    week: `${month} week ${w + 1}`,
    month,
    spend:
      month === "Mar"
        ? 1_900 + w * 470
        : 900 + Math.round(Math.abs(Math.sin(m * 4 + w)) * 500),
  }))
)

export default function BarChartDemo() {
  return (
    <BarChart
      data={data}
      xKey="week"
      yKey="spend"
      groupKey="month"
      color="var(--color-orange-500)"
      grid="none"
      highlight={(row) => row.month === "Mar"}
      yFormatter={(value) => formatNumber(value, { format: "currency" })}
      tooltipLabel={(row) => String(row.week).replace(/^\w+ /, "")}
    />
  )
}
```

### Striped

Set variant to "striped" for diagonal bands. mutedColor defaults to gray; pass the bar color for a tint of the same hue.

```tsx
"use client"

import { BarChart } from "@/components/ui/bar-chart"

const data = Array.from({ length: 14 }, (_, i) => {
  const day = i + 1
  const weekend = new Date(2026, 6, day).getDay() % 6 === 0
  return {
    date: `2026-07-${String(day).padStart(2, "0")}`,
    day,
    sessions: weekend ? 40 + i * 2 : 120 + Math.round(Math.abs(Math.cos(i)) * 90),
    weekend,
  }
})

export default function BarChartStripedDemo() {
  return (
    <BarChart
      data={data}
      xKey="date"
      yKey="sessions"
      variant="striped"
      color="var(--color-blue-500)"
      mutedColor="var(--color-blue-500)"
      barRadius={8}
      highlight={(row) => !row.weekend}
      xFormatter={(value) => String(value).slice(-2).replace(/^0/, "")}
      yFormatter={(value) => `${value} sessions`}
    />
  )
}
```

## Source

### components/ui/bar-chart.tsx

```tsx
"use client"

import * as React from "react"
import {
  Bar,
  BarChart as RechartsBarChart,
  CartesianGrid,
  Cell,
  Rectangle,
  ReferenceLine,
  XAxis,
  YAxis,
} from "recharts"

import { cn } from "@/lib/utils"
import { ChartContainer, ChartTooltip } from "@/components/ui/chart"

export type BarRow = Record<string, unknown>

export interface BarReferenceLine {
  /** Horizontal line at this y value. */
  y: number
  label?: string
  /** Any CSS color. Defaults to the muted foreground. */
  color?: string
  /** Defaults to dashed. */
  dashed?: boolean
}

export interface BarChartProps
  extends Omit<React.ComponentProps<typeof ChartContainer>, "config" | "children"> {
  data: BarRow[]
  /** Key of the x-axis value in each row. */
  xKey: string
  /** Key of the bar value in each row. */
  yKey: string
  /**
   * Key of a coarser label, e.g. "month" for weekly rows. When set, the x-axis
   * shows one tick per group centered under its bars instead of a tick per bar.
   */
  groupKey?: string
  /** "gradient" fades each bar toward the bottom; "striped" fills it with diagonal bands. */
  variant?: "gradient" | "striped" | "solid"
  /** Any CSS color for highlighted bars. Defaults to chart-1. */
  color?: string
  /** Any CSS color for bars that are not highlighted. Defaults to the muted foreground. */
  mutedColor?: string
  /** Return true for bars drawn in color. Every bar is highlighted when omitted. */
  highlight?: (row: BarRow, index: number) => boolean
  grid?: "dashed" | "solid" | "none"
  showYAxis?: boolean
  showTooltip?: boolean
  /** Draw a hollow ring on top of the hovered bar. */
  showActiveMarker?: boolean
  barRadius?: number
  /** Horizontal lines, e.g. a goal or an average. The y-axis extends to fit them. */
  referenceLines?: BarReferenceLine[]
  xFormatter?: (value: unknown) => string
  yFormatter?: (value: number) => string
  /** Secondary line of the tooltip. Defaults to the formatted x value. */
  tooltipLabel?: (row: BarRow, index: number) => React.ReactNode
  onBarClick?: (row: BarRow, index: number) => void
}

function defaultXFormatter(value: unknown) {
  if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}/.test(value)) {
    const [y, m, d] = value.split("-").map(Number)
    return new Date(y!, m! - 1, d).toLocaleDateString("en-US", {
      month: "short",
      day: "numeric",
    })
  }
  return String(value)
}

/** One tick per group, placed under the middle bar of the group. */
function groupTicks(data: BarRow[], groupKey: string) {
  const labels: string[] = Array.from({ length: data.length }, () => "")
  let start = 0
  for (let i = 1; i <= data.length; i++) {
    if (i === data.length || data[i]![groupKey] !== data[start]![groupKey]) {
      labels[Math.floor((start + i - 1) / 2)] = String(data[start]![groupKey] ?? "")
      start = i
    }
  }
  return labels
}

interface ShapeProps {
  x?: number
  y?: number
  width?: number
  height?: number
  index?: number
}

/** A single-series bar chart with gradient or striped fills, highlighted bars, and a hover marker. */
function BarChart({
  data,
  xKey,
  yKey,
  groupKey,
  variant = "gradient",
  color = "var(--chart-1)",
  mutedColor = "var(--muted-foreground)",
  highlight,
  grid = "dashed",
  showYAxis = false,
  showTooltip = true,
  showActiveMarker = true,
  barRadius = 6,
  referenceLines = [],
  xFormatter = defaultXFormatter,
  yFormatter,
  tooltipLabel,
  onBarClick,
  className,
  ...props
}: BarChartProps) {
  const id = React.useId()
  const isHighlighted = React.useCallback(
    (index: number) => (highlight ? highlight(data[index]!, index) : true),
    [data, highlight]
  )
  const tickLabels = React.useMemo(
    () => (groupKey ? groupTicks(data, groupKey) : null),
    [data, groupKey]
  )
  const fillFor = (index: number) =>
    `url(#${id}-${isHighlighted(index) ? "on" : "off"})`

  const activeBar = (shape: ShapeProps) => {
    const { x = 0, y = 0, width = 0, height = 0, index = 0 } = shape
    const on = isHighlighted(index)
    return (
      <g>
        <Rectangle {...shape} fill={fillFor(index)} />
        {showActiveMarker && height > 0 ? (
          <circle
            cx={x + width / 2}
            cy={y}
            r={4}
            fill="var(--background)"
            stroke={on ? color : mutedColor}
            strokeWidth={2}
          />
        ) : null}
      </g>
    )
  }

  return (
    <ChartContainer
      data-slot="bar-chart"
      config={{ [yKey]: { label: yKey, color } }}
      className={cn("aspect-auto h-64 w-full", className)}
      {...props}
    >
      <RechartsBarChart
        data={data}
        margin={{ top: 12, right: 8, bottom: 0, left: showYAxis ? 0 : 8 }}
        barCategoryGap="28%"
      >
        <defs>
          {variant === "gradient" ? (
            <>
              <linearGradient id={`${id}-on`} x1="0" y1="0" x2="0" y2="1">
                <stop offset="0%" stopColor={color} stopOpacity={1} />
                <stop offset="100%" stopColor={color} stopOpacity={0.6} />
              </linearGradient>
              <linearGradient id={`${id}-off`} x1="0" y1="0" x2="0" y2="1">
                <stop offset="0%" stopColor={mutedColor} stopOpacity={0.35} />
                <stop offset="100%" stopColor={mutedColor} stopOpacity={0.18} />
              </linearGradient>
            </>
          ) : variant === "striped" ? (
            <>
              {(["on", "off"] as const).map((state) => {
                const fill = state === "on" ? color : mutedColor
                const opacity = state === "on" ? 1 : 0.3
                return (
                  <pattern
                    key={state}
                    id={`${id}-${state}`}
                    patternUnits="userSpaceOnUse"
                    width={10}
                    height={10}
                    patternTransform="rotate(45)"
                  >
                    <rect width={10} height={10} fill={fill} fillOpacity={opacity} />
                    <rect
                      width={5}
                      height={10}
                      fill="var(--background)"
                      fillOpacity={0.25}
                    />
                  </pattern>
                )
              })}
            </>
          ) : (
            <>
              <linearGradient id={`${id}-on`}>
                <stop stopColor={color} />
              </linearGradient>
              <linearGradient id={`${id}-off`}>
                <stop stopColor={mutedColor} stopOpacity={0.3} />
              </linearGradient>
            </>
          )}
        </defs>
        {grid !== "none" ? (
          <CartesianGrid
            vertical={false}
            strokeDasharray={grid === "dashed" ? "6 6" : undefined}
          />
        ) : null}
        <XAxis
          dataKey={xKey}
          tickLine={false}
          axisLine={false}
          tickMargin={10}
          interval={tickLabels ? 0 : "preserveStartEnd"}
          minTickGap={tickLabels ? 0 : 24}
          tickFormatter={
            tickLabels ? (_, index) => tickLabels[index] ?? "" : (v) => xFormatter(v)
          }
        />
        <YAxis
          hide={!showYAxis}
          tickLine={false}
          axisLine={false}
          tickMargin={8}
          width={44}
          tickFormatter={yFormatter}
        />
        {showTooltip ? (
          <ChartTooltip
            cursor={false}
            isAnimationActive={false}
            content={({ active, payload }) => {
              const entry = payload?.[0]
              if (!active || !entry) return null
              const row = entry.payload as BarRow
              const index = data.indexOf(row)
              const value = Number(row[yKey])
              return (
                <div className="bg-background rounded-lg border px-3 py-2 text-xs shadow-md">
                  <div className="text-sm font-semibold tabular-nums">
                    {yFormatter ? yFormatter(value) : String(value)}
                  </div>
                  <div className="text-muted-foreground">
                    {tooltipLabel ? tooltipLabel(row, index) : xFormatter(row[xKey])}
                  </div>
                </div>
              )
            }}
          />
        ) : null}
        <Bar
          dataKey={yKey}
          radius={barRadius}
          isAnimationActive={false}
          activeBar={activeBar}
          onClick={
            onBarClick
              ? (_, index) => onBarClick(data[index]!, index)
              : undefined
          }
          className={onBarClick ? "cursor-pointer" : undefined}
        >
          {data.map((_, index) => (
            <Cell key={index} fill={fillFor(index)} />
          ))}
        </Bar>
        {referenceLines.map((line, index) => (
          <ReferenceLine
            key={index}
            y={line.y}
            ifOverflow="extendDomain"
            stroke={line.color ?? "var(--muted-foreground)"}
            strokeDasharray={line.dashed === false ? undefined : "4 4"}
            label={
              line.label
                ? {
                    value: line.label,
                    position: "insideTopRight",
                    fill: line.color ?? "var(--muted-foreground)",
                    fontSize: 11,
                  }
                : undefined
            }
          />
        ))}
      </RechartsBarChart>
    </ChartContainer>
  )
}

export { BarChart }
```

# Bar List

A ranked list with proportional bars, for top pages, referrers, or countries.

A ranked list with a proportional bar behind each row, the pattern analytics tools use for top pages, referrers, and countries. Rows are plain elements, so they can be links, and the bars pick up your shadcn theme color.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/bar-list.json
```

## Usage

```tsx
import { BarList } from "@/components/ui/bar-list"

<BarList
  data={[
    { name: "/", value: 48210, href: "/analytics?page=/" },
    { name: "/pricing", value: 21480 },
  ]}
  showPercentage
/>
```

## Examples

### Default

```tsx
import { BarList } from "@/components/ui/bar-list"

const pages = [
  { name: "/", value: 48_210, href: "#" },
  { name: "/pricing", value: 21_480, href: "#" },
  { name: "/docs", value: 18_930, href: "#" },
  { name: "/blog/launch-week", value: 9_120, href: "#" },
  { name: "/changelog", value: 4_305, href: "#" },
  { name: "/careers", value: 1_870, href: "#" },
]

export default function BarListDemo() {
  return (
    <div className="w-full max-w-lg">
      <div className="text-muted-foreground mb-2 flex justify-between text-xs">
        <span>Page</span>
        <span>Visitors</span>
      </div>
      <BarList data={pages} showPercentage />
    </div>
  )
}
```

## Source

### components/ui/bar-list.tsx

```tsx
import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber } from "@/lib/format"

export interface BarListItem {
  name: string
  value: number
  /** Renders the label as a link. */
  href?: string
  icon?: React.ReactNode
  /** Stable key when names can repeat. */
  key?: string
}

export interface BarListProps extends React.ComponentProps<"div"> {
  data: BarListItem[]
  valueFormatter?: (value: number) => string
  sortOrder?: "descending" | "ascending" | "none"
  /** Any CSS color. Defaults to chart-1. */
  color?: string
  /** Show each row's share of the total next to its value. */
  showPercentage?: boolean
  onItemClick?: (item: BarListItem) => void
}

function BarList({
  data,
  valueFormatter = (value) => formatNumber(value, { format: "compact" }),
  sortOrder = "descending",
  color = "var(--chart-1)",
  showPercentage = false,
  onItemClick,
  className,
  ...props
}: BarListProps) {
  const items = React.useMemo(() => {
    if (sortOrder === "none") return data
    const sorted = [...data].sort((a, b) => a.value - b.value)
    return sortOrder === "descending" ? sorted.reverse() : sorted
  }, [data, sortOrder])
  const max = Math.max(...items.map((item) => item.value), 0)
  const total = items.reduce((sum, item) => sum + item.value, 0)

  return (
    <div
      data-slot="bar-list"
      className={cn("flex flex-col gap-1.5", className)}
      {...props}
    >
      {items.map((item) => {
        const width = max > 0 ? (item.value / max) * 100 : 0
        const share = total > 0 ? item.value / total : 0
        const interactive = Boolean(item.href || onItemClick)
        const Label = item.href ? "a" : onItemClick ? "button" : "div"

        return (
          <div
            key={item.key ?? item.name}
            data-slot="bar-list-row"
            className="flex items-center gap-3 text-sm"
          >
            <div className="relative flex h-8 min-w-0 flex-1 items-center">
              <div
                aria-hidden="true"
                className="absolute inset-y-0 left-0 rounded-md transition-[width] duration-300"
                style={{
                  width: `${width}%`,
                  backgroundColor: `color-mix(in oklab, ${color} 20%, transparent)`,
                }}
              />
              <Label
                {...(item.href ? { href: item.href } : {})}
                {...(onItemClick && !item.href
                  ? { type: "button" as const, onClick: () => onItemClick(item) }
                  : {})}
                className={cn(
                  "relative flex min-w-0 items-center gap-2 px-2 text-left",
                  interactive && "hover:underline"
                )}
              >
                {item.icon ? (
                  <span className="text-muted-foreground shrink-0 [&>svg]:size-4">
                    {item.icon}
                  </span>
                ) : null}
                <span className="truncate">{item.name}</span>
              </Label>
            </div>
            <div className="flex shrink-0 items-center gap-2 tabular-nums">
              <span className="font-medium">{valueFormatter(item.value)}</span>
              {showPercentage ? (
                <span className="text-muted-foreground w-12 text-right text-xs">
                  {formatNumber(share, { format: "percent" })}
                </span>
              ) : null}
            </div>
          </div>
        )
      })}
    </div>
  )
}

export { BarList }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Composed Chart

Mix areas, lines, and bars in one chart with dual axes, reference lines, peak markers, and hatched bars.

A composed chart for shadcn/ui that mixes areas, lines, and bars in one plot, with a second y-axis for series on different scales, reference lines, peak markers, and hatched bars for forecast or projected values.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/composed-chart.json
```

Also installs `chart` from shadcn/ui if missing.

npm dependencies: `recharts`.

## Usage

```tsx
import { ComposedChart } from "@/components/ui/composed-chart"

<ComposedChart
  data={data}
  xKey="month"
  series={[
    { key: "sales", label: "Sales", type: "area", highlightMax: true },
    { key: "goal", label: "Goal", type: "line", dashed: true },
  ]}
  referenceLines={[{ y: 50000, label: "Target" }]}
  showYAxis
/>
```

## Examples

### Default

```tsx
"use client"

import { ComposedChart } from "@/components/ui/composed-chart"
import { formatNumber } from "@/lib/format"

const data = [
  { month: "Jan", sales: 42_000, goal: 40_000 },
  { month: "Feb", sales: 38_500, goal: 41_000 },
  { month: "Mar", sales: 47_200, goal: 42_000 },
  { month: "Apr", sales: 51_800, goal: 43_000 },
  { month: "May", sales: 49_100, goal: 44_000 },
  { month: "Jun", sales: 56_400, goal: 45_000 },
  { month: "Jul", sales: 61_900, goal: 46_000 },
  { month: "Aug", sales: 58_300, goal: 47_000 },
]

export default function ComposedChartDemo() {
  return (
    <ComposedChart
      data={data}
      xKey="month"
      series={[
        { key: "sales", label: "Sales", type: "area", highlightMax: true },
        { key: "goal", label: "Goal", type: "line", dashed: true, color: "var(--muted-foreground)" },
      ]}
      referenceLines={[{ y: 50_000, label: "Target" }]}
      yFormatter={(v) => formatNumber(v, { format: "compact" })}
      showYAxis
      showLegend
    />
  )
}
```

### Dual axis

Give a series axis: "right" to plot it against a second y-axis.

```tsx
"use client"

import { ComposedChart } from "@/components/ui/composed-chart"
import { formatNumber } from "@/lib/format"

const data = Array.from({ length: 14 }, (_, i) => ({
  date: `2026-08-${String(i + 4).padStart(2, "0")}`,
  views: 12_000 + Math.round(Math.sin(i / 2) * 3_000 + i * 400),
  sales: 180 + Math.round(Math.cos(i / 3) * 40 + i * 12),
}))

export default function ComposedChartDualAxisDemo() {
  return (
    <ComposedChart
      data={data}
      xKey="date"
      series={[
        { key: "views", label: "Page views", type: "bar", color: "var(--chart-1)" },
        { key: "sales", label: "Sales", type: "line", axis: "right", color: "var(--chart-4)", dots: true },
      ]}
      yFormatter={(v) => formatNumber(v, { format: "compact" })}
      rightYFormatter={(v) => formatNumber(v)}
      showYAxis
      showLegend
    />
  )
}
```

### Grouped and hatched bars

Bars group side by side unless they share a stackId. pattern: "hatched" fills a bar with diagonal lines.

```tsx
"use client"

import { ComposedChart } from "@/components/ui/composed-chart"
import { formatNumber } from "@/lib/format"

const data = [
  { region: "NA", air: 420, sea: 1_280 },
  { region: "EU", air: 380, sea: 1_040 },
  { region: "APAC", air: 610, sea: 1_720 },
  { region: "LATAM", air: 140, sea: 460 },
  { region: "MEA", air: 90, sea: 310 },
]

export default function ComposedChartHatchedDemo() {
  return (
    <ComposedChart
      data={data}
      xKey="region"
      series={[
        { key: "sea", label: "Sea freight", type: "bar" },
        { key: "air", label: "Air freight", type: "bar", pattern: "hatched", color: "var(--chart-4)" },
      ]}
      yFormatter={(v) => `${formatNumber(v)} t`}
      showYAxis
      showLegend
    />
  )
}
```

## Source

### components/ui/composed-chart.tsx

```tsx
"use client"

import * as React from "react"
import {
  Area,
  Bar,
  CartesianGrid,
  ComposedChart as RechartsComposedChart,
  Line,
  ReferenceDot,
  ReferenceLine,
  XAxis,
  YAxis,
} from "recharts"

import { cn } from "@/lib/utils"
import {
  ChartContainer,
  ChartLegend,
  ChartLegendContent,
  ChartTooltip,
  ChartTooltipContent,
  type ChartConfig,
} from "@/components/ui/chart"

export interface ComposedSeries {
  /** Key in each data row. */
  key: string
  label: string
  type?: "area" | "line" | "bar"
  /** Any CSS color. Defaults to chart-1 through chart-5 in order. */
  color?: string
  /** Plot against the right axis. */
  axis?: "left" | "right"
  /** Series with the same stackId stack on top of each other. */
  stackId?: string
  /** Bars only: fill with a diagonal hatch instead of a solid color. */
  pattern?: "solid" | "hatched"
  /** Lines and areas only. */
  dashed?: boolean
  curve?: "monotone" | "linear" | "step"
  /** Lines only: draw a dot on every point. */
  dots?: boolean
  /** Mark the highest point of this series with a dot. */
  highlightMax?: boolean
}

export interface ReferenceLineSpec {
  /** Horizontal line at this y value. */
  y?: number
  /** Vertical line at this x value. */
  x?: string | number
  label?: string
  /** Any CSS color. Defaults to the muted foreground. */
  color?: string
  dashed?: boolean
  axis?: "left" | "right"
}

export interface ComposedChartProps
  extends Omit<React.ComponentProps<typeof ChartContainer>, "config" | "children"> {
  data: Record<string, unknown>[]
  /** Key of the x-axis value in each row. */
  xKey: string
  series: ComposedSeries[]
  referenceLines?: ReferenceLineSpec[]
  showGrid?: boolean
  showYAxis?: boolean
  showLegend?: boolean
  showTooltip?: boolean
  xFormatter?: (value: unknown) => string
  yFormatter?: (value: number) => string
  rightYFormatter?: (value: number) => string
  barRadius?: number
  /** "zero" starts the y-axis at 0; "auto" fits it to the data. */
  yDomain?: "zero" | "auto" | [number, number]
}

function defaultXFormatter(value: unknown) {
  if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}/.test(value)) {
    const [y, m, d] = value.split("-").map(Number)
    return new Date(y!, m! - 1, d).toLocaleDateString("en-US", {
      month: "short",
      day: "numeric",
    })
  }
  return String(value)
}

function ComposedChart({
  data,
  xKey,
  series,
  referenceLines = [],
  showGrid = true,
  showYAxis = false,
  showLegend = false,
  showTooltip = true,
  xFormatter = defaultXFormatter,
  yFormatter,
  rightYFormatter,
  barRadius = 4,
  yDomain = "zero",
  className,
  ...props
}: ComposedChartProps) {
  const id = React.useId()
  const config = Object.fromEntries(
    series.map((s, index) => [
      s.key,
      { label: s.label, color: s.color ?? `var(--chart-${(index % 5) + 1})` },
    ])
  ) satisfies ChartConfig
  const hasRightAxis = series.some((s) => s.axis === "right")
  const domain =
    yDomain === "auto" ? (["auto", "auto"] as const) : yDomain === "zero" ? undefined : yDomain

  const maxPoints = series
    .filter((s) => s.highlightMax)
    .map((s) => {
      let best: { x: unknown; y: number } | null = null
      for (const row of data) {
        const y = Number(row[s.key])
        if (Number.isFinite(y) && (!best || y > best.y)) best = { x: row[xKey], y }
      }
      return best ? { ...best, key: s.key, axis: s.axis ?? "left" } : null
    })
    .filter((p): p is NonNullable<typeof p> => p !== null)

  return (
    <ChartContainer
      data-slot="composed-chart"
      config={config}
      className={cn("aspect-auto h-64 w-full", className)}
      {...props}
    >
      <RechartsComposedChart
        data={data}
        margin={{ top: 8, right: hasRightAxis ? 0 : 8, bottom: 0, left: showYAxis ? 0 : 8 }}
      >
        <defs>
          {series.map((s) => (
            <React.Fragment key={s.key}>
              <linearGradient id={`${id}-fill-${s.key}`} x1="0" y1="0" x2="0" y2="1">
                <stop offset="5%" stopColor={`var(--color-${s.key})`} stopOpacity={0.5} />
                <stop offset="95%" stopColor={`var(--color-${s.key})`} stopOpacity={0.05} />
              </linearGradient>
              <pattern
                id={`${id}-hatch-${s.key}`}
                patternUnits="userSpaceOnUse"
                width={6}
                height={6}
                patternTransform="rotate(45)"
              >
                <rect width={6} height={6} fill={`var(--color-${s.key})`} fillOpacity={0.15} />
                <rect width={2} height={6} fill={`var(--color-${s.key})`} />
              </pattern>
            </React.Fragment>
          ))}
        </defs>
        {showGrid ? <CartesianGrid vertical={false} /> : null}
        <XAxis
          dataKey={xKey}
          tickLine={false}
          axisLine={false}
          tickMargin={8}
          minTickGap={32}
          tickFormatter={xFormatter}
        />
        <YAxis
          yAxisId="left"
          domain={domain}
          hide={!showYAxis}
          tickLine={false}
          axisLine={false}
          tickMargin={8}
          width={44}
          tickFormatter={yFormatter}
        />
        {hasRightAxis ? (
          <YAxis
            yAxisId="right"
            orientation="right"
            domain={domain}
            hide={!showYAxis}
            tickLine={false}
            axisLine={false}
            tickMargin={8}
            width={44}
            tickFormatter={rightYFormatter ?? yFormatter}
          />
        ) : null}
        {showTooltip ? (
          <ChartTooltip
            cursor={false}
            content={
              <ChartTooltipContent
                indicator="dot"
                labelFormatter={(value) => xFormatter(value)}
                formatter={(value, name, item) => {
                  const s = series.find((entry) => entry.key === name)
                  const fmt = s?.axis === "right" ? (rightYFormatter ?? yFormatter) : yFormatter
                  return (
                    <div className="flex w-full items-center gap-2">
                      <span
                        className="size-2 shrink-0 rounded-[2px]"
                        style={{ backgroundColor: item.color }}
                      />
                      <span className="text-muted-foreground flex-1">
                        {config[name as string]?.label ?? name}
                      </span>
                      <span className="font-mono font-medium tabular-nums">
                        {fmt ? fmt(Number(value)) : String(value)}
                      </span>
                    </div>
                  )
                }}
              />
            }
          />
        ) : null}
        {showLegend ? <ChartLegend content={<ChartLegendContent />} /> : null}
        {series.map((s) => {
          const color = `var(--color-${s.key})`
          const common = {
            dataKey: s.key,
            yAxisId: s.axis ?? "left",
            stackId: s.stackId,
            isAnimationActive: false,
          }
          if (s.type === "bar") {
            return (
              <Bar
                key={s.key}
                {...common}
                fill={s.pattern === "hatched" ? `url(#${id}-hatch-${s.key})` : color}
                stroke={s.pattern === "hatched" ? color : undefined}
                strokeWidth={s.pattern === "hatched" ? 1 : 0}
                radius={s.stackId ? 0 : barRadius}
              />
            )
          }
          if (s.type === "line") {
            return (
              <Line
                key={s.key}
                {...common}
                type={s.curve ?? "monotone"}
                stroke={color}
                strokeWidth={2}
                strokeDasharray={s.dashed ? "4 4" : undefined}
                dot={s.dots ? { r: 3, fill: color, strokeWidth: 0 } : false}
                activeDot={{ r: 4 }}
              />
            )
          }
          return (
            <Area
              key={s.key}
              {...common}
              type={s.curve ?? "monotone"}
              stroke={color}
              strokeWidth={2}
              strokeDasharray={s.dashed ? "4 4" : undefined}
              fill={`url(#${id}-fill-${s.key})`}
              dot={false}
            />
          )
        })}
        {referenceLines.map((line, index) => (
          <ReferenceLine
            key={index}
            y={line.y}
            x={line.x}
            yAxisId={line.axis ?? "left"}
            stroke={line.color ?? "var(--muted-foreground)"}
            strokeDasharray={line.dashed === false ? undefined : "4 4"}
            label={
              line.label
                ? {
                    value: line.label,
                    position: line.y !== undefined ? "insideTopRight" : "insideTopLeft",
                    fill: line.color ?? "var(--muted-foreground)",
                    fontSize: 11,
                  }
                : undefined
            }
          />
        ))}
        {maxPoints.map((point) => (
          <ReferenceDot
            key={point.key}
            x={point.x as string | number}
            y={point.y}
            yAxisId={point.axis}
            r={4}
            fill={`var(--color-${point.key})`}
            stroke="var(--background)"
            strokeWidth={2}
          />
        ))}
      </RechartsComposedChart>
    </ChartContainer>
  )
}

export { ComposedChart }
```

# Data Table

A sortable, filterable, paginated table with column visibility, row selection, sticky and reorderable columns, and loading states, built on TanStack Table v9.

A complete data table for shadcn/ui on TanStack Table v9: sorting, filtering, pagination, column visibility, row selection, sticky and reorderable columns, and loading states. It uses the shadcn Table primitives and is the table you would build yourself after the shadcn docs example, finished.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/data-table.json
```

Also installs `table`, `button`, `input`, `dropdown-menu`, `checkbox`, `skeleton` from shadcn/ui if missing.

npm dependencies: `@tanstack/react-table`, `lucide-react`.

## Usage

```tsx
import {
  DataTable,
  DataTableColumnHeader,
  createDataTableColumnHelper,
} from "@/components/ui/data-table"

const helper = createDataTableColumnHelper<Row>()

const columns = helper.columns([
  helper.accessor("path", {
    header: ({ column }) => <DataTableColumnHeader column={column} title="Page" />,
  }),
  helper.accessor("views", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Views" align="right" />
    ),
    cell: ({ row }) => <div className="text-right">{row.original.views}</div>,
  }),
])

<DataTable columns={columns} data={rows} searchKey="path" />

// Or own the instance and lay the parts out yourself.
const table = useDataTable({ columns, data: rows, pageSize: 5 })

<DataTableToolbar>
  <DataTableSearch table={table} column="path" />
  <DataTableViewOptions table={table} className="ml-auto" />
</DataTableToolbar>
<DataTableContent table={table} pending={isFetching} stickyHeader maxHeight={340} />
<DataTablePagination table={table} pageSizeOptions={[5, 10, 25]} />
```

## Examples

### Default

```tsx
"use client"

import { Badge } from "@/components/ui/badge"
import { formatNumber } from "@/lib/format"
import {
  DataTable,
  DataTableColumnHeader,
  createDataTableColumnHelper,
} from "@/components/ui/data-table"

type PageRow = {
  path: string
  views: number
  visitors: number
  bounceRate: number
  status: "indexed" | "noindex" | "redirect"
}

const pages: PageRow[] = [
  { path: "/", views: 48_210, visitors: 31_400, bounceRate: 0.42, status: "indexed" },
  { path: "/pricing", views: 21_480, visitors: 16_200, bounceRate: 0.38, status: "indexed" },
  { path: "/docs", views: 18_930, visitors: 9_800, bounceRate: 0.21, status: "indexed" },
  { path: "/docs/installation", views: 12_310, visitors: 7_900, bounceRate: 0.19, status: "indexed" },
  { path: "/blog/launch-week", views: 9_120, visitors: 8_400, bounceRate: 0.61, status: "indexed" },
  { path: "/changelog", views: 4_305, visitors: 2_900, bounceRate: 0.33, status: "indexed" },
  { path: "/careers", views: 1_870, visitors: 1_600, bounceRate: 0.55, status: "indexed" },
  { path: "/legacy/signup", views: 940, visitors: 910, bounceRate: 0.9, status: "redirect" },
  { path: "/internal/status", views: 610, visitors: 40, bounceRate: 0.12, status: "noindex" },
  { path: "/blog/hiring", views: 430, visitors: 400, bounceRate: 0.7, status: "indexed" },
  { path: "/terms", views: 220, visitors: 210, bounceRate: 0.81, status: "indexed" },
  { path: "/privacy", views: 190, visitors: 185, bounceRate: 0.84, status: "indexed" },
]

const helper = createDataTableColumnHelper<PageRow>()

const columns = helper.columns([
  helper.accessor("path", {
    header: ({ column }) => <DataTableColumnHeader column={column} title="Page" />,
    cell: ({ row }) => (
      <span className="font-mono text-xs">{row.original.path}</span>
    ),
  }),
  helper.accessor("status", {
    header: "Status",
    cell: ({ row }) => (
      <Badge variant={row.original.status === "indexed" ? "secondary" : "outline"}>
        {row.original.status}
      </Badge>
    ),
  }),
  helper.accessor("views", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Views" align="right" />
    ),
    cell: ({ row }) => (
      <div className="text-right tabular-nums">
        {formatNumber(row.original.views)}
      </div>
    ),
  }),
  helper.accessor("visitors", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Visitors" align="right" />
    ),
    cell: ({ row }) => (
      <div className="text-right tabular-nums">
        {formatNumber(row.original.visitors)}
      </div>
    ),
  }),
  helper.accessor("bounceRate", {
    id: "bounce",
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Bounce" align="right" />
    ),
    cell: ({ row }) => (
      <div className="text-right tabular-nums">
        {formatNumber(row.original.bounceRate, { format: "percent", maximumFractionDigits: 0 })}
      </div>
    ),
  }),
])

export default function DataTableDemo() {
  return (
    <DataTable
      columns={columns}
      data={pages}
      searchKey="path"
      searchPlaceholder="Filter pages..."
      pageSize={8}
      className="w-full"
    />
  )
}
```

### Loading and refreshing

loading swaps the rows for a skeleton. pending keeps the rows and dims them, which is what a filter change wants — the table reports it is busy without collapsing and jumping.

```tsx
"use client"

import * as React from "react"
import { RefreshCw } from "lucide-react"

import { Button } from "@/components/ui/button"
import { formatNumber } from "@/lib/format"
import {
  DataTable,
  DataTableColumnHeader,
  createDataTableColumnHelper,
} from "@/components/ui/data-table"
import { PeriodTabs } from "@/components/ui/period-tabs"

type ChannelRow = {
  channel: string
  sessions: number
  signups: number
  revenue: number
}

type Period = "week" | "month" | "year"

const byPeriod: Record<Period, ChannelRow[]> = {
  week: [
    { channel: "Organic search", sessions: 18_420, signups: 412, revenue: 24_180 },
    { channel: "Paid search", sessions: 9_310, signups: 288, revenue: 19_640 },
    { channel: "Direct", sessions: 7_860, signups: 154, revenue: 11_200 },
    { channel: "Referral", sessions: 3_240, signups: 96, revenue: 7_480 },
    { channel: "Email", sessions: 2_180, signups: 141, revenue: 9_320 },
  ],
  month: [
    { channel: "Organic search", sessions: 74_910, signups: 1_684, revenue: 98_400 },
    { channel: "Paid search", sessions: 38_260, signups: 1_192, revenue: 81_050 },
    { channel: "Direct", sessions: 31_540, signups: 623, revenue: 45_900 },
    { channel: "Referral", sessions: 13_080, signups: 388, revenue: 30_120 },
    { channel: "Email", sessions: 8_940, signups: 574, revenue: 38_760 },
  ],
  year: [
    { channel: "Organic search", sessions: 892_300, signups: 20_140, revenue: 1_184_000 },
    { channel: "Paid search", sessions: 461_800, signups: 14_320, revenue: 972_500 },
    { channel: "Direct", sessions: 379_400, signups: 7_460, revenue: 551_200 },
    { channel: "Referral", sessions: 156_700, signups: 4_610, revenue: 361_400 },
    { channel: "Email", sessions: 107_200, signups: 6_890, revenue: 465_300 },
  ],
}

const helper = createDataTableColumnHelper<ChannelRow>()

const columns = helper.columns([
  helper.accessor("channel", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Channel" />
    ),
  }),
  helper.accessor("sessions", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Sessions" align="right" />
    ),
    cell: ({ row }) => (
      <div className="text-right tabular-nums">
        {formatNumber(row.original.sessions)}
      </div>
    ),
  }),
  helper.accessor("signups", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Signups" align="right" />
    ),
    cell: ({ row }) => (
      <div className="text-right tabular-nums">
        {formatNumber(row.original.signups)}
      </div>
    ),
  }),
  helper.accessor("revenue", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Revenue" align="right" />
    ),
    cell: ({ row }) => (
      <div className="text-right tabular-nums">
        {formatNumber(row.original.revenue, { format: "currency", compact: true })}
      </div>
    ),
  }),
])

export default function DataTableLoadingDemo() {
  const [period, setPeriod] = React.useState<Period>("month")
  const [data, setData] = React.useState(byPeriod.month)
  const [loading, setLoading] = React.useState(false)
  const [pending, setPending] = React.useState(false)

  // Stand-in for a fetch. A first load has no rows to show, so it swaps in the
  // skeleton; a filter change already has rows, so it dims them instead.
  const load = (next: Period, mode: "loading" | "pending") => {
    const setBusy = mode === "loading" ? setLoading : setPending
    setPeriod(next)
    setBusy(true)
    window.setTimeout(() => {
      setData(byPeriod[next])
      setBusy(false)
    }, 900)
  }

  return (
    <DataTable
      columns={columns}
      data={data}
      searchKey="channel"
      searchPlaceholder="Filter channels..."
      loading={loading}
      pending={pending}
      pageSize={5}
      showPagination={false}
      toolbar={
        <>
          <PeriodTabs
            value={period}
            onValueChange={(next) => load(next as Period, "pending")}
            size="sm"
          />
          <Button
            variant="outline"
            size="sm"
            className="h-8"
            onClick={() => load(period, "loading")}
          >
            <RefreshCw />
            Reload
          </Button>
        </>
      }
      className="w-full"
    />
  )
}
```

### Row selection

Put createSelectionColumn() first in the column list and set enableRowSelection. A bar with your actions appears while rows are selected. Pass getRowId so a selection survives sorting and paging, and shift-click a checkbox to take a range.

```tsx
"use client"

import * as React from "react"
import { Download, Trash2 } from "lucide-react"

import { Badge } from "@/components/ui/badge"
import { Button } from "@/components/ui/button"
import { formatNumber } from "@/lib/format"
import {
  DataTable,
  DataTableColumnHeader,
  createDataTableColumnHelper,
  createSelectionColumn,
} from "@/components/ui/data-table"

type InvoiceRow = {
  id: string
  customer: string
  status: "paid" | "open" | "overdue"
  issued: string
  amount: number
}

const invoices: InvoiceRow[] = [
  { id: "INV-2841", customer: "Northwind Traders", status: "paid", issued: "2026-08-02", amount: 12_400 },
  { id: "INV-2842", customer: "Contoso", status: "open", issued: "2026-08-04", amount: 3_180 },
  { id: "INV-2843", customer: "Fabrikam", status: "overdue", issued: "2026-07-11", amount: 8_960 },
  { id: "INV-2844", customer: "Tailspin Toys", status: "paid", issued: "2026-08-09", amount: 1_240 },
  { id: "INV-2845", customer: "Adventure Works", status: "open", issued: "2026-08-12", amount: 22_500 },
  { id: "INV-2846", customer: "Proseware", status: "paid", issued: "2026-08-14", amount: 640 },
  { id: "INV-2847", customer: "Wide World Importers", status: "overdue", issued: "2026-06-28", amount: 15_820 },
  { id: "INV-2848", customer: "Lucerne Publishing", status: "open", issued: "2026-08-19", amount: 4_075 },
]

const helper = createDataTableColumnHelper<InvoiceRow>()

const columns = helper.columns([
  createSelectionColumn<InvoiceRow>(),
  helper.accessor("id", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Invoice" />
    ),
    cell: ({ row }) => (
      <span className="font-mono text-xs">{row.original.id}</span>
    ),
  }),
  helper.accessor("customer", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Customer" />
    ),
  }),
  helper.accessor("status", {
    header: "Status",
    cell: ({ row }) => (
      <Badge
        variant={
          row.original.status === "paid"
            ? "secondary"
            : row.original.status === "overdue"
              ? "destructive"
              : "outline"
        }
      >
        {row.original.status}
      </Badge>
    ),
  }),
  helper.accessor("issued", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Issued" />
    ),
    sortFn: "datetime",
    cell: ({ row }) => (
      <span className="text-muted-foreground tabular-nums">
        {row.original.issued}
      </span>
    ),
  }),
  helper.accessor("amount", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Amount" align="right" />
    ),
    cell: ({ row }) => (
      <div className="text-right tabular-nums">
        {formatNumber(row.original.amount, { format: "currency" })}
      </div>
    ),
  }),
])

export default function DataTableSelectionDemo() {
  const [selected, setSelected] = React.useState<string[]>([])

  return (
    <div className="flex w-full flex-col gap-3">
      <DataTable
        columns={columns}
        data={invoices}
        searchKey="customer"
        searchPlaceholder="Filter customers..."
        enableRowSelection
        getRowId={(row) => row.id}
        onRowSelectionChange={(selection) =>
          setSelected(Object.keys(selection))
        }
        selectionActions={
          <>
            <Button variant="outline" size="sm" className="h-8">
              <Download />
              Export
            </Button>
            <Button variant="outline" size="sm" className="h-8">
              <Trash2 />
              Void
            </Button>
          </>
        }
        pageSize={0}
        showPagination={false}
      />
      <p className="text-muted-foreground text-sm">
        Shift-click a checkbox to select a range. Selected:{" "}
        {selected.length ? selected.join(", ") : "none"}
      </p>
    </div>
  )
}
```

### Row actions

A trailing column with a ⋯ menu. Right-clicking anywhere in a row offers the same actions through shadcn's ContextMenu — not a table feature: renderRow wraps the row in a trigger, and one array of actions feeds both menus. Drop it if you do not want it.

```tsx
"use client"

import * as React from "react"
import { MoreHorizontal } from "lucide-react"

import { Badge } from "@/components/ui/badge"
import { Button } from "@/components/ui/button"
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuSeparator,
  ContextMenuTrigger,
} from "@/components/ui/context-menu"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
import {
  DataTable,
  DataTableColumnHeader,
  createDataTableColumnHelper,
  type DataTableRow,
} from "@/components/ui/data-table"

type KeyRow = {
  name: string
  scope: "read" | "write" | "admin"
  lastUsed: string
}

const keys: KeyRow[] = [
  { name: "Production server", scope: "admin", lastUsed: "2 minutes ago" },
  { name: "Staging server", scope: "write", lastUsed: "1 hour ago" },
  { name: "Analytics export", scope: "read", lastUsed: "Yesterday" },
  { name: "CI pipeline", scope: "write", lastUsed: "3 days ago" },
  { name: "Partner sandbox", scope: "read", lastUsed: "2 weeks ago" },
  { name: "Legacy webhook", scope: "read", lastUsed: "Never" },
]

/** One list of actions, rendered by whichever menu asked for it. */
const actions = [
  { label: "Copy key id" },
  { label: "Edit scope" },
  { label: "Revoke", separated: true, destructive: true },
]

function RowMenu({ row }: { row: DataTableRow<KeyRow> }) {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="ghost" size="icon" className="size-7">
          <MoreHorizontal />
          <span className="sr-only">Open menu for {row.original.name}</span>
        </Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent align="end" className="w-40">
        {actions.map((action) => (
          <React.Fragment key={action.label}>
            {action.separated ? <DropdownMenuSeparator /> : null}
            <DropdownMenuItem
              variant={action.destructive ? "destructive" : "default"}
            >
              {action.label}
            </DropdownMenuItem>
          </React.Fragment>
        ))}
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

const helper = createDataTableColumnHelper<KeyRow>()

const columns = helper.columns([
  helper.accessor("name", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Key" />
    ),
    cell: ({ row }) => <span className="font-medium">{row.original.name}</span>,
  }),
  helper.accessor("scope", {
    header: "Scope",
    cell: ({ row }) => (
      <Badge variant={row.original.scope === "admin" ? "secondary" : "outline"}>
        {row.original.scope}
      </Badge>
    ),
  }),
  helper.accessor("lastUsed", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Last used" />
    ),
    cell: ({ row }) => (
      <span className="text-muted-foreground">{row.original.lastUsed}</span>
    ),
  }),
  helper.display({
    id: "actions",
    size: 48,
    enableHiding: false,
    header: () => <span className="sr-only">Actions</span>,
    cell: ({ row }) => (
      <div className="flex justify-end">
        <RowMenu row={row} />
      </div>
    ),
  }),
])

export default function DataTableRowActionsDemo() {
  return (
    <div className="flex w-full flex-col gap-3">
      <DataTable
        columns={columns}
        data={keys}
        searchKey="name"
        searchPlaceholder="Filter keys..."
        pageSize={0}
        showPagination={false}
        // renderRow is the escape hatch: wrap the row in whatever you like.
        // Here it becomes a context menu trigger, so the same actions are a
        // right-click away anywhere in the row.
        renderRow={(row, element) => (
          <ContextMenu>
            <ContextMenuTrigger asChild>{element}</ContextMenuTrigger>
            <ContextMenuContent className="w-40">
              {actions.map((action) => (
                <React.Fragment key={action.label}>
                  {action.separated ? <ContextMenuSeparator /> : null}
                  <ContextMenuItem
                    variant={action.destructive ? "destructive" : "default"}
                  >
                    {action.label}
                  </ContextMenuItem>
                </React.Fragment>
              ))}
            </ContextMenuContent>
          </ContextMenu>
        )}
      />
      <p className="text-muted-foreground text-sm">
        Right-click a row for the same actions as its ⋯ button.
      </p>
    </div>
  )
}
```

### Sticky columns

pinnedColumns holds columns against either edge while the rest scroll sideways, so the actions menu stays reachable at any scroll position. stickyHeader and maxHeight do the same vertically. Pinned columns need a size on the column def, because the sticky offsets are measured from it. The right-click menu from the previous example is in here too — it is written in the example, not a table feature, so take it or leave it.

```tsx
"use client"

import { MoreHorizontal } from "lucide-react"

import { Badge } from "@/components/ui/badge"
import { Button } from "@/components/ui/button"
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuTrigger,
} from "@/components/ui/context-menu"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
import { formatNumber } from "@/lib/format"
import {
  DataTable,
  DataTableColumnHeader,
  createDataTableColumnHelper,
  type DataTableRow,
} from "@/components/ui/data-table"

type CampaignRow = {
  campaign: string
  channel: string
  status: "live" | "paused" | "draft"
  impressions: number
  clicks: number
  ctr: number
  cpc: number
  spend: number
  conversions: number
  cpa: number
  roas: number
}

const campaigns: CampaignRow[] = [
  { campaign: "Spring launch — brand", channel: "Search", status: "live", impressions: 1_284_000, clicks: 38_400, ctr: 0.0299, cpc: 1.42, spend: 54_528, conversions: 1_842, cpa: 29.6, roas: 4.1 },
  { campaign: "Spring launch — retarget", channel: "Display", status: "live", impressions: 2_940_000, clicks: 21_600, ctr: 0.0073, cpc: 0.68, spend: 14_688, conversions: 612, cpa: 24, roas: 3.4 },
  { campaign: "Always-on — competitor", channel: "Search", status: "live", impressions: 486_000, clicks: 19_200, ctr: 0.0395, cpc: 2.86, spend: 54_912, conversions: 908, cpa: 60.5, roas: 2.2 },
  { campaign: "Lifecycle — winback", channel: "Email", status: "live", impressions: 312_000, clicks: 41_800, ctr: 0.134, cpc: 0.04, spend: 1_672, conversions: 1_204, cpa: 1.4, roas: 18.9 },
  { campaign: "Creator program", channel: "Social", status: "paused", impressions: 1_820_000, clicks: 47_300, ctr: 0.026, cpc: 0.91, spend: 43_043, conversions: 1_390, cpa: 31, roas: 3.8 },
  { campaign: "Podcast — Q1 flight", channel: "Audio", status: "paused", impressions: 940_000, clicks: 8_200, ctr: 0.0087, cpc: 3.4, spend: 27_880, conversions: 318, cpa: 87.7, roas: 1.6 },
  { campaign: "Marketplace listings", channel: "Partner", status: "live", impressions: 128_000, clicks: 6_400, ctr: 0.05, cpc: 1.15, spend: 7_360, conversions: 486, cpa: 15.1, roas: 6.7 },
  { campaign: "Docs — long tail", channel: "Search", status: "live", impressions: 74_000, clicks: 9_100, ctr: 0.123, cpc: 0.52, spend: 4_732, conversions: 402, cpa: 11.8, roas: 8.4 },
  { campaign: "Enterprise ABM", channel: "Display", status: "draft", impressions: 0, clicks: 0, ctr: 0, cpc: 0, spend: 0, conversions: 0, cpa: 0, roas: 0 },
  { campaign: "Conference — booth QR", channel: "Offline", status: "paused", impressions: 12_000, clicks: 1_900, ctr: 0.158, cpc: 0, spend: 18_000, conversions: 96, cpa: 187.5, roas: 0.9 },
  { campaign: "Newsletter sponsorships", channel: "Email", status: "live", impressions: 620_000, clicks: 14_400, ctr: 0.0232, cpc: 1.04, spend: 14_976, conversions: 508, cpa: 29.5, roas: 4.6 },
  { campaign: "App install — iOS", channel: "Social", status: "live", impressions: 3_410_000, clicks: 88_200, ctr: 0.0259, cpc: 0.47, spend: 41_454, conversions: 3_120, cpa: 13.3, roas: 5.2 },
]

/** One list of actions, rendered by whichever menu asked for it. */
const actions = [
  { label: "Open report" },
  { label: "Duplicate" },
  { label: "Archive", destructive: true },
]

function RowActions({ row }: { row: DataTableRow<CampaignRow> }) {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="ghost" size="icon" className="size-7">
          <MoreHorizontal />
          <span className="sr-only">Open menu for {row.original.campaign}</span>
        </Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent align="end">
        {actions.map((action) => (
          <DropdownMenuItem
            key={action.label}
            variant={action.destructive ? "destructive" : "default"}
          >
            {action.label}
          </DropdownMenuItem>
        ))}
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

const helper = createDataTableColumnHelper<CampaignRow>()

const number = (value: number, options?: Parameters<typeof formatNumber>[1]) => (
  <div className="text-right tabular-nums">{formatNumber(value, options)}</div>
)

const columns = helper.columns([
  helper.accessor("campaign", {
    enableHiding: false,
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Campaign" />
    ),
    cell: ({ row }) => (
      <span className="font-medium">{row.original.campaign}</span>
    ),
  }),
  helper.accessor("channel", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Channel" />
    ),
  }),
  helper.accessor("status", {
    header: "Status",
    cell: ({ row }) => (
      <Badge variant={row.original.status === "live" ? "secondary" : "outline"}>
        {row.original.status}
      </Badge>
    ),
  }),
  helper.accessor("impressions", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Impressions" align="right" />
    ),
    cell: ({ row }) => number(row.original.impressions, { compact: true }),
  }),
  helper.accessor("clicks", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Clicks" align="right" />
    ),
    cell: ({ row }) => number(row.original.clicks),
  }),
  helper.accessor("ctr", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="CTR" align="right" />
    ),
    cell: ({ row }) =>
      number(row.original.ctr, { format: "percent", maximumFractionDigits: 2 }),
  }),
  helper.accessor("cpc", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="CPC" align="right" />
    ),
    cell: ({ row }) => number(row.original.cpc, { format: "currency" }),
  }),
  helper.accessor("spend", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Spend" align="right" />
    ),
    cell: ({ row }) =>
      number(row.original.spend, { format: "currency", compact: true }),
  }),
  helper.accessor("conversions", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Conversions" align="right" />
    ),
    cell: ({ row }) => number(row.original.conversions),
  }),
  helper.accessor("cpa", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="CPA" align="right" />
    ),
    cell: ({ row }) => number(row.original.cpa, { format: "currency" }),
  }),
  helper.accessor("roas", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="ROAS" align="right" />
    ),
    cell: ({ row }) => (
      <div className="text-right tabular-nums">
        {row.original.roas.toFixed(1)}×
      </div>
    ),
  }),
  helper.display({
    id: "actions",
    // Pinned columns need a size: the sticky offsets are measured from it.
    size: 48,
    enableHiding: false,
    header: () => <span className="sr-only">Actions</span>,
    cell: ({ row }) => (
      <div className="flex justify-end">
        <RowActions row={row} />
      </div>
    ),
  }),
])

export default function DataTableStickyDemo() {
  return (
    <DataTable
      columns={columns}
      data={campaigns}
      searchKey="campaign"
      searchPlaceholder="Filter campaigns..."
      pinnedColumns={{ end: ["actions"] }}
      stickyHeader
      maxHeight={340}
      pageSize={0}
      showPagination={false}
      renderRow={(row, element) => (
        <ContextMenu>
          <ContextMenuTrigger asChild>{element}</ContextMenuTrigger>
          <ContextMenuContent className="w-40">
            {actions.map((action) => (
              <ContextMenuItem
                key={action.label}
                variant={action.destructive ? "destructive" : "default"}
              >
                {action.label}
              </ContextMenuItem>
            ))}
          </ContextMenuContent>
        </ContextMenu>
      )}
      className="w-full"
    />
  )
}
```

### Reorderable columns

reorderable puts a handle on each header. Drag one header onto another to move it, or focus a handle and use the arrow keys. Pass an array of column ids to limit which columns move.

```tsx
"use client"

import { Badge } from "@/components/ui/badge"
import { formatNumber } from "@/lib/format"
import {
  DataTable,
  DataTableColumnHeader,
  createDataTableColumnHelper,
} from "@/components/ui/data-table"

type RegionRow = {
  region: string
  tier: "enterprise" | "growth" | "starter"
  accounts: number
  seats: number
  arr: number
  churn: number
}

const regions: RegionRow[] = [
  { region: "North America", tier: "enterprise", accounts: 184, seats: 24_310, arr: 8_420_000, churn: 0.041 },
  { region: "EMEA", tier: "enterprise", accounts: 141, seats: 17_820, arr: 6_180_000, churn: 0.052 },
  { region: "APAC", tier: "growth", accounts: 96, seats: 8_940, arr: 2_740_000, churn: 0.068 },
  { region: "LATAM", tier: "growth", accounts: 62, seats: 4_120, arr: 1_180_000, churn: 0.081 },
  { region: "Nordics", tier: "starter", accounts: 48, seats: 2_060, arr: 486_000, churn: 0.094 },
  { region: "Benelux", tier: "starter", accounts: 39, seats: 1_540, arr: 361_000, churn: 0.077 },
  { region: "ANZ", tier: "growth", accounts: 34, seats: 2_880, arr: 812_000, churn: 0.058 },
]

const helper = createDataTableColumnHelper<RegionRow>()

const columns = helper.columns([
  helper.accessor("region", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Region" />
    ),
    cell: ({ row }) => <span className="font-medium">{row.original.region}</span>,
  }),
  helper.accessor("tier", {
    header: "Tier",
    cell: ({ row }) => (
      <Badge variant={row.original.tier === "enterprise" ? "secondary" : "outline"}>
        {row.original.tier}
      </Badge>
    ),
  }),
  helper.accessor("accounts", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Accounts" align="right" />
    ),
    cell: ({ row }) => (
      <div className="text-right tabular-nums">
        {formatNumber(row.original.accounts)}
      </div>
    ),
  }),
  helper.accessor("seats", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Seats" align="right" />
    ),
    cell: ({ row }) => (
      <div className="text-right tabular-nums">
        {formatNumber(row.original.seats)}
      </div>
    ),
  }),
  helper.accessor("arr", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="ARR" align="right" />
    ),
    cell: ({ row }) => (
      <div className="text-right tabular-nums">
        {formatNumber(row.original.arr, { format: "currency", compact: true })}
      </div>
    ),
  }),
  helper.accessor("churn", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Churn" align="right" />
    ),
    cell: ({ row }) => (
      <div className="text-right tabular-nums">
        {formatNumber(row.original.churn, {
          format: "percent",
          maximumFractionDigits: 1,
        })}
      </div>
    ),
  }),
])

export default function DataTableReorderDemo() {
  return (
    <DataTable
      columns={columns}
      data={regions}
      searchKey="region"
      searchPlaceholder="Filter regions..."
      reorderable
      pageSize={0}
      showPagination={false}
      className="w-full"
    />
  )
}
```

### Compact

density="compact" tightens the rows. With the toolbar and pagination off the table is only rows, and onRowClick with rowClassName makes them behave like a list.

```tsx
"use client"

import * as React from "react"

import { formatNumber } from "@/lib/format"
import { DeltaBadge } from "@/components/ui/delta-badge"
import {
  DataTable,
  createDataTableColumnHelper,
} from "@/components/ui/data-table"

type QueryRow = {
  query: string
  clicks: number
  position: number
  delta: number
}

const queries: QueryRow[] = [
  { query: "dashboard components", clicks: 4_120, position: 1.4, delta: 0.18 },
  { query: "shadcn kpi card", clicks: 3_480, position: 2.1, delta: 0.32 },
  { query: "react data table", clicks: 2_910, position: 4.8, delta: -0.06 },
  { query: "tanstack table example", clicks: 2_140, position: 3.2, delta: 0.09 },
  { query: "funnel chart react", clicks: 1_880, position: 5.6, delta: 0.21 },
  { query: "analytics ui kit", clicks: 1_240, position: 8.1, delta: -0.14 },
  { query: "sparkline component", clicks: 960, position: 6.4, delta: 0.04 },
  { query: "activity heatmap react", clicks: 720, position: 9.2, delta: 0.41 },
]

const helper = createDataTableColumnHelper<QueryRow>()

const columns = helper.columns([
  helper.accessor("query", {
    header: "Query",
    cell: ({ row }) => <span className="truncate">{row.original.query}</span>,
  }),
  helper.accessor("clicks", {
    header: () => <div className="text-right">Clicks</div>,
    cell: ({ row }) => (
      <div className="text-right tabular-nums">
        {formatNumber(row.original.clicks)}
      </div>
    ),
  }),
  helper.accessor("position", {
    header: () => <div className="text-right">Position</div>,
    cell: ({ row }) => (
      <div className="text-muted-foreground text-right tabular-nums">
        {row.original.position.toFixed(1)}
      </div>
    ),
  }),
  helper.accessor("delta", {
    header: () => <div className="text-right">Change</div>,
    cell: ({ row }) => (
      <div className="flex justify-end">
        <DeltaBadge delta={row.original.delta} variant="text" />
      </div>
    ),
  }),
])

export default function DataTableCompactDemo() {
  const [active, setActive] = React.useState<string | null>(null)

  return (
    <DataTable
      columns={columns}
      data={queries}
      density="compact"
      pageSize={0}
      showViewOptions={false}
      showPagination={false}
      onRowClick={(row) => setActive(row.original.query)}
      rowClassName={(row) =>
        row.original.query === active ? "bg-muted/60" : undefined
      }
      className="w-full"
    />
  )
}
```

### Composed

DataTable is a preset over parts that are all exported. Call useDataTable yourself and place the toolbar, search, view options, content, and pagination wherever the design puts them.

```tsx
"use client"

import { Badge } from "@/components/ui/badge"
import { Button } from "@/components/ui/button"
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card"
import {
  DataTableColumnHeader,
  DataTableContent,
  DataTablePagination,
  DataTableSearch,
  DataTableToolbar,
  DataTableViewOptions,
  createDataTableColumnHelper,
  useDataTable,
} from "@/components/ui/data-table"

type TicketRow = {
  subject: string
  requester: string
  status: "open" | "waiting" | "closed"
  priority: "urgent" | "high" | "normal"
  age: string
}

const tickets: TicketRow[] = [
  { subject: "Billing address will not save", requester: "R. Okafor", status: "open", priority: "high", age: "2h" },
  { subject: "SAML login loop after rotation", requester: "M. Lindqvist", status: "open", priority: "urgent", age: "4h" },
  { subject: "Export misses the last row", requester: "J. Alvarez", status: "waiting", priority: "normal", age: "1d" },
  { subject: "Webhook retries fire twice", requester: "P. Nakamura", status: "open", priority: "high", age: "1d" },
  { subject: "Invite email lands in spam", requester: "S. Dube", status: "closed", priority: "normal", age: "3d" },
  { subject: "Chart tooltip clipped on mobile", requester: "A. Fontaine", status: "waiting", priority: "normal", age: "3d" },
  { subject: "Seat count off by one", requester: "K. Brennan", status: "closed", priority: "high", age: "5d" },
  { subject: "API key scopes not enforced", requester: "T. Iqbal", status: "open", priority: "urgent", age: "6d" },
  { subject: "Timezone wrong in digest", requester: "L. Moreau", status: "closed", priority: "normal", age: "8d" },
]

const helper = createDataTableColumnHelper<TicketRow>()

const columns = helper.columns([
  helper.accessor("subject", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Subject" />
    ),
    cell: ({ row }) => (
      <span className="font-medium">{row.original.subject}</span>
    ),
  }),
  helper.accessor("requester", {
    header: "Requester",
    cell: ({ row }) => (
      <span className="text-muted-foreground">{row.original.requester}</span>
    ),
  }),
  helper.accessor("status", {
    header: "Status",
    cell: ({ row }) => (
      <Badge variant={row.original.status === "open" ? "secondary" : "outline"}>
        {row.original.status}
      </Badge>
    ),
  }),
  helper.accessor("priority", {
    header: "Priority",
    cell: ({ row }) => (
      <span
        className={
          row.original.priority === "urgent"
            ? "text-destructive"
            : "text-muted-foreground"
        }
      >
        {row.original.priority}
      </span>
    ),
  }),
  helper.accessor("age", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Age" align="right" />
    ),
    cell: ({ row }) => (
      <div className="text-muted-foreground text-right tabular-nums">
        {row.original.age}
      </div>
    ),
  }),
])

const statuses = ["open", "waiting", "closed"]

export default function DataTableComposedDemo() {
  // Own the instance, then lay the pieces out however the design calls for.
  const table = useDataTable({ columns, data: tickets, pageSize: 5 })

  const status = table.getColumn("status")
  const active = (status?.getFilterValue() as string) ?? ""

  return (
    <Card className="w-full gap-4">
      <CardHeader>
        <CardTitle>Support queue</CardTitle>
        <CardDescription>Unresolved tickets across all plans.</CardDescription>
        <CardAction>
          <DataTableViewOptions table={table} />
        </CardAction>
      </CardHeader>
      <CardContent className="flex flex-col gap-3">
        <DataTableToolbar>
          <DataTableSearch
            table={table}
            column="subject"
            placeholder="Filter tickets..."
          />
          <div className="ml-auto flex items-center gap-1">
            {statuses.map((value) => (
              <Button
                key={value}
                variant={active === value ? "secondary" : "ghost"}
                size="sm"
                className="h-8 capitalize"
                onClick={() =>
                  status?.setFilterValue(active === value ? "" : value)
                }
              >
                {value}
              </Button>
            ))}
          </div>
        </DataTableToolbar>
        <DataTableContent
          table={table}
          density="compact"
          emptyMessage="No tickets match that filter."
        />
      </CardContent>
      <CardFooter>
        <DataTablePagination
          table={table}
          pageSizeOptions={[5, 10, 25]}
          className="w-full"
        />
      </CardFooter>
    </Card>
  )
}
```

## Source

### components/ui/data-table.tsx

```tsx
"use client"

import * as React from "react"
import {
  columnFilteringFeature,
  columnOrderingFeature,
  columnPinningFeature,
  columnSizingFeature,
  columnVisibilityFeature,
  createColumnHelper,
  createFilteredRowModel,
  createPaginatedRowModel,
  createSortedRowModel,
  filterFn_includesString,
  flexRender,
  rowPaginationFeature,
  rowSelectionFeature,
  rowSortingFeature,
  sortFn_alphanumeric,
  sortFn_basic,
  sortFn_datetime,
  sortFn_text,
  tableFeatures,
  useTable,
  type Column,
  type ColumnDef,
  type ColumnFiltersState,
  type ColumnOrderState,
  type ColumnPinningState,
  type ColumnVisibilityState,
  type ReactTable,
  type Row,
  type RowData,
  type RowSelectionState,
  type SortingState,
} from "@tanstack/react-table"
import {
  ArrowDown,
  ArrowUp,
  ArrowUpDown,
  ChevronLeft,
  ChevronRight,
  ChevronsLeft,
  ChevronsRight,
  GripVertical,
  Settings2,
  X,
} from "lucide-react"

import { cn } from "@/lib/utils"
import { Button } from "@/components/ui/button"
import { Checkbox } from "@/components/ui/checkbox"
import {
  DropdownMenu,
  DropdownMenuCheckboxItem,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
import { Input } from "@/components/ui/input"
import { Skeleton } from "@/components/ui/skeleton"
import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@/components/ui/table"

/**
 * TanStack Table v9 is feature-gated: only what is registered here ships in
 * the bundle. Sorting, filtering, pagination, visibility, ordering, pinning,
 * and row selection cover the usual dashboard table.
 */
const dataTableFeatures = tableFeatures({
  columnFilteringFeature,
  columnOrderingFeature,
  columnPinningFeature,
  columnSizingFeature,
  columnVisibilityFeature,
  rowPaginationFeature,
  rowSelectionFeature,
  rowSortingFeature,
  filteredRowModel: createFilteredRowModel(),
  paginatedRowModel: createPaginatedRowModel(),
  sortedRowModel: createSortedRowModel(),
  filterFns: { includesString: filterFn_includesString },
  sortFns: {
    alphanumeric: sortFn_alphanumeric,
    basic: sortFn_basic,
    datetime: sortFn_datetime,
    text: sortFn_text,
  },
})

type DataTableFeatures = typeof dataTableFeatures

type DataTableColumnDef<TData extends RowData> = ColumnDef<
  DataTableFeatures,
  TData,
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  any
>

/** The table instance returned by `useDataTable`. */
type DataTableInstance<TData extends RowData> = ReactTable<
  DataTableFeatures,
  TData
>

type DataTableColumn<TData extends RowData> = Column<
  DataTableFeatures,
  TData,
  unknown
>

type DataTableRow<TData extends RowData> = Row<DataTableFeatures, TData>

/** Typed column helper bound to the data table's feature set. */
function createDataTableColumnHelper<TData extends RowData>() {
  return createColumnHelper<DataTableFeatures, TData>()
}

/** Row density presets. Only the cell padding changes. */
type DataTableDensity = "compact" | "default" | "relaxed"

const densityClasses: Record<DataTableDensity, string> = {
  compact:
    "[&_[data-slot=table-head]]:h-8 [&_[data-slot=table-cell]]:py-1 [&_[data-slot=table-cell]]:text-[0.8125rem]",
  default: "",
  relaxed: "[&_[data-slot=table-head]]:h-12 [&_[data-slot=table-cell]]:py-3.5",
}

/* -------------------------------------------------------------------------- */
/*                                    hook                                    */
/* -------------------------------------------------------------------------- */

export interface UseDataTableOptions<TData extends RowData> {
  columns: ReadonlyArray<DataTableColumnDef<TData>>
  data: TData[]
  /** Rows per page. Pass 0 to keep every row on a single page. */
  pageSize?: number
  initialSorting?: SortingState
  initialColumnVisibility?: ColumnVisibilityState
  /**
   * Column ids held against the leading and trailing edge. Read once, on
   * mount; use `table.setColumnPinning` to change it afterwards. Pinned
   * columns should declare a `size` so the sticky offsets line up.
   */
  pinnedColumns?: Partial<ColumnPinningState>
  /** Turn on checkbox selection, or decide per row. */
  enableRowSelection?: boolean | ((row: DataTableRow<TData>) => boolean)
  /** Stable row ids. Selection survives sorting and paging with this set. */
  getRowId?: (row: TData, index: number) => string
  onRowSelectionChange?: (selection: RowSelectionState) => void
}

/**
 * Wires the table state the components below read. Call it when you want to
 * lay the pieces out yourself; `DataTable` calls it for you.
 */
function useDataTable<TData extends RowData>({
  columns,
  data,
  pageSize = 10,
  initialSorting,
  initialColumnVisibility,
  pinnedColumns,
  enableRowSelection,
  getRowId,
  onRowSelectionChange,
}: UseDataTableOptions<TData>): DataTableInstance<TData> {
  const [sorting, setSorting] = React.useState<SortingState>(
    initialSorting ?? []
  )
  const [columnFilters, setColumnFilters] = React.useState<ColumnFiltersState>(
    []
  )
  const [columnVisibility, setColumnVisibility] =
    React.useState<ColumnVisibilityState>(initialColumnVisibility ?? {})
  const [columnOrder, setColumnOrder] = React.useState<ColumnOrderState>([])
  const [columnPinning, setColumnPinning] = React.useState<ColumnPinningState>(
    () => ({ start: pinnedColumns?.start ?? [], end: pinnedColumns?.end ?? [] })
  )
  const [rowSelection, setRowSelection] = React.useState<RowSelectionState>({})

  // Report the selection from an effect, not from inside the state updater:
  // the table can call the updater while it renders.
  const notify = React.useRef(onRowSelectionChange)
  const mounted = React.useRef(false)
  React.useEffect(() => {
    notify.current = onRowSelectionChange
  })
  React.useEffect(() => {
    if (!mounted.current) {
      mounted.current = true
      return
    }
    notify.current?.(rowSelection)
  }, [rowSelection])

  return useTable({
    features: dataTableFeatures,
    data,
    columns: columns as DataTableColumnDef<TData>[],
    initialState: {
      pagination: {
        pageIndex: 0,
        pageSize: pageSize > 0 ? pageSize : Number.MAX_SAFE_INTEGER,
      },
    },
    getRowId,
    enableRowSelection,
    // Shift-click extends the selection from the last row you touched.
    isRowRangeSelectionEvent: (event) =>
      Boolean((event as { shiftKey?: boolean }).shiftKey),
    onSortingChange: setSorting,
    onColumnFiltersChange: setColumnFilters,
    onColumnVisibilityChange: setColumnVisibility,
    onColumnOrderChange: setColumnOrder,
    onColumnPinningChange: setColumnPinning,
    onRowSelectionChange: setRowSelection,
    state: {
      sorting,
      columnFilters,
      columnVisibility,
      columnOrder,
      columnPinning,
      rowSelection,
    },
  })
}

/* -------------------------------------------------------------------------- */
/*                                   preset                                   */
/* -------------------------------------------------------------------------- */

export interface DataTableProps<TData extends RowData>
  extends Omit<React.ComponentProps<"div">, "onSelect">,
    UseDataTableOptions<TData> {
  /** Column id to filter with the search input. Omit to hide the input. */
  searchKey?: string
  searchPlaceholder?: string
  /** Extra toolbar content, rendered between the search input and view options. */
  toolbar?: React.ReactNode
  showViewOptions?: boolean
  showPagination?: boolean
  pageSizeOptions?: number[]
  emptyMessage?: React.ReactNode
  /** Swap the rows for a skeleton, e.g. on first load. */
  loading?: boolean
  /** Keep the rows but dim them, e.g. while a filter change is in flight. */
  pending?: boolean
  skeletonRows?: number
  stickyHeader?: boolean
  /** Caps the scroll area, e.g. 420 or "60vh". Pair it with stickyHeader. */
  maxHeight?: number | string
  /** Let columns be dragged into a new order. Pass ids to limit which ones. */
  reorderable?: boolean | string[]
  density?: DataTableDensity
  onRowClick?: (row: DataTableRow<TData>) => void
  rowClassName?: (row: DataTableRow<TData>) => string | undefined
  /** Anything else to put on a row, e.g. a data attribute or a handler. */
  rowProps?: (row: DataTableRow<TData>) => React.ComponentProps<"tr">
  /** Wrap the row element, e.g. in a context menu trigger. */
  renderRow?: (
    row: DataTableRow<TData>,
    element: React.ReactElement
  ) => React.ReactNode
  /** Actions shown in the bar that appears while rows are selected. */
  selectionActions?: React.ReactNode
}

/**
 * The batteries-included table: toolbar, rows, and pagination. Every part is
 * exported on its own, so reach for `useDataTable` and compose them by hand
 * when this shape is not the one you want.
 */
function DataTable<TData extends RowData>({
  columns,
  data,
  pageSize = 10,
  initialSorting,
  initialColumnVisibility,
  pinnedColumns,
  enableRowSelection,
  getRowId,
  onRowSelectionChange,
  searchKey,
  searchPlaceholder = "Filter...",
  toolbar,
  showViewOptions = true,
  showPagination = true,
  pageSizeOptions,
  emptyMessage = "No results.",
  loading = false,
  pending = false,
  skeletonRows,
  stickyHeader = false,
  maxHeight,
  reorderable = false,
  density = "default",
  onRowClick,
  rowClassName,
  rowProps,
  renderRow,
  selectionActions,
  className,
  ...props
}: DataTableProps<TData>) {
  const table = useDataTable({
    columns,
    data,
    pageSize,
    initialSorting,
    initialColumnVisibility,
    pinnedColumns,
    enableRowSelection,
    getRowId,
    onRowSelectionChange,
  })

  const hasToolbar = Boolean(searchKey || toolbar || showViewOptions)
  const selectedCount = table.getSelectedRowModel().rows.length

  return (
    <div
      data-slot="data-table"
      className={cn("flex flex-col gap-4", className)}
      {...props}
    >
      {hasToolbar ? (
        <DataTableToolbar>
          {searchKey ? (
            <DataTableSearch
              table={table}
              column={searchKey}
              placeholder={searchPlaceholder}
              disabled={loading}
            />
          ) : null}
          {toolbar}
          {showViewOptions ? (
            <DataTableViewOptions
              table={table}
              reorderable={reorderable}
              className="ml-auto"
              disabled={loading}
            />
          ) : null}
        </DataTableToolbar>
      ) : null}
      {selectedCount > 0 ? (
        <DataTableSelectionBar table={table}>
          {selectionActions}
        </DataTableSelectionBar>
      ) : null}
      <DataTableContent
        table={table}
        loading={loading}
        pending={pending}
        skeletonRows={skeletonRows ?? Math.min(pageSize || 10, 10)}
        stickyHeader={stickyHeader}
        maxHeight={maxHeight}
        reorderable={reorderable}
        density={density}
        emptyMessage={emptyMessage}
        onRowClick={onRowClick}
        rowClassName={rowClassName}
        rowProps={rowProps}
        renderRow={renderRow}
      />
      {showPagination ? (
        <DataTablePagination table={table} pageSizeOptions={pageSizeOptions} />
      ) : null}
    </div>
  )
}

/* -------------------------------------------------------------------------- */
/*                                   toolbar                                  */
/* -------------------------------------------------------------------------- */

/** The row above the table. Anything can go in it. */
function DataTableToolbar({
  className,
  ...props
}: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="data-table-toolbar"
      className={cn("flex flex-wrap items-center gap-2", className)}
      {...props}
    />
  )
}

interface DataTableSearchProps<TData extends RowData>
  extends Omit<React.ComponentProps<typeof Input>, "value" | "onChange"> {
  table: DataTableInstance<TData>
  /** Column id to filter. */
  column: string
}

/** An input bound to one column's filter. */
function DataTableSearch<TData extends RowData>({
  table,
  column,
  className,
  ...props
}: DataTableSearchProps<TData>) {
  const target = table.getColumn(column)
  if (!target) return null

  return (
    <Input
      data-slot="data-table-search"
      value={(target.getFilterValue() as string) ?? ""}
      onChange={(event) => target.setFilterValue(event.target.value)}
      className={cn("h-8 max-w-sm", className)}
      {...props}
    />
  )
}

interface DataTableViewOptionsProps<TData extends RowData>
  extends React.ComponentProps<typeof Button> {
  table: DataTableInstance<TData>
  /** Adds "move left / move right" items for the reorderable columns. */
  reorderable?: boolean | string[]
}

/** Column visibility, and column order when reordering is on. */
function DataTableViewOptions<TData extends RowData>({
  table,
  reorderable = false,
  className,
  ...props
}: DataTableViewOptionsProps<TData>) {
  const columns = table.getAllColumns().filter((column) => column.getCanHide())

  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button
          variant="outline"
          size="sm"
          className={cn("h-8", className)}
          {...props}
        >
          <Settings2 />
          View
        </Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent align="end" className="w-44">
        <DropdownMenuLabel>Toggle columns</DropdownMenuLabel>
        <DropdownMenuSeparator />
        {columns.map((column) => (
          <DropdownMenuCheckboxItem
            key={column.id}
            className="capitalize"
            checked={column.getIsVisible()}
            onCheckedChange={(value) => column.toggleVisibility(!!value)}
          >
            {column.id}
          </DropdownMenuCheckboxItem>
        ))}
        {reorderable ? (
          <>
            <DropdownMenuSeparator />
            <DropdownMenuLabel>Column order</DropdownMenuLabel>
            <DropdownMenuItem onSelect={() => table.resetColumnOrder()}>
              Reset to default
            </DropdownMenuItem>
          </>
        ) : null}
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

interface DataTableColumnHeaderProps<TData extends RowData, TValue>
  extends React.ComponentProps<"div"> {
  column: Column<DataTableFeatures, TData, TValue>
  title: string
  align?: "left" | "right"
}

function DataTableColumnHeader<TData extends RowData, TValue>({
  column,
  title,
  align = "left",
  className,
  ...props
}: DataTableColumnHeaderProps<TData, TValue>) {
  if (!column.getCanSort()) {
    return (
      <div
        className={cn(align === "right" && "text-right", className)}
        {...props}
      >
        {title}
      </div>
    )
  }

  const sorted = column.getIsSorted()
  const Icon =
    sorted === "asc" ? ArrowUp : sorted === "desc" ? ArrowDown : ArrowUpDown

  return (
    <div
      className={cn("flex", align === "right" && "justify-end", className)}
      {...props}
    >
      <Button
        variant="ghost"
        size="sm"
        className="data-[sorted=true]:text-foreground -ml-2 h-8 gap-1.5 px-2"
        data-sorted={sorted !== false}
        onClick={() => column.toggleSorting(sorted === "asc")}
      >
        {title}
        <Icon className="text-muted-foreground size-3.5" />
      </Button>
    </div>
  )
}

/* -------------------------------------------------------------------------- */
/*                                  selection                                 */
/* -------------------------------------------------------------------------- */

/**
 * A checkbox column. Put it first in your column list and give the table a
 * `getRowId` so the selection survives sorting and paging.
 */
function createSelectionColumn<TData extends RowData>(
  overrides?: Partial<DataTableColumnDef<TData>>
): DataTableColumnDef<TData> {
  return {
    id: "select",
    size: 36,
    enableSorting: false,
    enableHiding: false,
    header: ({ table }) => (
      <Checkbox
        checked={
          table.getIsAllPageRowsSelected()
            ? true
            : table.getIsSomePageRowsSelected()
              ? "indeterminate"
              : false
        }
        onCheckedChange={(value) => table.toggleAllPageRowsSelected(!!value)}
        aria-label="Select all rows on this page"
      />
    ),
    cell: ({ row }) => (
      <Checkbox
        checked={row.getIsSelected()}
        disabled={!row.getCanSelect()}
        // The handler wants the checkbox's next value and the shift key, which
        // is what turns a click into a range selection.
        onClick={(event) =>
          row.getToggleSelectedHandler()({
            target: { checked: !row.getIsSelected() },
            shiftKey: event.shiftKey,
          })
        }
        aria-label="Select row"
      />
    ),
    ...overrides,
  } as DataTableColumnDef<TData>
}

interface DataTableSelectionBarProps<TData extends RowData>
  extends React.ComponentProps<"div"> {
  table: DataTableInstance<TData>
}

/** The bar that appears once rows are selected. Children are the actions. */
function DataTableSelectionBar<TData extends RowData>({
  table,
  children,
  className,
  ...props
}: DataTableSelectionBarProps<TData>) {
  const count = table.getSelectedRowModel().rows.length

  return (
    <div
      data-slot="data-table-selection-bar"
      className={cn(
        "bg-muted/50 flex flex-wrap items-center gap-2 rounded-md border px-3 py-2",
        className
      )}
      {...props}
    >
      <span className="text-sm tabular-nums">
        {count} {count === 1 ? "row" : "rows"} selected
      </span>
      <div className="ml-auto flex items-center gap-2">
        {children}
        <Button
          variant="ghost"
          size="sm"
          className="h-8"
          onClick={() => table.resetRowSelection()}
        >
          <X />
          Clear
        </Button>
      </div>
    </div>
  )
}

/* -------------------------------------------------------------------------- */
/*                                   content                                  */
/* -------------------------------------------------------------------------- */

/** Moves `columnId` to the slot `targetId` currently occupies. */
function moveColumn<TData extends RowData>(
  table: DataTableInstance<TData>,
  columnId: string,
  targetId: string
) {
  const order = table.getAllLeafColumns().map((column) => column.id)
  const from = order.indexOf(columnId)
  const to = order.indexOf(targetId)
  if (from < 0 || to < 0 || from === to) return
  const next = order.slice()
  next.splice(from, 1)
  next.splice(to, 0, columnId)
  table.setColumnOrder(next)
}

/** Nudges `columnId` one slot left (-1) or right (1). */
function shiftColumn<TData extends RowData>(
  table: DataTableInstance<TData>,
  columnId: string,
  delta: number
) {
  const order = table.getAllLeafColumns().map((column) => column.id)
  const from = order.indexOf(columnId)
  const to = from + delta
  if (from < 0 || to < 0 || to >= order.length) return
  const next = order.slice()
  next.splice(from, 1)
  next.splice(to, 0, columnId)
  table.setColumnOrder(next)
}

/**
 * Sticky offsets and hairlines for a pinned cell. The feature computes the
 * regions; the renderer owns the CSS.
 */
function getPinnedStyle<TData extends RowData>(
  column: DataTableColumn<TData>,
  { stickyHeader = false }: { stickyHeader?: boolean } = {}
): React.CSSProperties | undefined {
  const pinned = column.getIsPinned()
  const shadows: string[] = []
  if (stickyHeader) shadows.push("inset 0 -1px 0 0 var(--border)")
  if (pinned === "start" && column.getIsLastColumn("start")) {
    shadows.push("inset -1px 0 0 0 var(--border)")
  }
  if (pinned === "end" && column.getIsFirstColumn("end")) {
    shadows.push("inset 1px 0 0 0 var(--border)")
  }
  if (!pinned && !shadows.length) return undefined

  // Auto table layout treats width as a suggestion, so pin all three: the
  // sticky offsets are computed from `size` and have to match what renders.
  const size = pinned ? column.getSize() : undefined

  return {
    insetInlineStart:
      pinned === "start" ? `${column.getStart("start")}px` : undefined,
    insetInlineEnd: pinned === "end" ? `${column.getAfter("end")}px` : undefined,
    width: size,
    minWidth: size,
    maxWidth: size,
    boxShadow: shadows.length ? shadows.join(", ") : undefined,
  }
}

/** Grip on a reorderable header. Drag it, or focus it and press an arrow. */
function DataTableDragHandle<TData extends RowData>({
  table,
  column,
}: {
  table: DataTableInstance<TData>
  column: DataTableColumn<TData>
}) {
  return (
    <button
      type="button"
      aria-label={`Reorder ${column.id} column`}
      className="text-muted-foreground/50 hover:text-foreground focus-visible:ring-ring/50 -ml-1 rounded-sm outline-none focus-visible:ring-[3px]"
      onKeyDown={(event) => {
        if (event.key !== "ArrowLeft" && event.key !== "ArrowRight") return
        event.preventDefault()
        shiftColumn(table, column.id, event.key === "ArrowLeft" ? -1 : 1)
      }}
    >
      <GripVertical className="size-3.5" />
    </button>
  )
}

const skeletonWidths = [72, 44, 58, 36, 64, 48, 52]

export interface DataTableContentProps<TData extends RowData>
  extends React.ComponentProps<"div"> {
  table: DataTableInstance<TData>
  loading?: boolean
  pending?: boolean
  skeletonRows?: number
  stickyHeader?: boolean
  maxHeight?: number | string
  reorderable?: boolean | string[]
  density?: DataTableDensity
  emptyMessage?: React.ReactNode
  onRowClick?: (row: DataTableRow<TData>) => void
  rowClassName?: (row: DataTableRow<TData>) => string | undefined
  /**
   * Anything else to put on a row: a handler, a data attribute, a title.
   * Merged after the built-in props, so it wins.
   */
  rowProps?: (row: DataTableRow<TData>) => React.ComponentProps<"tr">
  /**
   * Wrap the row element, e.g. in a context menu trigger or a link. Render
   * the element you are handed somewhere inside what you return.
   */
  renderRow?: (
    row: DataTableRow<TData>,
    element: React.ReactElement
  ) => React.ReactNode
}

/** The bordered table itself: header, rows, and their loading states. */
function DataTableContent<TData extends RowData>({
  table,
  loading = false,
  pending = false,
  skeletonRows = 8,
  stickyHeader = false,
  maxHeight,
  reorderable = false,
  density = "default",
  emptyMessage = "No results.",
  onRowClick,
  rowClassName,
  rowProps,
  renderRow,
  className,
  style,
  ...props
}: DataTableContentProps<TData>) {
  const [dragging, setDragging] = React.useState<string | null>(null)
  const [dropTarget, setDropTarget] = React.useState<string | null>(null)

  const { start, end } = table.state.columnPinning
  const hasPinned = start.length > 0 || end.length > 0
  const visibleColumns = table.getVisibleLeafColumns()
  const rows = table.getRowModel().rows

  const canReorder = (column: DataTableColumn<TData>) => {
    if (!reorderable || column.getIsPinned()) return false
    return Array.isArray(reorderable)
      ? reorderable.includes(column.id)
      : column.getCanHide()
  }

  /** Native drag and drop, so no drag library is pulled in for this. */
  const dragProps = (columnId: string): React.ComponentProps<"th"> => ({
    draggable: true,
    onDragStart: (event) => {
      setDragging(columnId)
      event.dataTransfer.effectAllowed = "move"
      event.dataTransfer.setData("text/plain", columnId)
    },
    onDragOver: (event) => {
      if (!dragging || dragging === columnId) return
      event.preventDefault()
      event.dataTransfer.dropEffect = "move"
      setDropTarget(columnId)
    },
    onDragLeave: () =>
      setDropTarget((current) => (current === columnId ? null : current)),
    onDrop: (event) => {
      event.preventDefault()
      if (dragging) moveColumn(table, dragging, columnId)
      setDragging(null)
      setDropTarget(null)
    },
    onDragEnd: () => {
      setDragging(null)
      setDropTarget(null)
    },
  })

  // Pinned cells are painted opaque so rows scroll under them, which would
  // otherwise hide the row's own hover and selected colours. Move both onto
  // the cells so pinned and unpinned columns stay in step. They have to stay
  // opaque too: a translucent hover on a pinned cell lets the columns passing
  // underneath show through, so the row hover is `bg-muted/50` pre-mixed over
  // the background rather than blended with whatever is behind the cell.
  const rowClasses = cn(
    "group/row",
    hasPinned && "hover:bg-transparent data-[state=selected]:bg-transparent"
  )
  const cellClasses = cn(
    hasPinned && [
      "group-hover/row:bg-[color-mix(in_oklab,var(--muted)_50%,var(--background))]",
      "group-data-[state=selected]/row:bg-muted",
    ]
  )

  return (
    <div
      data-slot="data-table-content"
      aria-busy={loading || pending || undefined}
      className={cn(
        "relative overflow-hidden rounded-md border",
        maxHeight !== undefined &&
          "[&>[data-slot=table-container]]:max-h-[var(--data-table-max-height)]",
        densityClasses[density],
        className
      )}
      style={
        maxHeight !== undefined
          ? ({
              ...style,
              "--data-table-max-height":
                typeof maxHeight === "number" ? `${maxHeight}px` : maxHeight,
            } as React.CSSProperties)
          : style
      }
      {...props}
    >
      {pending ? (
        <div
          aria-hidden
          className="bg-primary/60 absolute inset-x-0 top-0 z-40 h-0.5 animate-pulse"
        />
      ) : null}
      <Table>
        <TableHeader className={cn(stickyHeader && "[&_tr]:border-b-0")}>
          {table.getHeaderGroups().map((headerGroup) => (
            <TableRow
              key={headerGroup.id}
              className={cn(rowClasses, "hover:bg-transparent")}
            >
              {headerGroup.headers.map((header) => {
                const column = header.column as DataTableColumn<TData>
                const pinned = column.getIsPinned()
                const draggable = canReorder(column)

                return (
                  <TableHead
                    key={header.id}
                    colSpan={header.colSpan}
                    data-pinned={pinned || undefined}
                    data-dragging={dragging === column.id || undefined}
                    data-drop-target={dropTarget === column.id || undefined}
                    {...(draggable ? dragProps(column.id) : null)}
                    className={cn(
                      (stickyHeader || pinned) && "bg-background",
                      stickyHeader && "sticky top-0 z-20",
                      pinned && "sticky z-20 overflow-hidden",
                      pinned && stickyHeader && "z-30",
                      draggable && "cursor-grab data-[dragging]:opacity-40",
                      "data-[drop-target]:bg-muted"
                    )}
                    style={getPinnedStyle(column, { stickyHeader })}
                  >
                    {header.isPlaceholder ? null : draggable ? (
                      <div className="flex items-center gap-1">
                        <DataTableDragHandle table={table} column={column} />
                        {flexRender(
                          column.columnDef.header,
                          header.getContext()
                        )}
                      </div>
                    ) : (
                      flexRender(column.columnDef.header, header.getContext())
                    )}
                  </TableHead>
                )
              })}
            </TableRow>
          ))}
        </TableHeader>
        <TableBody
          className={cn(
            pending && "pointer-events-none opacity-50",
            "transition-opacity"
          )}
        >
          {loading ? (
            <DataTableSkeletonRows
              columns={visibleColumns.length}
              rows={skeletonRows}
            />
          ) : rows.length ? (
            rows.map((row) => {
              const extra = rowProps?.(row)
              const element = (
                <TableRow
                  data-state={row.getIsSelected() ? "selected" : undefined}
                  onClick={onRowClick ? () => onRowClick(row) : undefined}
                  {...extra}
                  className={cn(
                    rowClasses,
                    onRowClick && "cursor-pointer",
                    rowClassName?.(row),
                    extra?.className
                  )}
                >
                  {row.getVisibleCells().map((cell) => {
                    const column = cell.column as DataTableColumn<TData>
                    const pinned = column.getIsPinned()

                    return (
                      <TableCell
                        key={cell.id}
                        data-pinned={pinned || undefined}
                        className={cn(
                          cellClasses,
                          pinned && "bg-background sticky z-20 overflow-hidden"
                        )}
                        style={getPinnedStyle(column)}
                      >
                        {flexRender(column.columnDef.cell, cell.getContext())}
                      </TableCell>
                    )
                  })}
                </TableRow>
              )

              return (
                <React.Fragment key={row.id}>
                  {renderRow ? renderRow(row, element) : element}
                </React.Fragment>
              )
            })
          ) : (
            <TableRow className="hover:bg-transparent">
              <TableCell
                colSpan={visibleColumns.length}
                className="text-muted-foreground h-24 text-center"
              >
                {emptyMessage}
              </TableCell>
            </TableRow>
          )}
        </TableBody>
      </Table>
    </div>
  )
}

/* -------------------------------------------------------------------------- */
/*                                  skeletons                                 */
/* -------------------------------------------------------------------------- */

function DataTableSkeletonRows({
  columns,
  rows,
}: {
  columns: number
  rows: number
}) {
  return (
    <>
      {Array.from({ length: rows }).map((_, rowIndex) => (
        <TableRow key={rowIndex} className="hover:bg-transparent">
          {Array.from({ length: columns }).map((__, columnIndex) => (
            <TableCell key={columnIndex}>
              <Skeleton
                className="h-4"
                style={{
                  width: `${
                    skeletonWidths[
                      (rowIndex + columnIndex) % skeletonWidths.length
                    ]
                  }%`,
                }}
              />
            </TableCell>
          ))}
        </TableRow>
      ))}
    </>
  )
}

export interface DataTableSkeletonProps extends React.ComponentProps<"div"> {
  columns: number
  rows?: number
  showToolbar?: boolean
  showPagination?: boolean
}

/**
 * A standalone placeholder for when the columns are not known yet, e.g. a
 * Suspense fallback. Once you have a table instance, `loading` on
 * `DataTableContent` renders the same rows under the real header.
 */
function DataTableSkeleton({
  columns,
  rows = 8,
  showToolbar = true,
  showPagination = true,
  className,
  ...props
}: DataTableSkeletonProps) {
  return (
    <div
      data-slot="data-table-skeleton"
      aria-busy
      className={cn("flex flex-col gap-4", className)}
      {...props}
    >
      {showToolbar ? (
        <div className="flex items-center gap-2">
          <Skeleton className="h-8 w-full max-w-sm" />
          <Skeleton className="ml-auto h-8 w-20" />
        </div>
      ) : null}
      <div className="overflow-hidden rounded-md border">
        <Table>
          <TableHeader>
            <TableRow className="hover:bg-transparent">
              {Array.from({ length: columns }).map((_, index) => (
                <TableHead key={index}>
                  <Skeleton className="h-3.5 w-16" />
                </TableHead>
              ))}
            </TableRow>
          </TableHeader>
          <TableBody>
            <DataTableSkeletonRows columns={columns} rows={rows} />
          </TableBody>
        </Table>
      </div>
      {showPagination ? (
        <div className="flex items-center justify-between gap-4">
          <Skeleton className="h-5 w-28" />
          <Skeleton className="h-8 w-48" />
        </div>
      ) : null}
    </div>
  )
}

/* -------------------------------------------------------------------------- */
/*                                 pagination                                 */
/* -------------------------------------------------------------------------- */

interface DataTablePaginationProps<TData extends RowData>
  extends React.ComponentProps<"div"> {
  table: DataTableInstance<TData>
  /** Adds a rows-per-page menu. */
  pageSizeOptions?: number[]
}

function DataTablePagination<TData extends RowData>({
  table,
  pageSizeOptions,
  className,
  ...props
}: DataTablePaginationProps<TData>) {
  const { pageIndex, pageSize } = table.state.pagination
  const total = table.getFilteredRowModel().rows.length
  const from = total === 0 ? 0 : pageIndex * pageSize + 1
  const to = Math.min((pageIndex + 1) * pageSize, total)

  return (
    <div
      data-slot="data-table-pagination"
      className={cn("flex flex-wrap items-center justify-between gap-4", className)}
      {...props}
    >
      <div className="flex items-center gap-3">
        <p className="text-muted-foreground text-sm tabular-nums">
          {from}–{to} of {total}
        </p>
        {pageSizeOptions?.length ? (
          <DropdownMenu>
            <DropdownMenuTrigger asChild>
              <Button variant="ghost" size="sm" className="h-8 tabular-nums">
                {pageSize} per page
              </Button>
            </DropdownMenuTrigger>
            <DropdownMenuContent align="start" className="w-36">
              {pageSizeOptions.map((option) => (
                <DropdownMenuCheckboxItem
                  key={option}
                  checked={option === pageSize}
                  onCheckedChange={() => table.setPageSize(option)}
                  className="tabular-nums"
                >
                  {option} per page
                </DropdownMenuCheckboxItem>
              ))}
            </DropdownMenuContent>
          </DropdownMenu>
        ) : null}
      </div>
      <div className="flex items-center gap-1">
        <Button
          variant="outline"
          size="icon"
          className="size-8"
          onClick={() => table.firstPage()}
          disabled={!table.getCanPreviousPage()}
          aria-label="First page"
        >
          <ChevronsLeft />
        </Button>
        <Button
          variant="outline"
          size="icon"
          className="size-8"
          onClick={() => table.previousPage()}
          disabled={!table.getCanPreviousPage()}
          aria-label="Previous page"
        >
          <ChevronLeft />
        </Button>
        <span className="text-muted-foreground px-2 text-sm tabular-nums">
          Page {pageIndex + 1} of {Math.max(table.getPageCount(), 1)}
        </span>
        <Button
          variant="outline"
          size="icon"
          className="size-8"
          onClick={() => table.nextPage()}
          disabled={!table.getCanNextPage()}
          aria-label="Next page"
        >
          <ChevronRight />
        </Button>
        <Button
          variant="outline"
          size="icon"
          className="size-8"
          onClick={() => table.lastPage()}
          disabled={!table.getCanNextPage()}
          aria-label="Last page"
        >
          <ChevronsRight />
        </Button>
      </div>
    </div>
  )
}

export {
  DataTable,
  DataTableColumnHeader,
  DataTableContent,
  DataTablePagination,
  DataTableSearch,
  DataTableSelectionBar,
  DataTableSkeleton,
  DataTableToolbar,
  DataTableViewOptions,
  createDataTableColumnHelper,
  createSelectionColumn,
  dataTableFeatures,
  moveColumn,
  shiftColumn,
  useDataTable,
  type DataTableColumnDef,
  type DataTableDensity,
  type DataTableFeatures,
  type DataTableInstance,
  type DataTableRow,
}
```

# Delta Badge

A signed percentage change with a trend icon, colored by whether the change is good.

A small badge showing a signed percentage change with a trend icon, colored by whether the change is good. Every card in this registry uses it, and it can be inverted for metrics where a decrease is the good direction.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/delta-badge.json
```

npm dependencies: `lucide-react`.

## Usage

```tsx
import { DeltaBadge } from "@/components/ui/delta-badge"

<DeltaBadge delta={0.124} />
<DeltaBadge delta={0.08} invert />
<DeltaBadge delta={-0.032} variant="soft" />
```

## Examples

### Default

```tsx
import { DeltaBadge } from "@/components/ui/delta-badge"

export default function DeltaBadgeDemo() {
  return (
    <div className="flex flex-col gap-4">
      <div className="flex items-center gap-3">
        <DeltaBadge delta={0.124} />
        <DeltaBadge delta={-0.032} />
        <DeltaBadge delta={0} />
        <DeltaBadge delta={0.08} invert />
      </div>
      <div className="flex items-center gap-3">
        <DeltaBadge delta={0.124} variant="soft" />
        <DeltaBadge delta={-0.032} variant="soft" />
        <DeltaBadge delta={0} variant="soft" />
      </div>
      <div className="flex items-center gap-3">
        <DeltaBadge delta={0.124} variant="text" />
        <DeltaBadge delta={-0.032} variant="text" showIcon={false} />
      </div>
    </div>
  )
}
```

## Source

### components/ui/delta-badge.tsx

```tsx
import * as React from "react"
import { Minus, TrendingDown, TrendingUp } from "lucide-react"

import { cn } from "@/lib/utils"
import { formatDelta } from "@/lib/format"

export type DeltaDirection = "up" | "down" | "flat"

export function getDeltaDirection(delta: number | undefined): DeltaDirection {
  if (delta === undefined || delta === 0 || !Number.isFinite(delta)) return "flat"
  return delta > 0 ? "up" : "down"
}

const directionIcon: Record<DeltaDirection, React.ElementType> = {
  up: TrendingUp,
  down: TrendingDown,
  flat: Minus,
}

export interface DeltaBadgeProps extends React.ComponentProps<"span"> {
  /** Fractional change, e.g. 0.124 for +12.4%. */
  delta: number
  /** Treat a decrease as good and an increase as bad (churn, latency, errors). */
  invert?: boolean
  variant?: "outline" | "soft" | "text"
  showIcon?: boolean
}

function DeltaBadge({
  delta,
  invert = false,
  variant = "outline",
  showIcon = true,
  className,
  children,
  ...props
}: DeltaBadgeProps) {
  const direction = getDeltaDirection(delta)
  const positive = direction === "flat" ? null : (direction === "up") !== invert
  const Icon = directionIcon[direction]

  return (
    <span
      data-slot="delta-badge"
      data-direction={direction}
      data-positive={positive}
      className={cn(
        "inline-flex items-center gap-1 text-xs font-medium tabular-nums",
        variant === "outline" && "rounded-md border px-1.5 py-0.5",
        variant === "soft" && "rounded-md px-1.5 py-0.5",
        variant === "soft" && positive === true && "bg-emerald-500/10",
        variant === "soft" && positive === false && "bg-red-500/10",
        variant === "soft" && positive === null && "bg-muted",
        positive === true && "text-emerald-600 dark:text-emerald-400",
        positive === false && "text-red-600 dark:text-red-400",
        positive === null && "text-muted-foreground",
        className
      )}
      {...props}
    >
      {showIcon ? <Icon className="size-3" aria-hidden="true" /> : null}
      {children ?? formatDelta(delta)}
    </span>
  )
}

export { DeltaBadge }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Distribution Bar

A single stacked bar showing how a total splits across categories.

A single stacked bar that shows how a total splits across categories, with a legend. Use it for storage by type, revenue by plan, or traffic by source when a pie chart would take too much room.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/distribution-bar.json
```

## Usage

```tsx
import { DistributionBar } from "@/components/ui/distribution-bar"

<DistributionBar
  segments={[
    { name: "Desktop", value: 61400 },
    { name: "Mobile", value: 34200 },
    { name: "Tablet", value: 4100 },
  ]}
/>
```

## Examples

### Default

```tsx
import { DistributionBar } from "@/components/ui/distribution-bar"

const devices = [
  { name: "Desktop", value: 61_400 },
  { name: "Mobile", value: 34_200 },
  { name: "Tablet", value: 4_100 },
  { name: "Other", value: 640 },
]

export default function DistributionBarDemo() {
  return (
    <div className="w-full max-w-lg">
      <DistributionBar segments={devices} showValues />
    </div>
  )
}
```

## Source

### components/ui/distribution-bar.tsx

```tsx
import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber } from "@/lib/format"

export interface DistributionSegment {
  name: string
  value: number
  /** Any CSS color. Defaults to chart-1 through chart-5 in order. */
  color?: string
}

export interface DistributionBarProps extends React.ComponentProps<"div"> {
  segments: DistributionSegment[]
  valueFormatter?: (value: number) => string
  showLegend?: boolean
  /** Show absolute values in the legend in addition to the share. */
  showValues?: boolean
}

const defaultColors = [
  "var(--chart-1)",
  "var(--chart-2)",
  "var(--chart-3)",
  "var(--chart-4)",
  "var(--chart-5)",
]

function DistributionBar({
  segments,
  valueFormatter = (value) => formatNumber(value, { format: "compact" }),
  showLegend = true,
  showValues = false,
  className,
  ...props
}: DistributionBarProps) {
  const total = segments.reduce((sum, segment) => sum + segment.value, 0)
  const resolved = segments.map((segment, index) => ({
    ...segment,
    color: segment.color ?? defaultColors[index % defaultColors.length],
    share: total > 0 ? segment.value / total : 0,
  }))

  return (
    <div
      data-slot="distribution-bar"
      className={cn("flex flex-col gap-3", className)}
      {...props}
    >
      <div
        role="img"
        aria-label={resolved
          .map(
            (segment) =>
              `${segment.name} ${formatNumber(segment.share, { format: "percent" })}`
          )
          .join(", ")}
        className="flex h-2.5 w-full gap-0.5 overflow-hidden rounded-full"
      >
        {resolved.map((segment) =>
          segment.share > 0 ? (
            <div
              key={segment.name}
              className="h-full transition-[width] duration-300 first:rounded-l-full last:rounded-r-full"
              style={{
                width: `${segment.share * 100}%`,
                backgroundColor: segment.color,
              }}
            />
          ) : null
        )}
      </div>
      {showLegend ? (
        <ul className="flex flex-wrap gap-x-4 gap-y-1.5 text-sm">
          {resolved.map((segment) => (
            <li key={segment.name} className="flex items-center gap-2">
              <span
                aria-hidden="true"
                className="size-2.5 shrink-0 rounded-[2px]"
                style={{ backgroundColor: segment.color }}
              />
              <span className="text-muted-foreground">{segment.name}</span>
              <span className="font-medium tabular-nums">
                {formatNumber(segment.share, { format: "percent" })}
              </span>
              {showValues ? (
                <span className="text-muted-foreground tabular-nums">
                  ({valueFormatter(segment.value)})
                </span>
              ) : null}
            </li>
          ))}
        </ul>
      ) : null}
    </div>
  )
}

export { DistributionBar }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Donut Chart

A donut, pie, or half-donut with a center label, tooltip, and legend, on shadcn's chart primitives.

A donut, pie, or half-donut chart for shadcn/ui with a center label, tooltip, and legend, built on shadcn's chart primitives. The half-donut form doubles as a simple gauge.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/donut-chart.json
```

Also installs `chart` from shadcn/ui if missing.

npm dependencies: `recharts`.

## Usage

```tsx
import { DonutChart } from "@/components/ui/donut-chart"

<DonutChart
  data={[
    { name: "Chrome", value: 58400 },
    { name: "Safari", value: 21300 },
    { name: "Firefox", value: 8900 },
  ]}
  centerLabel="Visitors"
  showLegend
/>
```

## Examples

### Default

```tsx
import { DonutChart } from "@/components/ui/donut-chart"

const browsers = [
  { name: "Chrome", value: 58_400 },
  { name: "Safari", value: 21_300 },
  { name: "Firefox", value: 8_900 },
  { name: "Edge", value: 6_100 },
  { name: "Other", value: 2_400 },
]

export default function DonutChartDemo() {
  return (
    <div className="w-full max-w-xs">
      <DonutChart
        data={browsers}
        centerLabel="Visitors"
        showLegend
        className="max-h-72"
      />
    </div>
  )
}
```

### Half donut

Set sweep to 180 and startAngle to 180 for a gauge-like semicircle.

```tsx
"use client"

import { DonutChart } from "@/components/ui/donut-chart"
import { formatNumber } from "@/lib/format"

const sources = [
  { name: "Institutional", value: 4_200_000, color: "var(--chart-2)" },
  { name: "Retail", value: 2_100_000, color: "var(--chart-1)" },
  { name: "Treasury", value: 900_000, color: "var(--chart-4)" },
]

export default function DonutChartHalfDemo() {
  return (
    <div className="w-full max-w-sm">
      <DonutChart
        data={sources}
        startAngle={180}
        sweep={180}
        innerRadius={0.75}
        centerLabel="Capital inflows"
        valueFormatter={(v) => formatNumber(v, { format: "currency", maximumFractionDigits: 0 })}
        centerValue={formatNumber(7_200_000, { format: "compact" })}
        showLegend
        className="max-h-56"
      />
    </div>
  )
}
```

## Source

### components/ui/donut-chart.tsx

```tsx
"use client"

import * as React from "react"
import { Label, Pie, PieChart } from "recharts"

import { cn } from "@/lib/utils"
import { formatNumber } from "@/lib/format"
import {
  ChartContainer,
  ChartLegend,
  ChartLegendContent,
  ChartTooltip,
  ChartTooltipContent,
  type ChartConfig,
} from "@/components/ui/chart"

export interface DonutSlice {
  name: string
  value: number
  /** Any CSS color. Defaults to chart-1 through chart-5 in order. */
  color?: string
}

export interface DonutChartProps
  extends Omit<React.ComponentProps<typeof ChartContainer>, "config" | "children"> {
  data: DonutSlice[]
  /** Inner radius as a fraction of the outer radius. 0 draws a pie. */
  innerRadius?: number
  /** Label shown in the middle, under the value. */
  centerLabel?: React.ReactNode
  /** Value shown in the middle. Defaults to the total. */
  centerValue?: React.ReactNode
  valueFormatter?: (value: number) => string
  showLegend?: boolean
  showTooltip?: boolean
  /** Angle where the first slice starts, in degrees. */
  startAngle?: number
  /** Total sweep in degrees. 180 draws a half donut. */
  sweep?: number
  paddingAngle?: number
}

function DonutChart({
  data,
  innerRadius = 0.7,
  centerLabel,
  centerValue,
  valueFormatter = (value) => formatNumber(value, { format: "compact" }),
  showLegend = false,
  showTooltip = true,
  startAngle = 90,
  sweep = 360,
  paddingAngle = 2,
  className,
  ...props
}: DonutChartProps) {
  const total = data.reduce((sum, slice) => sum + slice.value, 0)
  const slices = data.map((slice, index) => ({
    ...slice,
    key: slice.name.toLowerCase().replace(/[^a-z0-9]+/g, "-"),
    fill: slice.color ?? `var(--chart-${(index % 5) + 1})`,
  }))
  const config = Object.fromEntries(
    slices.map((slice) => [slice.key, { label: slice.name, color: slice.fill }])
  ) satisfies ChartConfig
  const center = centerValue ?? valueFormatter(total)

  return (
    <ChartContainer
      data-slot="donut-chart"
      config={config}
      className={cn("mx-auto aspect-square w-full max-h-64", className)}
      {...props}
    >
      <PieChart>
        {showTooltip ? (
          <ChartTooltip
            cursor={false}
            content={
              <ChartTooltipContent
                hideLabel
                nameKey="key"
                formatter={(value, _name, item) => (
                  <div className="flex w-full items-center justify-between gap-4">
                    <span className="text-muted-foreground">{item.payload.name}</span>
                    <span className="font-mono font-medium tabular-nums">
                      {valueFormatter(Number(value))}
                    </span>
                  </div>
                )}
              />
            }
          />
        ) : null}
        <Pie
          data={slices}
          dataKey="value"
          nameKey="key"
          innerRadius={`${innerRadius * 100}%`}
          outerRadius="100%"
          startAngle={startAngle}
          endAngle={startAngle - sweep}
          paddingAngle={paddingAngle}
          strokeWidth={0}
          cornerRadius={2}
          isAnimationActive={false}
        >
          {innerRadius > 0 && (center || centerLabel) ? (
            <Label
              content={({ viewBox }) => {
                if (!viewBox || !("cx" in viewBox) || !("cy" in viewBox)) return null
                const cx = Number(viewBox.cx)
                const cy = Number(viewBox.cy) + (sweep < 360 ? 12 : 0)
                return (
                  <text x={cx} y={cy} textAnchor="middle" dominantBaseline="middle">
                    <tspan
                      x={cx}
                      y={cy}
                      className="fill-foreground text-2xl font-semibold tabular-nums"
                    >
                      {center}
                    </tspan>
                    {centerLabel ? (
                      <tspan
                        x={cx}
                        y={cy + 22}
                        className="fill-muted-foreground text-xs"
                      >
                        {centerLabel}
                      </tspan>
                    ) : null}
                  </text>
                )
              }}
            />
          ) : null}
        </Pie>
        {showLegend ? (
          <ChartLegend
            content={
              <ChartLegendContent nameKey="key" className="flex-wrap gap-x-4 gap-y-1" />
            }
          />
        ) : null}
      </PieChart>
    </ChartContainer>
  )
}

export { DonutChart }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Dot Plot

A distribution drawn as columns of stacked dots, with the peak columns at full strength.

A distribution drawn as columns of stacked dots, with the peak columns at full strength. It suits counts per day or per bucket where a bar chart would look too heavy.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/dot-plot.json
```

## Usage

```tsx
import { DotPlot } from "@/components/ui/dot-plot"

<DotPlot data={[1, 1, 2, 1, 2, 4, 6, 4, 2, 1, 2, 1, 1, 1]} color="var(--color-green-600)" />
<DotPlot data={[3, 5, 8, 12, 7, 4, 2]} labels={days} rows={6} />
<DotPlot data={[2, 3, 5, 4, 6, 3, 2]} emphasis={0} className="[--dot-size:0.875rem]" />
```

## Examples

### Default

```tsx
import { DotPlot } from "@/components/ui/dot-plot"

const days = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
const hourly = [1, 1, 2, 1, 2, 4, 6, 4, 2, 1, 2, 1, 1, 1]

export default function DotPlotDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-8">
      <DotPlot data={hourly} color="var(--color-green-600)" />
      <DotPlot data={[3, 5, 8, 12, 7, 4, 2]} labels={days} color="var(--color-blue-600)" />
      <DotPlot data={[2, 3, 5, 4, 6, 3, 2]} labels={days} rows={4} emphasis={0} color="var(--foreground)" className="[--dot-size:0.875rem]" />
    </div>
  )
}
```

## Source

### components/ui/dot-plot.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"

export interface DotPlotProps extends React.ComponentProps<"div"> {
  /** One value per column, in order. */
  data: number[]
  /** Optional label per column, shown in the tooltip and used for the accessible name. */
  labels?: string[]
  /** The value that fills a column. Defaults to the largest value in `data`. */
  max?: number
  /** Number of dots in a full column. */
  rows?: number
  /** Any CSS color. Defaults to chart-1. */
  color?: string
  /**
   * Columns at or above this fraction of `max` are drawn at full strength and the
   * rest are faded, so the peak stands out. Set to 0 to draw every column at full strength.
   */
  emphasis?: number
  /** Opacity of the faded columns. */
  fadedOpacity?: number
  /** Show a tooltip with the column's label and value while it is hovered. */
  showTooltip?: boolean
  /** Formats the value in the tooltip. Defaults to a plain grouped number. */
  valueFormatter?: (value: number) => string
  /** Index of the hovered column, to control it from outside. */
  activeIndex?: number | null
  /** Called when the hovered column changes, with null when the pointer leaves. */
  onActiveIndexChange?: (index: number | null) => void
}

const defaultFormatter = (value: number) => value.toLocaleString("en-US")

/**
 * A distribution drawn as columns of stacked dots, with the peak columns at full strength.
 * Hovering a column lights it up, fades the others, and shows its value.
 */
function DotPlot({
  data,
  labels,
  max,
  rows = 6,
  color = "var(--chart-1)",
  emphasis = 0.5,
  fadedOpacity = 0.35,
  showTooltip = true,
  valueFormatter = defaultFormatter,
  activeIndex,
  onActiveIndexChange,
  className,
  ...props
}: DotPlotProps) {
  const [internal, setInternal] = React.useState<number | null>(null)
  const active = activeIndex === undefined ? internal : activeIndex
  const setActive = (index: number | null) => {
    setInternal(index)
    onActiveIndexChange?.(index)
  }

  const top = max ?? Math.max(0, ...data)
  const peak = data.indexOf(Math.max(...data))
  const peakLabel = labels?.[peak]

  return (
    <div
      data-slot="dot-plot"
      role="img"
      aria-label={
        peakLabel !== undefined
          ? `Distribution across ${data.length} points, peaking at ${peakLabel}`
          : `Distribution across ${data.length} points`
      }
      onPointerLeave={() => setActive(null)}
      className={cn(
        // Dot size and gap are variables so they can be tuned from className, e.g. "[--dot-size:0.75rem]".
        "flex w-full justify-center [--dot-gap:0.25rem] [--dot-size:0.625rem]",
        className
      )}
      {...props}
    >
      {data.map((value, index) => {
        const fraction = Math.min(1, Math.max(0, value / (top || 1)))
        // Any non-zero value shows at least one dot so small values still register.
        const count = fraction === 0 ? 0 : Math.max(1, Math.round(fraction * rows))
        const strong = emphasis <= 0 || fraction >= emphasis
        // While a column is hovered it alone is lit; otherwise the emphasized columns are.
        const lit = active === null ? strong : active === index
        const label = labels?.[index]
        return (
          <div
            key={index}
            data-slot="dot-plot-column"
            data-emphasis={strong}
            data-active={active === index}
            onPointerEnter={() => setActive(index)}
            // Columns stretch to the full height and carry the gap as padding, so the hover target has no dead zones.
            // They share the width equally and cap at the dot size, so dots shrink in narrow cards instead of overflowing.
            className="relative flex min-w-0 flex-1 cursor-default flex-col-reverse justify-start gap-(--dot-gap) px-[calc(var(--dot-gap)/2)] max-w-[calc(var(--dot-size)+var(--dot-gap))]"
          >
            {Array.from({ length: count }, (_, dot) => (
              <span
                key={dot}
                className="aspect-square w-full rounded-full transition-opacity"
                style={{ backgroundColor: color, opacity: lit ? 1 : fadedOpacity }}
              />
            ))}
            {showTooltip && active === index ? (
              <span
                role="tooltip"
                className="bg-popover text-popover-foreground pointer-events-none absolute bottom-full left-1/2 z-10 mb-1.5 flex -translate-x-1/2 items-baseline gap-1.5 rounded-md border px-2 py-1 text-xs whitespace-nowrap shadow-md"
              >
                {label !== undefined ? (
                  <span className="text-muted-foreground">{label}</span>
                ) : null}
                <span className="font-medium tabular-nums">{valueFormatter(value)}</span>
              </span>
            ) : null}
          </div>
        )
      })}
    </div>
  )
}

export { DotPlot }
```

# Funnel Chart

Step-by-step conversion, as stacked bars with drop-off or as a flow of tapering stages with a tile per step.

A conversion funnel for shadcn/ui: each step as a bar, the drop-off between steps, and overall conversion at the end. It is plain HTML rather than SVG, which keeps it easy to restyle and accessible by default.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/funnel-chart.json
```

## Usage

```tsx
import { FunnelChart } from "@/components/ui/funnel-chart"

<FunnelChart
  steps={[
    { name: "Visited pricing", value: 12480 },
    { name: "Started signup", value: 4920 },
    { name: "Upgraded to Pro", value: 412 },
  ]}
/>

<FunnelChart
  variant="flow"
  steps={[
    { name: "Link opened", value: 197, color: "var(--color-lime-400)" },
    { name: "Started", value: 110, color: "var(--color-blue-500)" },
    { name: "Converted", value: 38, color: "var(--color-pink-500)" },
  ]}
/>
```

## Examples

### Default

```tsx
import { FunnelChart } from "@/components/ui/funnel-chart"

const steps = [
  { name: "Visited pricing", value: 12_480 },
  { name: "Started signup", value: 4_920 },
  { name: "Verified email", value: 3_610 },
  { name: "Created workspace", value: 2_140 },
  { name: "Upgraded to Pro", value: 412 },
]

export default function FunnelChartDemo() {
  return (
    <div className="w-full max-w-lg">
      <FunnelChart steps={steps} />
    </div>
  )
}
```

### Flow

Set variant to "flow" to run the steps left to right, each sized to its share of the first and tapering into the next. Give each step a color, or none for the chart palette. Hover a stage to focus it.

```tsx
import { FunnelChart } from "@/components/ui/funnel-chart"

const steps = [
  { name: "Link opened", value: 197, color: "var(--color-lime-400)" },
  { name: "Started", value: 110, color: "var(--color-blue-500)" },
  { name: "Completed", value: 77, color: "var(--color-violet-500)" },
  { name: "Converted", value: 38, color: "var(--color-pink-500)" },
]

export default function FunnelChartFlowDemo() {
  return (
    <div className="w-full max-w-lg">
      <FunnelChart variant="flow" steps={steps} />
    </div>
  )
}
```

### Sharp and single color

shape="sharp" draws straight trapezoids. A single color fades from stage to stage, so pass the foreground for a one-ink funnel. height sets the stage height in pixels.

```tsx
import { FunnelChart } from "@/components/ui/funnel-chart"

const steps = [
  { name: "Applied", value: 1240 },
  { name: "Screened", value: 420 },
  { name: "Phone", value: 96 },
  { name: "Offer", value: 18 },
  { name: "Hired", value: 11 },
]

export default function FunnelChartSharpDemo() {
  return (
    <div className="w-full max-w-lg">
      <FunnelChart
        variant="flow"
        shape="sharp"
        color="var(--foreground)"
        steps={steps}
        height={128}
      />
    </div>
  )
}
```

## Source

### components/ui/funnel-chart.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber } from "@/lib/format"

export interface FunnelStep {
  name: string
  value: number
  /** Any CSS color for this step in the flow variant. Defaults to chart-1 through chart-5 in order. */
  color?: string
}

export interface FunnelChartProps extends React.ComponentProps<"div"> {
  steps: FunnelStep[]
  valueFormatter?: (value: number) => string
  /**
   * Any CSS color. "bars" fades it step by step. "flow" paints every stage in
   * it, in place of the per-stage palette.
   */
  color?: string
  /** Show the drop-off between consecutive steps. Bars only. */
  showDropoff?: boolean
  /** "bars" stacks one bar per step; "flow" runs the steps left to right, each tapering into the next. */
  variant?: "bars" | "flow"
  /** Flow only. "eased" curves each neck; "sharp" draws straight trapezoids. */
  shape?: "eased" | "sharp"
  /** Flow only. Height of the stages in pixels. */
  height?: number
  /** Flow only. Width of the neck between stages in pixels. */
  neckWidth?: number
  /** Flow only. Show the share of the first step as a pill on each stage. */
  showPercentages?: boolean
  /** Flow only. Show a tile with the name and value under each stage. */
  showLabels?: boolean
  /** Flow only. Stage drawn at full strength while the rest dim. */
  activeIndex?: number | null
  onActiveIndexChange?: (index: number | null) => void
}

const defaultColors = [
  "var(--chart-1)",
  "var(--chart-2)",
  "var(--chart-3)",
  "var(--chart-4)",
  "var(--chart-5)",
]

// Round so server and client render identical path strings.
const round = (n: number) => Math.round(n * 1000) / 1000

/** Path for the neck between two stages, in a 1x1 box stretched to fit. */
function neckPath(from: number, to: number, shape: "eased" | "sharp") {
  const t0 = round((1 - from) / 2)
  const b0 = round(1 - t0)
  const t1 = round((1 - to) / 2)
  const b1 = round(1 - t1)
  if (shape === "sharp") return `M0,${t0} L1,${t1} L1,${b1} L0,${b0} Z`
  return `M0,${t0} C0.5,${t0} 0.5,${t1} 1,${t1} L1,${b1} C0.5,${b1} 0.5,${b0} 0,${b0} Z`
}

function FunnelBars({
  steps,
  valueFormatter,
  color,
  showDropoff,
}: {
  steps: FunnelStep[]
  valueFormatter: (value: number) => string
  color: string
  showDropoff: boolean
}) {
  const first = steps[0]?.value ?? 0
  const last = steps[steps.length - 1]?.value ?? 0
  const overall = first > 0 ? last / first : 0

  return (
    <>
      {steps.map((step, index) => {
        const previous = index > 0 ? steps[index - 1]!.value : step.value
        const ofFirst = first > 0 ? step.value / first : 0
        const ofPrevious = previous > 0 ? step.value / previous : 0
        const dropoff = 1 - ofPrevious

        return (
          <React.Fragment key={step.name}>
            {showDropoff && index > 0 ? (
              <div className="text-muted-foreground flex items-center gap-2 py-1 pl-3 text-xs">
                <span aria-hidden="true" className="bg-border h-3 w-px" />
                <span className="tabular-nums">
                  {formatNumber(dropoff, { format: "percent" })} drop-off
                </span>
              </div>
            ) : null}
            <div data-slot="funnel-step" className="flex flex-col gap-1.5">
              <div className="flex items-baseline justify-between gap-4 text-sm">
                <span className="flex items-center gap-2 truncate">
                  <span className="text-muted-foreground w-4 shrink-0 text-xs tabular-nums">
                    {index + 1}
                  </span>
                  <span className="truncate font-medium">{step.name}</span>
                </span>
                <span className="flex shrink-0 items-baseline gap-2 tabular-nums">
                  <span className="font-medium">{valueFormatter(step.value)}</span>
                  <span className="text-muted-foreground w-12 text-right text-xs">
                    {formatNumber(ofFirst, { format: "percent" })}
                  </span>
                </span>
              </div>
              <div className="bg-muted h-6 w-full overflow-hidden rounded-md">
                <div
                  className="h-full rounded-md transition-[width] duration-300"
                  style={{
                    width: `${ofFirst * 100}%`,
                    backgroundColor: color,
                    opacity: 1 - index * (0.5 / Math.max(steps.length - 1, 1)),
                  }}
                />
              </div>
            </div>
          </React.Fragment>
        )
      })}
      {steps.length > 1 ? (
        <div className="mt-2 flex items-center justify-between border-t pt-3 text-sm">
          <span className="text-muted-foreground">Overall conversion</span>
          <span className="font-semibold tabular-nums">
            {formatNumber(overall, { format: "percent" })}
          </span>
        </div>
      ) : null}
    </>
  )
}

function FunnelFlow({
  steps,
  valueFormatter,
  color,
  shape,
  height,
  neckWidth,
  showPercentages,
  showLabels,
  activeIndex,
  onActiveIndexChange,
}: {
  steps: FunnelStep[]
  valueFormatter: (value: number) => string
  color?: string
  shape: "eased" | "sharp"
  height: number
  neckWidth: number
  showPercentages: boolean
  showLabels: boolean
  activeIndex?: number | null
  onActiveIndexChange?: (index: number | null) => void
}) {
  const id = React.useId()
  const [activeState, setActiveState] = React.useState<number | null>(null)
  const active = activeIndex === undefined ? activeState : activeIndex
  const setActive = (index: number | null) => {
    setActiveState(index)
    onActiveIndexChange?.(index)
  }

  const first = steps[0]?.value ?? 0
  const stages = steps.map((step, index) => ({
    ...step,
    share: first > 0 ? Math.min(1, Math.max(0, step.value / first)) : 0,
    fill: step.color ?? color ?? defaultColors[index % defaultColors.length],
    // A single color fades toward the end of the funnel so stages stay distinct.
    opacity: color && !step.color ? 1 - index * (0.6 / Math.max(steps.length - 1, 1)) : 1,
  }))

  return (
    <>
      <div
        data-slot="funnel-flow"
        className="flex w-full items-stretch"
        style={{ height }}
        onMouseLeave={() => setActive(null)}
      >
        {stages.map((stage, index) => {
          const next = stages[index + 1]
          const dimmed = active !== null && active !== index
          const neckDimmed = active !== null && active !== index && active !== index + 1
          const gradient = `${id}-${index}`
          return (
            <React.Fragment key={stage.name}>
              <div
                data-slot="funnel-stage"
                data-active={active === index || undefined}
                onMouseEnter={() => setActive(index)}
                className="relative flex min-w-0 flex-1 items-center transition-opacity duration-200"
                style={{ opacity: dimmed ? 0.35 : 1 }}
              >
                <div
                  className={cn(
                    "w-full transition-[height] duration-500 ease-out",
                    index === 0 && "rounded-l-lg",
                    index === stages.length - 1 && "rounded-r-lg"
                  )}
                  style={{
                    height: `${round(stage.share * 100)}%`,
                    minHeight: 4,
                    backgroundColor: stage.fill,
                    opacity: stage.opacity,
                  }}
                />
                {showPercentages ? (
                  <span className="bg-background/90 text-foreground ring-foreground/10 pointer-events-none absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 rounded-full px-2 py-0.5 text-[11px] font-medium tabular-nums shadow-xs ring-1 backdrop-blur-sm">
                    {formatNumber(stage.share, { format: "percent", maximumFractionDigits: 0 })}
                  </span>
                ) : null}
              </div>
              {next ? (
                <svg
                  aria-hidden="true"
                  data-slot="funnel-neck"
                  viewBox="0 0 1 1"
                  preserveAspectRatio="none"
                  className="h-full shrink-0 transition-opacity duration-200"
                  style={{ width: neckWidth, opacity: neckDimmed ? 0.35 : 1 }}
                >
                  <defs>
                    <linearGradient id={gradient} x1="0" y1="0" x2="1" y2="0">
                      <stop offset="0" stopColor={stage.fill} stopOpacity={stage.opacity} />
                      <stop offset="1" stopColor={next.fill} stopOpacity={next.opacity} />
                    </linearGradient>
                  </defs>
                  <path
                    d={neckPath(stage.share, next.share, shape)}
                    fill={`url(#${gradient})`}
                    className="transition-[d] duration-500 ease-out"
                  />
                </svg>
              ) : null}
            </React.Fragment>
          )
        })}
      </div>
      {showLabels ? (
        <div
          data-slot="funnel-labels"
          className="grid gap-2"
          style={{ gridTemplateColumns: `repeat(${stages.length}, minmax(0, 1fr))` }}
        >
          {stages.map((stage, index) => (
            <div
              key={stage.name}
              data-active={active === index || undefined}
              onMouseEnter={() => setActive(index)}
              onMouseLeave={() => setActive(null)}
              className={cn(
                "flex min-w-0 flex-col gap-0.5 rounded-lg border px-2.5 py-2 transition-[opacity,border-color] duration-200",
                active !== null && active !== index && "opacity-50",
                active === index && "border-foreground/20"
              )}
            >
              <span className="text-muted-foreground flex items-center gap-1.5 text-xs">
                <span
                  aria-hidden="true"
                  className="size-2 shrink-0 rounded-full"
                  style={{ backgroundColor: stage.fill, opacity: stage.opacity }}
                />
                <span className="truncate">{stage.name}</span>
              </span>
              <span className="truncate text-sm font-semibold tabular-nums">
                {valueFormatter(stage.value)}
              </span>
            </div>
          ))}
        </div>
      ) : null}
    </>
  )
}

/** Step-by-step conversion, as stacked bars with drop-off or as a flow of tapering stages. */
function FunnelChart({
  steps,
  valueFormatter = (value) => formatNumber(value),
  color,
  showDropoff = true,
  variant = "bars",
  shape = "eased",
  height = 160,
  neckWidth = 24,
  showPercentages = true,
  showLabels = true,
  activeIndex,
  onActiveIndexChange,
  className,
  ...props
}: FunnelChartProps) {
  return (
    <div
      data-slot="funnel-chart"
      data-variant={variant}
      className={cn("flex flex-col", variant === "flow" ? "gap-3" : "gap-1", className)}
      {...props}
    >
      {variant === "flow" ? (
        <FunnelFlow
          steps={steps}
          valueFormatter={valueFormatter}
          color={color}
          shape={shape}
          height={height}
          neckWidth={neckWidth}
          showPercentages={showPercentages}
          showLabels={showLabels}
          activeIndex={activeIndex}
          onActiveIndexChange={onActiveIndexChange}
        />
      ) : (
        <FunnelBars
          steps={steps}
          valueFormatter={valueFormatter}
          color={color ?? "var(--chart-1)"}
          showDropoff={showDropoff}
        />
      )}
    </div>
  )
}

export { FunnelChart }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Heatmap Chart

A matrix heatmap with a row per line and a column per label, e.g. weekday by hour, with hover highlighting and tooltips.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/heatmap-chart.json
```

Also installs `tooltip` from shadcn/ui if missing.

## Usage

```tsx
import { HeatmapChart } from "@/components/ui/heatmap-chart"

<HeatmapChart
  rows={[
    { label: "Mon", values: [12, 48, 210, 320, 260, 80] },
    { label: "Tue", values: [10, 52, 230, 340, 250, 70] },
  ]}
  columns={["00", "04", "08", "12", "16", "20"]}
  unit="sessions"
/>
```

## Examples

### Default

```tsx
import { HeatmapChart } from "@/components/ui/heatmap-chart"

const days = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
const hours = Array.from({ length: 12 }, (_, i) => String(i * 2).padStart(2, "0"))

// Deterministic sample data so the demo is stable between renders: a working-hours
// peak on weekdays, a quieter and later curve at the weekend, plus some noise.
function sampleRows() {
  let seed = 7
  const random = () => {
    seed = (seed * 1664525 + 1013904223) % 4294967296
    return seed / 4294967296
  }
  return days.map((label, d) => {
    const weekend = d >= 5
    return {
      label,
      values: hours.map((_, h) => {
        const hour = h * 2 + 1
        const peak = weekend ? 15 : 14
        const shape = Math.exp(-((hour - peak) ** 2) / (weekend ? 40 : 22))
        const base = (weekend ? 90 : 320) * shape + (weekend ? 6 : 12)
        return Math.round(base * (0.75 + random() * 0.5))
      }),
    }
  })
}

const rows = sampleRows()

export default function HeatmapChartDemo() {
  return (
    <div className="w-full max-w-lg">
      <HeatmapChart rows={rows} columns={hours} unit="sessions" />
    </div>
  )
}
```

### Regions by month

Any two axes work. Set color for the accent and scale to "sqrt" to spread out small values.

```tsx
"use client"

import { HeatmapChart } from "@/components/ui/heatmap-chart"

const months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]

// Orders per region and month, in thousands. Each region has its own size and
// seasonal shape so the rows read differently instead of as one gradient.
const regions: { label: string; size: number; peak: number }[] = [
  { label: "North America", size: 48, peak: 11 },
  { label: "Europe", size: 36, peak: 10 },
  { label: "Asia Pacific", size: 42, peak: 5 },
  { label: "Latin America", size: 14, peak: 7 },
  { label: "Middle East", size: 9, peak: 2 },
  { label: "Africa", size: 5, peak: 8 },
]

function sampleRows() {
  let seed = 19
  const random = () => {
    seed = (seed * 1664525 + 1013904223) % 4294967296
    return seed / 4294967296
  }
  return regions.map((region) => ({
    label: region.label,
    values: months.map((_, m) => {
      const distance = Math.min(Math.abs(m - region.peak), 12 - Math.abs(m - region.peak))
      const season = 0.45 + 0.55 * Math.cos((distance / 6) * Math.PI) ** 2
      return Math.round(region.size * season * (0.85 + random() * 0.3) * 10) / 10
    }),
  }))
}

const rows = sampleRows()

export default function HeatmapChartRegionsDemo() {
  return (
    <div className="w-full max-w-lg">
      <HeatmapChart
        rows={rows}
        columns={months}
        color="var(--color-violet-500)"
        scale="sqrt"
        unit="K orders"
        valueFormatter={(value) => value.toFixed(1)}
      />
    </div>
  )
}
```

## Source

### components/ui/heatmap-chart.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

export interface HeatmapRow {
  label: string
  /** One value per column, in column order. Missing entries read as 0. */
  values: number[]
}

/** A cell's position by row and column index. */
export interface HeatmapCell {
  row: number
  column: number
}

export interface HeatmapDatum extends HeatmapCell {
  rowLabel: string
  columnLabel: string
  value: number
}

export interface HeatmapChartProps extends React.ComponentProps<"div"> {
  /** One row per line of the matrix, top to bottom. */
  rows: HeatmapRow[]
  /** Column labels, left to right. Sets the number of columns. */
  columns: string[]
  /** Any CSS color. Cells mix this into `--muted` by value. Defaults to chart-1. */
  color?: string
  /** Value drawn fully saturated. Defaults to the largest value. */
  max?: number
  /** How values map to color. `sqrt` spreads out small values. */
  scale?: "linear" | "sqrt"
  /** Quantize the fill into this many steps instead of a continuous ramp. */
  levels?: number
  /** Gap between cells in px. Cells themselves stretch to fill the container. */
  gap?: number
  valueFormatter?: (value: number) => string
  /** Label for the value in the tooltip, e.g. "sessions". */
  unit?: string
  showLegend?: boolean
  showRowLabels?: boolean
  showColumnLabels?: boolean
  /** Show every nth column label. Defaults to whatever keeps about 12 labels. */
  columnLabelEvery?: number
  /** Replace the tooltip body. Return `null` to hide it for that cell. */
  renderTooltip?: (datum: HeatmapDatum) => React.ReactNode
  onCellClick?: (datum: HeatmapDatum) => void
  /** The hovered cell, to control it from outside. */
  activeCell?: HeatmapCell | null
  /** Called when the hovered cell changes, with null when the pointer leaves. */
  onActiveCellChange?: (cell: HeatmapCell | null) => void
}

/** Where a value sits between the muted track (0) and the accent (1). */
function fractionFor(
  value: number,
  max: number,
  scale: "linear" | "sqrt",
  levels?: number
) {
  if (value <= 0 || max <= 0) return 0
  let t = Math.min(1, value / max)
  if (scale === "sqrt") t = Math.sqrt(t)
  if (levels && levels > 1) {
    t = Math.max(1, Math.ceil(t * (levels - 1))) / (levels - 1)
  }
  return t
}

function fillFor(color: string, fraction: number) {
  if (fraction <= 0) return "var(--muted)"
  // Floor the mix so the smallest non-zero values still read against the track.
  const pct = Math.round(12 + fraction * 88)
  return `color-mix(in oklab, ${color} ${pct}%, var(--muted))`
}

/**
 * A matrix heatmap with a row per line and a column per label, e.g. weekday by hour.
 * Cells stretch to the container width. Hovering a cell rings it, lights up its row
 * and column labels, and shows its value.
 */
function HeatmapChart({
  rows,
  columns,
  color = "var(--chart-1)",
  max,
  scale = "linear",
  levels,
  gap = 4,
  valueFormatter = (value) => formatNumber(value),
  unit,
  showLegend = true,
  showRowLabels = true,
  showColumnLabels = true,
  columnLabelEvery,
  renderTooltip,
  onCellClick,
  activeCell,
  onActiveCellChange,
  className,
  ...props
}: HeatmapChartProps) {
  const [internal, setInternal] = React.useState<HeatmapCell | null>(null)
  const active = activeCell === undefined ? internal : activeCell
  const setActive = (cell: HeatmapCell | null) => {
    setInternal(cell)
    onActiveCellChange?.(cell)
  }

  const top = React.useMemo(
    () =>
      max ??
      rows.reduce(
        (acc, row) => row.values.reduce((m, v) => Math.max(m, v), acc),
        0
      ),
    [rows, max]
  )

  const every = columnLabelEvery ?? Math.max(1, Math.ceil(columns.length / 12))
  const steps = levels && levels > 1 ? levels : 5
  const swatches = Array.from({ length: steps }, (_, i) =>
    fillFor(color, i / (steps - 1))
  )

  const withUnit = (value: number) =>
    unit ? `${valueFormatter(value)} ${unit}` : valueFormatter(value)

  return (
    <div
      data-slot="heatmap-chart"
      className={cn("flex min-w-0 flex-col gap-2 text-xs", className)}
      {...props}
    >
      <TooltipProvider delayDuration={100} skipDelayDuration={0}>
        <div
          role="group"
          aria-label="Heatmap"
          className="grid min-w-0"
          style={{
            gap,
            gridTemplateColumns: `${showRowLabels ? "auto " : ""}repeat(${columns.length}, minmax(0, 1fr))`,
          }}
          onPointerLeave={() => setActive(null)}
        >
          {rows.map((row, r) => (
            <React.Fragment key={r}>
              {showRowLabels ? (
                <div
                  data-slot="heatmap-chart-row-label"
                  data-active={active?.row === r}
                  onPointerEnter={() => setActive(null)}
                  className="text-muted-foreground data-[active=true]:text-foreground flex items-center pr-1.5 leading-none whitespace-nowrap transition-colors"
                >
                  {row.label}
                </div>
              ) : null}
              {columns.map((column, c) => {
                const value = row.values[c] ?? 0
                const datum: HeatmapDatum = {
                  row: r,
                  column: c,
                  rowLabel: row.label,
                  columnLabel: column,
                  value,
                }
                const isActive = active?.row === r && active?.column === c
                const body = renderTooltip ? (
                  renderTooltip(datum)
                ) : (
                  <>
                    <span className="font-medium tabular-nums">{withUnit(value)}</span>
                    <span className="text-background/70 block">
                      {row.label} · {column}
                    </span>
                  </>
                )

                const cell = (
                  <button
                    type="button"
                    aria-label={`${withUnit(value)}, ${row.label} ${column}`}
                    data-slot="heatmap-chart-cell"
                    data-row={r}
                    data-column={c}
                    data-active={isActive}
                    onPointerEnter={() => setActive({ row: r, column: c })}
                    onFocus={() => setActive({ row: r, column: c })}
                    onBlur={(event) => {
                      // Keep the highlight while focus moves between cells so the readout does not flash.
                      const next = event.relatedTarget
                      if (next instanceof HTMLElement && next.dataset.slot === "heatmap-chart-cell") return
                      setActive(null)
                    }}
                    onClick={onCellClick ? () => onCellClick(datum) : undefined}
                    className={cn(
                      "inset-ring-foreground/6 aspect-square w-full rounded-sm outline-none inset-ring transition-[box-shadow] duration-100",
                      "data-[active=true]:inset-ring-foreground/45 data-[active=true]:inset-ring-2",
                      "focus-visible:inset-ring-ring focus-visible:inset-ring-2",
                      onCellClick ? "cursor-pointer" : "cursor-default"
                    )}
                    style={{
                      backgroundColor: fillFor(
                        color,
                        fractionFor(value, top, scale, levels)
                      ),
                    }}
                  />
                )

                if (body === null) {
                  return <React.Fragment key={c}>{cell}</React.Fragment>
                }

                return (
                  <Tooltip key={c}>
                    <TooltipTrigger asChild>{cell}</TooltipTrigger>
                    <TooltipContent sideOffset={4} className="text-left">
                      {body}
                    </TooltipContent>
                  </Tooltip>
                )
              })}
            </React.Fragment>
          ))}

          {showColumnLabels ? (
            <>
              {showRowLabels ? <div aria-hidden /> : null}
              {columns.map((column, c) => (
                <div
                  key={c}
                  data-slot="heatmap-chart-column-label"
                  data-active={active?.column === c}
                  onPointerEnter={() => setActive(null)}
                  className="text-muted-foreground data-[active=true]:text-foreground min-w-0 pt-0.5 text-center leading-none whitespace-nowrap transition-colors"
                >
                  {c % every === 0 ? column : ""}
                </div>
              ))}
            </>
          ) : null}
        </div>
      </TooltipProvider>

      {showLegend ? (
        <div className="text-muted-foreground flex items-center justify-end gap-1">
          <span className="mr-0.5">Less</span>
          {swatches.map((fill, index) => (
            <span
              key={index}
              className="inset-ring-foreground/6 size-3 rounded-[3px] inset-ring"
              style={{ backgroundColor: fill }}
            />
          ))}
          <span className="ml-0.5">More</span>
        </div>
      ) : null}
    </div>
  )
}

export { HeatmapChart }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# KPI Card

A metric card with value, period-over-period delta, and an optional sparkline.

The KPI card is the stat card at the top of most dashboards: a label, a formatted value, a delta badge for the change since last period, and an optional sparkline. It is built from the shadcn/ui Card, so it matches the rest of your app, and it knows that a decrease is good for metrics like churn or latency.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/kpi-card.json
```

Also installs `card`, `tooltip` from shadcn/ui if missing.

npm dependencies: `recharts`, `lucide-react`.

## Usage

```tsx
import { KpiCard } from "@/components/ui/kpi-card"

<KpiCard
  label="Revenue"
  value={84120}
  format="currency"
  delta={0.124}
  deltaLabel="vs. last 30 days"
  trend={[42, 48, 45, 52, 58, 61, 67, 72, 78, 84]}
/>
```

## Examples

### Default

```tsx
import { KpiCard } from "@/components/ui/kpi-card"

const revenue = [42, 48, 45, 52, 58, 55, 61, 67, 64, 72, 78, 84]
const users = [1200, 1260, 1250, 1300, 1310, 1290, 1280, 1300, 1295, 1310, 1300, 1305]
const churn = [3.2, 3.1, 3.3, 2.9, 2.8, 2.9, 2.6, 2.5, 2.4, 2.4, 2.2, 2.1]

export default function KpiCardDemo() {
  return (
    <div className="@container w-full">
      <div className="grid gap-4 @lg:grid-cols-2 @3xl:grid-cols-4">
        <KpiCard
          label="Revenue"
          value={84_120}
          format="currency"
          delta={0.124}
          deltaLabel="vs. last 30 days"
          trend={revenue}
        />
        <KpiCard
          label="Active users"
          value={1_305}
          format="compact"
          delta={0.004}
          deltaLabel="vs. last 30 days"
          trend={users}
        />
        <KpiCard
          label="Churn"
          value={0.021}
          format="percent"
          delta={-0.34}
          deltaLabel="vs. last 30 days"
          trend={churn}
          invertDelta
        />
        <KpiCard
          label="Open tickets"
          value={17}
          delta={0}
          deltaLabel="No change this week"
        />
      </div>
    </div>
  )
}
```

## Source

### components/ui/kpi-card.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { type NumberFormat } from "@/lib/format"
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@/components/ui/card"
import { DeltaBadge, getDeltaDirection } from "@/components/ui/delta-badge"
import { Sparkline } from "@/components/ui/sparkline"
import { MetricValue } from "@/components/ui/metric-value"

export interface KpiCardProps extends Omit<
  React.ComponentProps<typeof Card>,
  "children"
> {
  /** Metric name, e.g. "Revenue". */
  label: string
  /** Current value. Numbers are formatted with `format`; strings render as-is. */
  value: number | string
  /** Fractional change vs. the previous period, e.g. 0.124 for +12.4%. */
  delta?: number
  /** Context for the delta, e.g. "vs. last 30 days". */
  deltaLabel?: string
  /** Series for the sparkline. Rendered when it has two or more points. */
  trend?: number[]
  format?: NumberFormat
  /** ISO 4217 code, used when `format` is "currency". */
  currency?: string
  /** Treat a decrease as good and an increase as bad (churn, latency, errors). */
  invertDelta?: boolean
  /** Optional icon shown before the label. */
  icon?: React.ReactNode
  children?: React.ReactNode
}

function KpiCard({
  label,
  value,
  delta,
  deltaLabel,
  trend,
  format = "number",
  currency,
  invertDelta = false,
  icon,
  className,
  children,
  ...props
}: KpiCardProps) {
  const direction = getDeltaDirection(delta)
  const isPositive =
    direction === "flat" ? null : (direction === "up") !== invertDelta
  const trendColor =
    isPositive === true
      ? "var(--color-emerald-500)"
      : isPositive === false
        ? "var(--color-red-500)"
        : "var(--primary)"

  return (
    <Card
      data-slot="kpi-card"
      data-direction={direction}
      className={cn("gap-4 py-5", className)}
      {...props}
    >
      <CardHeader className="px-5">
        <CardDescription className="flex items-center gap-1.5 [&>svg]:size-4">
          {icon}
          {label}
        </CardDescription>
        <CardTitle className="text-2xl font-semibold tabular-nums tracking-tight">
          <MetricValue value={value} format={format} currency={currency} />
        </CardTitle>
        {delta !== undefined ? (
          <CardAction>
            <DeltaBadge delta={delta} invert={invertDelta} />
          </CardAction>
        ) : null}
      </CardHeader>
      {trend && trend.length > 1 ? (
        <CardContent className="px-5">
          <Sparkline data={trend} color={trendColor} />
        </CardContent>
      ) : null}
      {deltaLabel || children ? (
        <CardContent className="text-muted-foreground flex items-center gap-2 px-5 text-xs">
          {deltaLabel ? <span>{deltaLabel}</span> : null}
          {children}
        </CardContent>
      ) : null}
    </Card>
  )
}

export { KpiCard }
```

### components/ui/delta-badge.tsx

```tsx
import * as React from "react"
import { Minus, TrendingDown, TrendingUp } from "lucide-react"

import { cn } from "@/lib/utils"
import { formatDelta } from "@/lib/format"

export type DeltaDirection = "up" | "down" | "flat"

export function getDeltaDirection(delta: number | undefined): DeltaDirection {
  if (delta === undefined || delta === 0 || !Number.isFinite(delta)) return "flat"
  return delta > 0 ? "up" : "down"
}

const directionIcon: Record<DeltaDirection, React.ElementType> = {
  up: TrendingUp,
  down: TrendingDown,
  flat: Minus,
}

export interface DeltaBadgeProps extends React.ComponentProps<"span"> {
  /** Fractional change, e.g. 0.124 for +12.4%. */
  delta: number
  /** Treat a decrease as good and an increase as bad (churn, latency, errors). */
  invert?: boolean
  variant?: "outline" | "soft" | "text"
  showIcon?: boolean
}

function DeltaBadge({
  delta,
  invert = false,
  variant = "outline",
  showIcon = true,
  className,
  children,
  ...props
}: DeltaBadgeProps) {
  const direction = getDeltaDirection(delta)
  const positive = direction === "flat" ? null : (direction === "up") !== invert
  const Icon = directionIcon[direction]

  return (
    <span
      data-slot="delta-badge"
      data-direction={direction}
      data-positive={positive}
      className={cn(
        "inline-flex items-center gap-1 text-xs font-medium tabular-nums",
        variant === "outline" && "rounded-md border px-1.5 py-0.5",
        variant === "soft" && "rounded-md px-1.5 py-0.5",
        variant === "soft" && positive === true && "bg-emerald-500/10",
        variant === "soft" && positive === false && "bg-red-500/10",
        variant === "soft" && positive === null && "bg-muted",
        positive === true && "text-emerald-600 dark:text-emerald-400",
        positive === false && "text-red-600 dark:text-red-400",
        positive === null && "text-muted-foreground",
        className
      )}
      {...props}
    >
      {showIcon ? <Icon className="size-3" aria-hidden="true" /> : null}
      {children ?? formatDelta(delta)}
    </span>
  )
}

export { DeltaBadge }
```

### components/ui/sparkline.tsx

```tsx
"use client"

import * as React from "react"
import {
  Area,
  AreaChart,
  AreaRevealShape,
  Line,
  LineChart,
  ResponsiveContainer,
  type AreaRevealShapeProps,
} from "recharts"

import { cn } from "@/lib/utils"

export interface SparklineProps extends React.ComponentProps<"div"> {
  /** Series to plot, oldest first. */
  data: number[]
  variant?: "area" | "line"
  /** Area fill: a plain gradient, or a dot grid that fades out toward the line. */
  fill?: "gradient" | "dots"
  /** Any CSS color. Defaults to the theme primary. */
  color?: string
  curve?: "monotone" | "linear" | "step"
  strokeWidth?: number
}

/** Area shape that masks the fill to a dot grid while keeping the stroke solid. */
function DotGridAreaShape({
  maskId,
  ...props
}: AreaRevealShapeProps & { maskId: string }) {
  return (
    <>
      <g mask={`url(#${maskId})`}>
        <AreaRevealShape {...props} stroke="none" />
      </g>
      <AreaRevealShape {...props} id={undefined} fill="none" />
    </>
  )
}

function Sparkline({
  data,
  variant = "area",
  fill = "gradient",
  color = "var(--primary)",
  curve = "monotone",
  strokeWidth = 1.5,
  className,
  ...props
}: SparklineProps) {
  const id = React.useId()
  const dots = variant === "area" && fill === "dots"
  const points = React.useMemo(() => data.map((y, i) => ({ i, y })), [data])
  const margin = { top: 2, right: 0, bottom: 0, left: 0 }

  return (
    <div
      data-slot="sparkline"
      aria-hidden="true"
      className={cn("h-10 w-full", className)}
      {...props}
    >
      <ResponsiveContainer width="100%" height="100%">
        {variant === "line" ? (
          <LineChart data={points} margin={margin}>
            <Line
              type={curve}
              dataKey="y"
              stroke={color}
              strokeWidth={strokeWidth}
              dot={false}
              isAnimationActive={false}
            />
          </LineChart>
        ) : (
          <AreaChart data={points} margin={margin}>
            <defs>
              <linearGradient id={id} x1="0" y1="0" x2="0" y2="1">
                <stop offset="0%" stopColor={color} stopOpacity={dots ? 0.08 : 0.3} />
                <stop offset="100%" stopColor={color} stopOpacity={dots ? 0.9 : 0} />
              </linearGradient>
              {dots ? (
                <>
                  <pattern
                    id={`${id}-dots`}
                    patternUnits="userSpaceOnUse"
                    width={4}
                    height={4}
                  >
                    <circle cx={2} cy={2} r={0.9} fill="#fff" />
                  </pattern>
                  <mask
                    id={`${id}-mask`}
                    maskUnits="userSpaceOnUse"
                    x={0}
                    y={0}
                    width="100%"
                    height="100%"
                  >
                    <rect width="100%" height="100%" fill={`url(#${id}-dots)`} />
                  </mask>
                </>
              ) : null}
            </defs>
            <Area
              type={curve}
              dataKey="y"
              stroke={color}
              strokeWidth={strokeWidth}
              fill={`url(#${id})`}
              fillOpacity={dots ? 1 : undefined}
              dot={false}
              isAnimationActive={false}
              shape={
                dots
                  ? (shapeProps: AreaRevealShapeProps) => (
                      <DotGridAreaShape {...shapeProps} maskId={`${id}-mask`} />
                    )
                  : undefined
              }
            />
          </AreaChart>
        )}
      </ResponsiveContainer>
    </div>
  )
}

export { Sparkline }
```

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Metric List

Compact rows of label, sparkline, value, and delta.

Compact rows of label, sparkline, value, and delta, for listing several metrics in the space of one card. It uses the same formatting and delta conventions as the KPI card.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/metric-list.json
```

Also installs `tooltip` from shadcn/ui if missing.

npm dependencies: `recharts`, `lucide-react`.

## Usage

```tsx
import { MetricList } from "@/components/ui/metric-list"

<MetricList
  items={[
    { label: "Orders", value: 2865, delta: 0.18, trend: [12, 14, 13, 18, 22, 26] },
    { label: "Refunds", value: 42, delta: -0.06, invertDelta: true, trend: [50, 48, 51, 46, 42] },
  ]}
/>
```

## Examples

### Default

```tsx
import { MetricList } from "@/components/ui/metric-list"

const items = [
  { label: "Orders", value: 2_865, delta: 0.18, trend: [12, 14, 13, 18, 22, 21, 26] },
  { label: "Response time", value: "135 ms", delta: 0.14, invertDelta: true, trend: [140, 130, 128, 135, 150, 142, 135] },
  { label: "Revenue", value: 8_670, format: "currency" as const, delta: 0.15, trend: [5, 6, 6.5, 6, 7.2, 8.1, 8.6] },
  { label: "Users", value: 1_425, delta: 0.15, trend: [900, 950, 1_010, 1_100, 1_180, 1_320, 1_425] },
  { label: "Refunds", value: 42, delta: -0.06, invertDelta: true, trend: [50, 48, 51, 46, 44, 45, 42] },
]

export default function MetricListDemo() {
  return (
    <div className="w-full max-w-md">
      <MetricList items={items} />
    </div>
  )
}
```

## Source

### components/ui/metric-list.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { type NumberFormat } from "@/lib/format"
import { DeltaBadge, getDeltaDirection } from "@/components/ui/delta-badge"
import { Sparkline } from "@/components/ui/sparkline"
import { MetricValue } from "@/components/ui/metric-value"

export interface MetricListItem {
  label: string
  value: number | string
  delta?: number
  trend?: number[]
  format?: NumberFormat
  currency?: string
  invertDelta?: boolean
  icon?: React.ReactNode
  key?: string
}

export interface MetricListProps extends React.ComponentProps<"div"> {
  items: MetricListItem[]
  /** Sparkline variant. */
  variant?: "area" | "line"
  /** Sparkline area fill. */
  fill?: "gradient" | "dots"
  showDivider?: boolean
}

/** Compact rows of label, sparkline, value, and delta. */
function MetricList({
  items,
  variant = "line",
  fill,
  showDivider = true,
  className,
  ...props
}: MetricListProps) {
  return (
    <div
      data-slot="metric-list"
      className={cn("flex flex-col", showDivider && "divide-y", className)}
      {...props}
    >
      {items.map((item) => {
        const direction = getDeltaDirection(item.delta)
        const positive =
          direction === "flat" ? null : (direction === "up") !== Boolean(item.invertDelta)
        const color =
          positive === true
            ? "var(--color-emerald-500)"
            : positive === false
              ? "var(--color-red-500)"
              : "var(--muted-foreground)"
        return (
          <div
            key={item.key ?? item.label}
            data-slot="metric-list-row"
            className="flex items-center gap-4 py-2.5 text-sm first:pt-0 last:pb-0"
          >
            <div className="flex min-w-0 flex-1 items-center gap-2">
              {item.icon ? (
                <span className="text-muted-foreground shrink-0 [&>svg]:size-4">
                  {item.icon}
                </span>
              ) : null}
              <span className="truncate">{item.label}</span>
            </div>
            {item.trend && item.trend.length > 1 ? (
              <Sparkline
                data={item.trend}
                variant={variant}
                fill={fill}
                color={color}
                className="h-6 w-20 shrink-0"
              />
            ) : null}
            <div className="flex w-28 shrink-0 items-center justify-end gap-2 tabular-nums">
              <MetricValue
                value={item.value}
                format={item.format}
                currency={item.currency}
                className="font-medium"
              />
              {item.delta !== undefined ? (
                <DeltaBadge
                  delta={item.delta}
                  invert={item.invertDelta}
                  variant="text"
                  showIcon={false}
                />
              ) : null}
            </div>
          </div>
        )
      })}
    </div>
  )
}

export { MetricList }
```

### components/ui/delta-badge.tsx

```tsx
import * as React from "react"
import { Minus, TrendingDown, TrendingUp } from "lucide-react"

import { cn } from "@/lib/utils"
import { formatDelta } from "@/lib/format"

export type DeltaDirection = "up" | "down" | "flat"

export function getDeltaDirection(delta: number | undefined): DeltaDirection {
  if (delta === undefined || delta === 0 || !Number.isFinite(delta)) return "flat"
  return delta > 0 ? "up" : "down"
}

const directionIcon: Record<DeltaDirection, React.ElementType> = {
  up: TrendingUp,
  down: TrendingDown,
  flat: Minus,
}

export interface DeltaBadgeProps extends React.ComponentProps<"span"> {
  /** Fractional change, e.g. 0.124 for +12.4%. */
  delta: number
  /** Treat a decrease as good and an increase as bad (churn, latency, errors). */
  invert?: boolean
  variant?: "outline" | "soft" | "text"
  showIcon?: boolean
}

function DeltaBadge({
  delta,
  invert = false,
  variant = "outline",
  showIcon = true,
  className,
  children,
  ...props
}: DeltaBadgeProps) {
  const direction = getDeltaDirection(delta)
  const positive = direction === "flat" ? null : (direction === "up") !== invert
  const Icon = directionIcon[direction]

  return (
    <span
      data-slot="delta-badge"
      data-direction={direction}
      data-positive={positive}
      className={cn(
        "inline-flex items-center gap-1 text-xs font-medium tabular-nums",
        variant === "outline" && "rounded-md border px-1.5 py-0.5",
        variant === "soft" && "rounded-md px-1.5 py-0.5",
        variant === "soft" && positive === true && "bg-emerald-500/10",
        variant === "soft" && positive === false && "bg-red-500/10",
        variant === "soft" && positive === null && "bg-muted",
        positive === true && "text-emerald-600 dark:text-emerald-400",
        positive === false && "text-red-600 dark:text-red-400",
        positive === null && "text-muted-foreground",
        className
      )}
      {...props}
    >
      {showIcon ? <Icon className="size-3" aria-hidden="true" /> : null}
      {children ?? formatDelta(delta)}
    </span>
  )
}

export { DeltaBadge }
```

### components/ui/sparkline.tsx

```tsx
"use client"

import * as React from "react"
import {
  Area,
  AreaChart,
  AreaRevealShape,
  Line,
  LineChart,
  ResponsiveContainer,
  type AreaRevealShapeProps,
} from "recharts"

import { cn } from "@/lib/utils"

export interface SparklineProps extends React.ComponentProps<"div"> {
  /** Series to plot, oldest first. */
  data: number[]
  variant?: "area" | "line"
  /** Area fill: a plain gradient, or a dot grid that fades out toward the line. */
  fill?: "gradient" | "dots"
  /** Any CSS color. Defaults to the theme primary. */
  color?: string
  curve?: "monotone" | "linear" | "step"
  strokeWidth?: number
}

/** Area shape that masks the fill to a dot grid while keeping the stroke solid. */
function DotGridAreaShape({
  maskId,
  ...props
}: AreaRevealShapeProps & { maskId: string }) {
  return (
    <>
      <g mask={`url(#${maskId})`}>
        <AreaRevealShape {...props} stroke="none" />
      </g>
      <AreaRevealShape {...props} id={undefined} fill="none" />
    </>
  )
}

function Sparkline({
  data,
  variant = "area",
  fill = "gradient",
  color = "var(--primary)",
  curve = "monotone",
  strokeWidth = 1.5,
  className,
  ...props
}: SparklineProps) {
  const id = React.useId()
  const dots = variant === "area" && fill === "dots"
  const points = React.useMemo(() => data.map((y, i) => ({ i, y })), [data])
  const margin = { top: 2, right: 0, bottom: 0, left: 0 }

  return (
    <div
      data-slot="sparkline"
      aria-hidden="true"
      className={cn("h-10 w-full", className)}
      {...props}
    >
      <ResponsiveContainer width="100%" height="100%">
        {variant === "line" ? (
          <LineChart data={points} margin={margin}>
            <Line
              type={curve}
              dataKey="y"
              stroke={color}
              strokeWidth={strokeWidth}
              dot={false}
              isAnimationActive={false}
            />
          </LineChart>
        ) : (
          <AreaChart data={points} margin={margin}>
            <defs>
              <linearGradient id={id} x1="0" y1="0" x2="0" y2="1">
                <stop offset="0%" stopColor={color} stopOpacity={dots ? 0.08 : 0.3} />
                <stop offset="100%" stopColor={color} stopOpacity={dots ? 0.9 : 0} />
              </linearGradient>
              {dots ? (
                <>
                  <pattern
                    id={`${id}-dots`}
                    patternUnits="userSpaceOnUse"
                    width={4}
                    height={4}
                  >
                    <circle cx={2} cy={2} r={0.9} fill="#fff" />
                  </pattern>
                  <mask
                    id={`${id}-mask`}
                    maskUnits="userSpaceOnUse"
                    x={0}
                    y={0}
                    width="100%"
                    height="100%"
                  >
                    <rect width="100%" height="100%" fill={`url(#${id}-dots)`} />
                  </mask>
                </>
              ) : null}
            </defs>
            <Area
              type={curve}
              dataKey="y"
              stroke={color}
              strokeWidth={strokeWidth}
              fill={`url(#${id})`}
              fillOpacity={dots ? 1 : undefined}
              dot={false}
              isAnimationActive={false}
              shape={
                dots
                  ? (shapeProps: AreaRevealShapeProps) => (
                      <DotGridAreaShape {...shapeProps} maskId={`${id}-mask`} />
                    )
                  : undefined
              }
            />
          </AreaChart>
        )}
      </ResponsiveContainer>
    </div>
  )
}

export { Sparkline }
```

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Metric Value

A formatted number that abbreviates large values (e.g. $158K) and shows the full value in a tooltip on hover. Every card in this registry renders its numbers through it.

The number formatter used by every card here. It renders currency, percent, compact, and plain numbers, abbreviates large values to K, M, and B, and shows the full value in a tooltip on hover.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/metric-value.json
```

Also installs `tooltip` from shadcn/ui if missing.

## Usage

```tsx
import { MetricValue } from "@/components/ui/metric-value"

<MetricValue value={158143} format="currency" maximumFractionDigits={0} />
<MetricValue value={1234567} />
<MetricValue value={41194} format="currency" maximumFractionDigits={0} />
<MetricValue value={1234567} compactFrom={Infinity} />
```

## Examples

### Default

```tsx
import { MetricValue } from "@/components/ui/metric-value"

export default function MetricValueDemo() {
  return (
    <div className="flex flex-col gap-4 text-2xl font-semibold tracking-tight">
      <div className="flex flex-wrap items-baseline gap-x-6 gap-y-2">
        <MetricValue value={158143} format="currency" maximumFractionDigits={0} />
        <MetricValue value={1234567} />
        <MetricValue value={0.124} format="percent" />
        <MetricValue value={41194} format="currency" maximumFractionDigits={0} />
      </div>
      <p className="text-muted-foreground text-sm font-normal">
        Values from 100,000 up are abbreviated. Hover one to see the full value, or set
        compactFrom to change the threshold.
      </p>
      <div className="flex flex-wrap items-baseline gap-x-6 gap-y-2">
        <MetricValue value={1234567} compactFrom={Infinity} />
        <MetricValue value={41194} format="currency" maximumFractionDigits={0} compactFrom={10_000} />
        <MetricValue value={98} suffix=" ms" compactFrom={10} />
      </div>
    </div>
  )
}
```

## Source

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Period Tabs

A small segmented control for switching a chart between week, month, and year.

A small segmented control for switching a chart or card between periods like week, month, and year. It is a thin layer over shadcn's Tabs, with an optional animated pill.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/period-tabs.json
```

Also installs `tabs` from shadcn/ui if missing.

## Usage

```tsx
import { PeriodTabs } from "@/components/ui/period-tabs"

const [period, setPeriod] = React.useState("month")

<PeriodTabs value={period} onValueChange={setPeriod} />
```

## Examples

### Default

```tsx
"use client"

import * as React from "react"

import { PeriodTabs } from "@/components/ui/period-tabs"

export default function PeriodTabsDemo() {
  const [period, setPeriod] = React.useState("month")
  return (
    <div className="flex flex-col items-center gap-3">
      <PeriodTabs value={period} onValueChange={setPeriod} />
      <span className="text-muted-foreground text-sm">Showing: {period}</span>
    </div>
  )
}
```

### Animated

Set animated to slide a single pill between tabs instead of swapping backgrounds.

```tsx
"use client"

import * as React from "react"

import { PeriodTabs } from "@/components/ui/period-tabs"

export default function PeriodTabsAnimatedDemo() {
  const [period, setPeriod] = React.useState("month")
  return (
    <div className="flex flex-col items-center gap-3">
      <PeriodTabs animated value={period} onValueChange={setPeriod} />
      <span className="text-muted-foreground text-sm">Showing: {period}</span>
    </div>
  )
}
```

## Source

### components/ui/period-tabs.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"

export interface PeriodOption {
  value: string
  label: string
}

export const defaultPeriods: PeriodOption[] = [
  { value: "week", label: "Week" },
  { value: "month", label: "Month" },
  { value: "year", label: "Year" },
]

export interface PeriodTabsProps
  extends Omit<React.ComponentProps<typeof Tabs>, "children"> {
  options?: PeriodOption[]
  size?: "sm" | "default"
  /** Slide a single pill between tabs instead of swapping backgrounds. */
  animated?: boolean
}

interface IndicatorRect {
  left: number
  top: number
  width: number
  height: number
}

/** Small segmented control for switching a chart's time range. */
function PeriodTabs({
  options = defaultPeriods,
  size = "sm",
  animated = false,
  className,
  value,
  defaultValue,
  onValueChange,
  ...props
}: PeriodTabsProps) {
  const listRef = React.useRef<HTMLDivElement>(null)
  const [internalValue, setInternalValue] = React.useState(
    defaultValue ?? options[0]?.value
  )
  const active = value ?? internalValue
  const [rect, setRect] = React.useState<IndicatorRect | null>(null)

  const measure = React.useCallback(() => {
    const list = listRef.current
    if (!list) return
    const trigger = list.querySelector<HTMLElement>('[data-state="active"]')
    if (!trigger) return
    setRect({
      left: trigger.offsetLeft,
      top: trigger.offsetTop,
      width: trigger.offsetWidth,
      height: trigger.offsetHeight,
    })
  }, [])

  React.useLayoutEffect(() => {
    if (!animated) return
    measure()
  }, [animated, active, options, size, measure])

  React.useEffect(() => {
    if (!animated || !listRef.current) return
    const observer = new ResizeObserver(measure)
    observer.observe(listRef.current)
    return () => observer.disconnect()
  }, [animated, measure])

  return (
    <Tabs
      data-slot="period-tabs"
      className={cn("w-fit", className)}
      value={value}
      defaultValue={defaultValue}
      onValueChange={(next) => {
        setInternalValue(next)
        onValueChange?.(next)
      }}
      {...props}
    >
      <TabsList
        ref={listRef}
        className={cn(
          "relative",
          size === "sm" && "group-data-[orientation=horizontal]/tabs:h-8 p-1"
        )}
      >
        {animated && rect ? (
          <span
            aria-hidden
            data-slot="period-tabs-indicator"
            className="pointer-events-none absolute rounded-md bg-background shadow-sm transition-[left,top,width,height] duration-300 ease-[cubic-bezier(0.25,1,0.5,1)] motion-reduce:transition-none dark:border dark:border-input dark:bg-input/30"
            style={rect}
          />
        ) : null}
        {options.map((option) => (
          <TabsTrigger
            key={option.value}
            value={option.value}
            className={cn(
              size === "sm" && "h-6 px-2.5 text-xs",
              animated &&
                "relative z-10 data-[state=active]:bg-transparent group-data-[variant=default]/tabs-list:data-[state=active]:shadow-none dark:data-[state=active]:border-transparent dark:data-[state=active]:bg-transparent"
            )}
          >
            {option.label}
          </TabsTrigger>
        ))}
      </TabsList>
    </Tabs>
  )
}

export { PeriodTabs }
```

# Radar Chart

A filled, outlined, or dotted radar chart with polygon or circle grids, for scores and multi-series comparisons.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/radar-chart.json
```

Also installs `chart` from shadcn/ui if missing.

npm dependencies: `recharts`.

## Usage

```tsx
import { RadarChart } from "@/components/ui/radar-chart"

<RadarChart
  data={data}
  angleKey="month"
  series={[
    { key: "desktop", label: "Desktop" },
    { key: "mobile", label: "Mobile" },
  ]}
  variant="line"
  showLegend
/>
```

## Examples

### Default

```tsx
"use client"

import { RadarChart } from "@/components/ui/radar-chart"

const data = [
  { month: "January", visitors: 186_000 },
  { month: "February", visitors: 305_000 },
  { month: "March", visitors: 237_000 },
  { month: "April", visitors: 273_000 },
  { month: "May", visitors: 209_000 },
  { month: "June", visitors: 214_000 },
]

export default function RadarChartDemo() {
  return (
    <div className="w-full max-w-lg">
      <RadarChart
        data={data}
        angleKey="month"
        series={[{ key: "visitors", label: "Visitors" }]}
      />
    </div>
  )
}
```

### Multiple series

Each series draws its own polygon. variant="line" drops the fill so overlaps stay readable.

```tsx
"use client"

import { RadarChart } from "@/components/ui/radar-chart"

const data = [
  { month: "January", desktop: 186_000, mobile: 80_000 },
  { month: "February", desktop: 305_000, mobile: 200_000 },
  { month: "March", desktop: 237_000, mobile: 120_000 },
  { month: "April", desktop: 73_000, mobile: 190_000 },
  { month: "May", desktop: 209_000, mobile: 130_000 },
  { month: "June", desktop: 214_000, mobile: 140_000 },
]

export default function RadarChartMultiDemo() {
  return (
    <div className="w-full max-w-lg">
      <RadarChart
        data={data}
        angleKey="month"
        series={[
          { key: "desktop", label: "Desktop" },
          { key: "mobile", label: "Mobile" },
        ]}
        variant="line"
        showLegend
      />
    </div>
  )
}
```

### Score radar

variant="dots" marks every vertex. Set grid to "circle", a fixed domain, and showRadiusAxis for a scorecard.

```tsx
"use client"

import { RadarChart } from "@/components/ui/radar-chart"
import { formatNumber } from "@/lib/format"

const data = [
  { skill: "Speed", score: 82 },
  { skill: "Reliability", score: 91 },
  { skill: "Design", score: 68 },
  { skill: "Docs", score: 74 },
  { skill: "Support", score: 88 },
]

export default function RadarChartDotsDemo() {
  return (
    <div className="w-full max-w-lg">
      <RadarChart
        data={data}
        angleKey="skill"
        series={[{ key: "score", label: "Score" }]}
        variant="dots"
        grid="circle"
        domain={[0, 100]}
        showRadiusAxis
        valueFormatter={(v) => formatNumber(v)}
      />
    </div>
  )
}
```

## Source

### components/ui/radar-chart.tsx

```tsx
"use client"

import * as React from "react"
import {
  PolarAngleAxis,
  PolarGrid,
  PolarRadiusAxis,
  Radar,
  RadarChart as RechartsRadarChart,
} from "recharts"

import { cn } from "@/lib/utils"
import { formatNumber } from "@/lib/format"
import {
  ChartContainer,
  ChartLegend,
  ChartLegendContent,
  ChartTooltip,
  ChartTooltipContent,
  type ChartConfig,
} from "@/components/ui/chart"

export interface RadarSeries {
  /** Key in each data row. */
  key: string
  label: string
  /** Any CSS color. Defaults to chart-1 through chart-5 in order. */
  color?: string
}

export interface RadarChartProps
  extends Omit<React.ComponentProps<typeof ChartContainer>, "config" | "children"> {
  data: Record<string, unknown>[]
  /** Key of the category label in each row, one per spoke. */
  angleKey: string
  series: RadarSeries[]
  /** "filled" shades the area, "line" draws only the outline, "dots" adds a dot at every vertex. */
  variant?: "filled" | "line" | "dots"
  /** Shape of the background grid rings. */
  grid?: "polygon" | "circle" | "none"
  /** Show the category label at the end of each spoke. */
  showAngleLabels?: boolean
  /** Show value ticks along the vertical spoke. */
  showRadiusAxis?: boolean
  showLegend?: boolean
  showTooltip?: boolean
  /** Recharts domain for the value axis, e.g. [0, 100]. Defaults to [0, "auto"]. */
  domain?: React.ComponentProps<typeof PolarRadiusAxis>["domain"]
  valueFormatter?: (value: number) => string
}

/** A radar chart on shadcn's chart primitives: filled, outlined, or dotted, with one polygon per series. */
function RadarChart({
  data,
  angleKey,
  series,
  variant = "filled",
  grid = "polygon",
  showAngleLabels = true,
  showRadiusAxis = false,
  showLegend = false,
  showTooltip = true,
  domain,
  valueFormatter = (value) => formatNumber(value, { format: "compact" }),
  className,
  ...props
}: RadarChartProps) {
  const config = Object.fromEntries(
    series.map((s, index) => [
      s.key,
      { label: s.label, color: s.color ?? `var(--chart-${(index % 5) + 1})` },
    ])
  ) satisfies ChartConfig

  return (
    <ChartContainer
      data-slot="radar-chart"
      config={config}
      className={cn("aspect-auto h-64 w-full", className)}
      {...props}
    >
      <RechartsRadarChart data={data} margin={{ top: 8, right: 8, bottom: 8, left: 8 }}>
        {grid !== "none" ? <PolarGrid gridType={grid} /> : null}
        <PolarAngleAxis
          dataKey={angleKey}
          tickLine={false}
          axisLine={false}
          tick={showAngleLabels ? { fill: "var(--muted-foreground)" } : false}
        />
        <PolarRadiusAxis
          angle={90}
          domain={domain}
          axisLine={false}
          tick={showRadiusAxis ? { fill: "var(--muted-foreground)" } : false}
          tickFormatter={valueFormatter}
        />
        {showTooltip ? (
          <ChartTooltip
            cursor={false}
            content={
              <ChartTooltipContent
                indicator="dot"
                formatter={(value, name, item) => (
                  <div className="flex w-full items-center gap-2">
                    <span
                      className="size-2 shrink-0 rounded-[2px]"
                      style={{ backgroundColor: item.color }}
                    />
                    <span className="text-muted-foreground flex-1">
                      {config[name as string]?.label ?? name}
                    </span>
                    <span className="font-mono font-medium tabular-nums">
                      {valueFormatter(Number(value))}
                    </span>
                  </div>
                )}
              />
            }
          />
        ) : null}
        {showLegend ? <ChartLegend content={<ChartLegendContent />} /> : null}
        {series.map((s) => {
          const color = `var(--color-${s.key})`
          return (
            <Radar
              key={s.key}
              dataKey={s.key}
              stroke={color}
              strokeWidth={2}
              fill={color}
              fillOpacity={variant === "filled" ? 0.25 : 0}
              dot={variant === "dots" ? { r: 3, fill: color, strokeWidth: 0 } : false}
              activeDot={{ r: 4, fill: color, stroke: "var(--background)", strokeWidth: 2 }}
              isAnimationActive={false}
            />
          )
        })}
      </RechartsRadarChart>
    </ChartContainer>
  )
}

export { RadarChart }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Radial Gauge

A semicircular or ring gauge, continuous or segmented, with content in the middle.

A semicircular or ring gauge for a value out of a whole, continuous or segmented, with room for content in the middle. Use it for capacity, health scores, or progress toward a target.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/radial-gauge.json
```

## Usage

```tsx
import { RadialGauge } from "@/components/ui/radial-gauge"

<RadialGauge value={99.7} segments={40} size={180} thickness={12}>
  <span className="text-2xl font-semibold">99.7%</span>
  <span className="text-muted-foreground text-xs">Uptime</span>
</RadialGauge>
```

## Examples

### Default

```tsx
import { RadialGauge } from "@/components/ui/radial-gauge"

export default function RadialGaugeDemo() {
  return (
    <div className="flex flex-wrap items-end justify-center gap-10">
      <RadialGauge value={99.7} segments={40} size={180} thickness={12} color="var(--color-emerald-500)">
        <span className="text-2xl font-semibold tabular-nums">99.7%</span>
        <span className="text-muted-foreground text-xs">Uptime</span>
      </RadialGauge>
      <RadialGauge value={48} size={180} thickness={12}>
        <span className="text-2xl font-semibold tabular-nums">48%</span>
        <span className="text-muted-foreground text-xs">Coverage</span>
      </RadialGauge>
      <RadialGauge value={72} sweep={360} size={120} thickness={8} color="var(--chart-2)">
        <span className="text-lg font-semibold tabular-nums">72</span>
      </RadialGauge>
    </div>
  )
}
```

### Inline in a KPI card

A small segmented ring next to a value.

```tsx
import { Card, CardContent } from "@/components/ui/card"
import { DeltaBadge } from "@/components/ui/delta-badge"
import { RadialGauge } from "@/components/ui/radial-gauge"

const metrics = [
  { label: "API response time", value: "132 ms", pct: 66, delta: -0.108, invert: true },
  { label: "Error rate", value: "1.4 %", pct: 28, delta: 0.05, invert: true },
  { label: "Throughput", value: "4.3k req/s", pct: 86, delta: 0.1 },
]

export default function RadialGaugeInlineDemo() {
  return (
    <div className="grid w-full gap-4 sm:grid-cols-3">
      {metrics.map((m) => (
        <Card key={m.label} className="py-4">
          <CardContent className="flex flex-col gap-3 px-4">
            <span className="text-muted-foreground text-sm">{m.label}</span>
            <div className="flex items-center gap-3">
              <RadialGauge
                value={m.pct}
                sweep={360}
                size={36}
                thickness={4}
                segments={12}
                gap={6}
                color="var(--color-emerald-500)"
              />
              <span className="text-2xl font-semibold tabular-nums">{m.value}</span>
            </div>
            <DeltaBadge delta={m.delta} invert={m.invert} variant="text" />
          </CardContent>
        </Card>
      ))}
    </div>
  )
}
```

## Source

### components/ui/radial-gauge.tsx

```tsx
import * as React from "react"

import { cn } from "@/lib/utils"

export interface RadialGaugeProps extends React.ComponentProps<"div"> {
  value: number
  min?: number
  max?: number
  /** Diameter in pixels. */
  size?: number
  /** Stroke width in pixels. */
  thickness?: number
  /** Number of arc segments. 0 draws a continuous arc. */
  segments?: number
  /** Gap between segments in degrees. */
  gap?: number
  /** Angle where the arc starts, in degrees clockwise from 12 o'clock. */
  startAngle?: number
  /** Total sweep of the arc in degrees. 180 is a semicircle, 360 a ring. */
  sweep?: number
  /** Any CSS color. Defaults to chart-1. */
  color?: string
  trackColor?: string
  /** Content rendered in the middle of the gauge. */
  children?: React.ReactNode
}

// Round so server and client render identical path strings.
const round = (n: number) => Math.round(n * 1000) / 1000

function polar(cx: number, cy: number, r: number, angleDeg: number) {
  const rad = ((angleDeg - 90) * Math.PI) / 180
  return { x: round(cx + r * Math.cos(rad)), y: round(cy + r * Math.sin(rad)) }
}

function arcPath(cx: number, cy: number, r: number, from: number, to: number) {
  const start = polar(cx, cy, r, from)
  const end = polar(cx, cy, r, to)
  const largeArc = to - from > 180 ? 1 : 0
  return `M ${start.x} ${start.y} A ${r} ${r} 0 ${largeArc} 1 ${end.x} ${end.y}`
}

function RadialGauge({
  value,
  min = 0,
  max = 100,
  size = 160,
  thickness = 10,
  segments = 0,
  gap = 2,
  startAngle,
  sweep = 180,
  color = "var(--chart-1)",
  trackColor = "var(--muted)",
  className,
  children,
  ...props
}: RadialGaugeProps) {
  const fraction = Math.min(1, Math.max(0, (value - min) / (max - min || 1)))
  const start = startAngle ?? (sweep >= 360 ? 0 : -sweep / 2)
  const r = size / 2 - thickness / 2
  const cx = size / 2
  const cy = size / 2
  // Trim the box to the arc's vertical extent so a semicircle does not
  // reserve a full circle of space.
  const angles = Array.from({ length: 64 }, (_, i) => start + (sweep * i) / 63)
  const ys = angles.map((a) => polar(cx, cy, r, a).y)
  const top = Math.max(0, Math.min(...ys) - thickness / 2)
  const bottom = Math.min(size, Math.max(...ys) + thickness / 2)
  const height = bottom - top

  const arcs: { from: number; to: number; filled: boolean }[] = []
  if (segments > 0) {
    const step = sweep / segments
    for (let i = 0; i < segments; i++) {
      const from = start + i * step + gap / 2
      const to = start + (i + 1) * step - gap / 2
      const mid = (i + 0.5) / segments
      arcs.push({ from, to, filled: mid <= fraction })
    }
  }

  return (
    <div
      data-slot="radial-gauge"
      role="meter"
      aria-valuemin={min}
      aria-valuemax={max}
      aria-valuenow={value}
      className={cn("relative inline-flex shrink-0", className)}
      style={{ width: size, height }}
      {...props}
    >
      <svg
        width={size}
        height={height}
        viewBox={`0 ${top} ${size} ${height}`}
        className="absolute inset-0"
        aria-hidden="true"
      >
        {segments > 0 ? (
          arcs.map((arc, index) => (
            <path
              key={index}
              d={arcPath(cx, cy, r, arc.from, arc.to)}
              fill="none"
              stroke={arc.filled ? color : trackColor}
              strokeWidth={thickness}
              strokeLinecap="butt"
            />
          ))
        ) : (
          <>
            <path
              d={arcPath(cx, cy, r, start, start + sweep - (sweep >= 360 ? 0.01 : 0))}
              fill="none"
              stroke={trackColor}
              strokeWidth={thickness}
              strokeLinecap={sweep >= 360 ? "butt" : "round"}
            />
            {fraction > 0 ? (
              <path
                d={arcPath(cx, cy, r, start, start + sweep * fraction)}
                fill="none"
                stroke={color}
                strokeWidth={thickness}
                strokeLinecap="round"
                className="transition-[d] duration-500"
              />
            ) : null}
          </>
        )}
      </svg>
      {children ? (
        <div
          className={cn(
            "absolute inset-x-0 flex flex-col items-center justify-center text-center",
            sweep > 200 ? "inset-y-0" : "bottom-0"
          )}
        >
          {children}
        </div>
      ) : null}
    </div>
  )
}

export { RadialGauge }
```

# Sankey Chart

A flow diagram with tinted links, colored node bars, and share labels, on shadcn's chart primitives.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/sankey-chart.json
```

Also installs `chart` from shadcn/ui if missing.

npm dependencies: `recharts`.

## Usage

```tsx
import { SankeyChart } from "@/components/ui/sankey-chart"

<SankeyChart
  nodes={[
    { name: "Focus" },
    { name: "Meetings" },
    { name: "Writing" },
    { name: "Calls" },
  ]}
  links={[
    { source: "Focus", target: "Writing", value: 12 },
    { source: "Meetings", target: "Calls", value: 7 },
    { source: "Meetings", target: "Writing", value: 2 },
  ]}
  valueFormatter={(value) => `${value}h`}
/>
```

## Examples

### Default

```tsx
"use client"

import { SankeyChart } from "@/components/ui/sankey-chart"

// Sources carry a color; the activities on the right inherit it from their largest inflow.
const nodes = [
  { name: "Focus", color: "var(--color-violet-500)" },
  { name: "Meetings", color: "var(--color-sky-500)" },
  { name: "Breaks", color: "var(--color-lime-500)" },
  { name: "Admin", color: "var(--color-amber-500)" },
  { name: "Learning", color: "var(--color-pink-500)" },
  { name: "Browsing" },
  { name: "Writing" },
  { name: "Coding" },
  { name: "Calls" },
  { name: "Email" },
  { name: "Reading" },
  { name: "Planning" },
]

// Hours per week, sources on the left flowing into activities on the right.
const links = [
  { source: "Focus", target: "Coding", value: 8 },
  { source: "Focus", target: "Writing", value: 7 },
  { source: "Focus", target: "Browsing", value: 3 },
  { source: "Focus", target: "Planning", value: 2 },
  { source: "Meetings", target: "Calls", value: 7 },
  { source: "Meetings", target: "Planning", value: 2 },
  { source: "Meetings", target: "Email", value: 1 },
  { source: "Breaks", target: "Browsing", value: 5 },
  { source: "Breaks", target: "Reading", value: 1 },
  { source: "Admin", target: "Email", value: 5 },
  { source: "Admin", target: "Browsing", value: 2 },
  { source: "Admin", target: "Writing", value: 1 },
  { source: "Learning", target: "Reading", value: 4 },
  { source: "Learning", target: "Browsing", value: 1 },
  { source: "Learning", target: "Writing", value: 1 },
]

export default function SankeyChartDemo() {
  return (
    <div className="w-full max-w-lg">
      <SankeyChart nodes={nodes} links={links} valueFormatter={(value) => `${value}h`} />
    </div>
  )
}
```

### Cash flow

Income sources flowing into budget categories, with a currency formatter.

```tsx
"use client"

import { SankeyChart } from "@/components/ui/sankey-chart"
import { formatNumber } from "@/lib/format"

const nodes = [
  { name: "Salary" },
  { name: "Freelance" },
  { name: "Dividends" },
  { name: "Housing" },
  { name: "Savings" },
  { name: "Leisure" },
  { name: "Groceries" },
  { name: "Insurance" },
  { name: "Transport" },
  { name: "Utilities" },
]

// Monthly cash flow, income on the left and budget categories on the right.
const links = [
  { source: "Salary", target: "Housing", value: 2400 },
  { source: "Salary", target: "Savings", value: 1200 },
  { source: "Salary", target: "Groceries", value: 900 },
  { source: "Salary", target: "Transport", value: 600 },
  { source: "Salary", target: "Utilities", value: 500 },
  { source: "Salary", target: "Insurance", value: 600 },
  { source: "Freelance", target: "Leisure", value: 1100 },
  { source: "Freelance", target: "Savings", value: 500 },
  { source: "Freelance", target: "Insurance", value: 200 },
  { source: "Dividends", target: "Savings", value: 200 },
  { source: "Dividends", target: "Leisure", value: 200 },
]

export default function SankeyChartCashflowDemo() {
  return (
    <div className="w-full max-w-lg">
      <SankeyChart
        nodes={nodes}
        links={links}
        valueFormatter={(value) =>
          formatNumber(value, { format: "currency", maximumFractionDigits: 0 })
        }
        nodePadding={12}
      />
    </div>
  )
}
```

## Source

### components/ui/sankey-chart.tsx

```tsx
"use client"

import * as React from "react"
import {
  Sankey,
  type SankeyLinkProps,
  type SankeyNode as RechartsSankeyNode,
  type SankeyNodeProps,
} from "recharts"

import { cn } from "@/lib/utils"
import { formatNumber } from "@/lib/format"
import {
  ChartContainer,
  ChartTooltip,
  ChartTooltipContent,
  type ChartConfig,
} from "@/components/ui/chart"

export interface SankeyChartNode {
  name: string
  /** Any CSS color. Sources default to the palette in order; targets inherit the color of their largest incoming link. */
  color?: string
}

export interface SankeyChartLink {
  /** Node name or index into `nodes`. */
  source: number | string
  /** Node name or index into `nodes`. */
  target: number | string
  value: number
}

export interface SankeyChartProps
  extends Omit<React.ComponentProps<typeof ChartContainer>, "config" | "children"> {
  nodes: SankeyChartNode[]
  links: SankeyChartLink[]
  valueFormatter?: (value: number) => string
  /** Append each node's share of the total flow to its label, e.g. "Writing · 18%". */
  showShares?: boolean
  showTooltip?: boolean
  nodeWidth?: number
  /** Vertical gap between nodes in the same column. */
  nodePadding?: number
  /** Fill opacity of the links. Hovered links are drawn at double this, up to 1. */
  linkOpacity?: number
  /** "outside" reserves a margin and puts labels left of sources and right of targets; "inside" draws them over the flow. */
  labelPosition?: "outside" | "inside"
  /** Palette cycled through source nodes without a color. Defaults to chart-1 through chart-5. */
  colors?: string[]
}

const DEFAULT_COLORS = [
  "var(--chart-1)",
  "var(--chart-2)",
  "var(--chart-3)",
  "var(--chart-4)",
  "var(--chart-5)",
]

/** Approximate rendered width of a text-xs string, for reserving label margins. */
const CHAR_WIDTH = 6.4
const LABEL_GAP = 8

interface ResolvedNode {
  name: string
  color: string
  /** Share of the total flow, as a fraction. */
  share: number
  /** Which side of the node bar the label is drawn on. */
  side: "left" | "right"
  /** Label text next to the node, share included. */
  label: string
  shareLabel: string
}

interface ResolvedLink {
  source: number
  target: number
  value: number
}

function round(n: number) {
  return Math.round(n * 1000) / 1000
}

function slugify(name: string) {
  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-")
}

function SankeyChart({
  nodes,
  links,
  valueFormatter = (value) => formatNumber(value),
  showShares = true,
  showTooltip = true,
  nodeWidth = 12,
  nodePadding = 16,
  linkOpacity = 0.25,
  labelPosition = "outside",
  colors = DEFAULT_COLORS,
  className,
  ...props
}: SankeyChartProps) {
  const palette = colors.length ? colors : DEFAULT_COLORS
  const hoverOpacity = Math.min(1, linkOpacity * 2)

  const { data, margin, config } = React.useMemo(() => {
    const indexByName = new Map(nodes.map((node, index) => [node.name, index]))
    const resolveIndex = (ref: number | string) =>
      typeof ref === "number"
        ? Number.isInteger(ref) && ref >= 0 && ref < nodes.length
          ? ref
          : -1
        : (indexByName.get(ref) ?? -1)

    const resolvedLinks: ResolvedLink[] = links
      .map((link) => ({
        source: resolveIndex(link.source),
        target: resolveIndex(link.target),
        value: link.value,
      }))
      .filter(
        (link) =>
          link.source >= 0 &&
          link.target >= 0 &&
          link.source !== link.target &&
          Number.isFinite(link.value) &&
          link.value > 0
      )

    const incoming = nodes.map(() => 0)
    const outgoing = nodes.map(() => 0)
    const strongestSource = nodes.map<number | null>(() => null)
    const strongestValue = nodes.map(() => 0)
    for (const link of resolvedLinks) {
      outgoing[link.source]! += link.value
      incoming[link.target]! += link.value
      if (link.value > strongestValue[link.target]!) {
        strongestValue[link.target] = link.value
        strongestSource[link.target] = link.source
      }
    }

    const isRoot = nodes.map((_, index) => incoming[index] === 0)
    const isLeaf = nodes.map((_, index) => outgoing[index] === 0)
    const values = nodes.map((_, index) => Math.max(incoming[index]!, outgoing[index]!))
    const total = values.reduce((sum, value, index) => (isRoot[index] ? sum + value : sum), 0)

    // Roots cycle through the palette; everything else inherits its strongest source.
    const resolvedColors: (string | undefined)[] = nodes.map(() => undefined)
    let paletteIndex = 0
    nodes.forEach((node, index) => {
      if (node.color) resolvedColors[index] = node.color
      else if (isRoot[index]) resolvedColors[index] = palette[paletteIndex++ % palette.length]
    })
    const colorOf = (index: number, seen: Set<number>): string => {
      const known = resolvedColors[index]
      if (known) return known
      const source = strongestSource[index] ?? null
      if (source !== null && !seen.has(index)) {
        seen.add(index)
        const inherited = colorOf(source, seen)
        resolvedColors[index] = inherited
        return inherited
      }
      const fallback = palette[paletteIndex++ % palette.length]!
      resolvedColors[index] = fallback
      return fallback
    }

    const resolvedNodes: ResolvedNode[] = nodes.map((node, index) => {
      const share = total > 0 ? values[index]! / total : 0
      const shareLabel = showShares
        ? ` · ${formatNumber(share, { format: "percent", maximumFractionDigits: 0 })}`
        : ""
      const side: ResolvedNode["side"] =
        labelPosition === "outside"
          ? isRoot[index] && !isLeaf[index]
            ? "left"
            : "right"
          : isLeaf[index] && !isRoot[index]
            ? "left"
            : "right"
      return {
        name: node.name,
        color: colorOf(index, new Set()),
        share,
        side,
        label: node.name,
        shareLabel,
      }
    })

    const labelWidth = (node: ResolvedNode) =>
      Math.ceil((node.label.length + node.shareLabel.length) * CHAR_WIDTH) + LABEL_GAP
    const widest = (predicate: (index: number) => boolean) =>
      resolvedNodes.reduce(
        (max, node, index) =>
          predicate(index) && values[index]! > 0 ? Math.max(max, labelWidth(node)) : max,
        0
      )
    const margin =
      labelPosition === "outside"
        ? {
            top: 4,
            bottom: 4,
            left: widest((index) => resolvedNodes[index]!.side === "left"),
            right: widest((index) => resolvedNodes[index]!.side === "right"),
          }
        : { top: 4, bottom: 4, left: 4, right: 4 }

    const config = Object.fromEntries(
      resolvedNodes.map((node) => [slugify(node.name), { label: node.name, color: node.color }])
    ) satisfies ChartConfig

    return { data: { nodes: resolvedNodes, links: resolvedLinks }, margin, config }
  }, [nodes, links, palette, showShares, labelPosition])

  const renderNode = React.useCallback((props: SankeyNodeProps) => {
    const { x, y, width, height, payload } = props
    const node = payload as unknown as RechartsSankeyNode & ResolvedNode
    if (!(node.value > 0) || !(height > 0)) return null
    const radius = Math.min(3, width / 2, height / 2)
    const labelX = node.side === "left" ? x - LABEL_GAP : x + width + LABEL_GAP
    return (
      <g data-slot="sankey-node">
        <rect
          x={round(x)}
          y={round(y)}
          width={round(width)}
          height={round(height)}
          rx={round(radius)}
          fill={node.color}
        />
        <text
          x={round(labelX)}
          y={round(y + height / 2)}
          textAnchor={node.side === "left" ? "end" : "start"}
          dominantBaseline="middle"
          className="fill-foreground text-xs"
        >
          <tspan className="font-medium">{node.label}</tspan>
          {node.shareLabel ? (
            <tspan className="fill-muted-foreground tabular-nums">{node.shareLabel}</tspan>
          ) : null}
        </text>
      </g>
    )
  }, [])

  const renderLink = React.useCallback(
    (props: SankeyLinkProps) => {
      const {
        sourceX,
        sourceY,
        sourceControlX,
        targetX,
        targetY,
        targetControlX,
        linkWidth,
        payload,
      } = props
      const source = payload.source as RechartsSankeyNode & ResolvedNode
      const half = Math.max(linkWidth, 0.5) / 2
      const top = (yValue: number) => round(yValue - half)
      const bottom = (yValue: number) => round(yValue + half)
      const d = [
        `M${round(sourceX)},${top(sourceY)}`,
        `C${round(sourceControlX)},${top(sourceY)} ${round(targetControlX)},${top(targetY)} ${round(targetX)},${top(targetY)}`,
        `L${round(targetX)},${bottom(targetY)}`,
        `C${round(targetControlX)},${bottom(targetY)} ${round(sourceControlX)},${bottom(sourceY)} ${round(sourceX)},${bottom(sourceY)}`,
        "Z",
      ].join(" ")
      return (
        <path
          data-slot="sankey-link"
          d={d}
          fill={source.color}
          fillOpacity={linkOpacity}
          stroke="none"
          className="transition-[fill-opacity] duration-150 hover:[fill-opacity:var(--sankey-link-hover-opacity)]"
          style={{ "--sankey-link-hover-opacity": hoverOpacity } as React.CSSProperties}
        />
      )
    },
    [linkOpacity, hoverOpacity]
  )

  return (
    <ChartContainer
      data-slot="sankey-chart"
      config={config}
      className={cn("aspect-auto h-72 w-full", className)}
      {...props}
    >
      <Sankey
        data={data}
        nodeWidth={nodeWidth}
        nodePadding={nodePadding}
        linkCurvature={0.5}
        margin={margin}
        node={renderNode}
        link={renderLink}
      >
        {showTooltip ? (
          <ChartTooltip
            cursor={false}
            content={
              <ChartTooltipContent
                hideLabel
                formatter={(value, name, item) => {
                  // Links carry resolved source/target nodes; nodes carry their own meta.
                  const raw = item.payload as Record<string, unknown> | undefined
                  const source = raw?.source as (RechartsSankeyNode & ResolvedNode) | undefined
                  const target = raw?.target as (RechartsSankeyNode & ResolvedNode) | undefined
                  const isLink = typeof source === "object" && typeof target === "object"
                  const label = isLink
                    ? `${source.name} → ${target.name}`
                    : String(raw?.name ?? name)
                  const color = isLink ? source.color : (raw?.color as string | undefined)
                  return (
                    <div className="flex w-full items-center gap-2">
                      <span
                        className="size-2 shrink-0 rounded-[2px]"
                        style={{ backgroundColor: color }}
                      />
                      <span className="text-muted-foreground flex-1">{label}</span>
                      <span className="font-mono font-medium tabular-nums">
                        {valueFormatter(Number(value))}
                      </span>
                    </div>
                  )
                }}
              />
            }
          />
        ) : null}
      </Sankey>
    </ChartContainer>
  )
}

export { SankeyChart }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Scatter Chart

Correlation dots per series that become bubbles when a size key is set, with a per-point tooltip and legend.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/scatter-chart.json
```

Also installs `chart` from shadcn/ui if missing.

npm dependencies: `recharts`.

## Usage

```tsx
import { ScatterChart } from "@/components/ui/scatter-chart"

<ScatterChart
  series={[
    { label: "Free", data: free },
    { label: "Pro", data: pro },
    { label: "Enterprise", data: enterprise },
  ]}
  xKey="sessions"
  yKey="revenue"
  xLabel="Sessions"
  yLabel="Revenue"
  showLegend
/>
```

## Examples

### Default

```tsx
"use client"

import { ScatterChart } from "@/components/ui/scatter-chart"
import { formatNumber } from "@/lib/format"

const free = [
  { sessions: 12, revenue: 0 },
  { sessions: 28, revenue: 0 },
  { sessions: 41, revenue: 19 },
  { sessions: 55, revenue: 0 },
  { sessions: 63, revenue: 29 },
  { sessions: 78, revenue: 49 },
  { sessions: 94, revenue: 19 },
  { sessions: 110, revenue: 79 },
]

const pro = [
  { sessions: 68, revenue: 240 },
  { sessions: 95, revenue: 310 },
  { sessions: 132, revenue: 420 },
  { sessions: 148, revenue: 380 },
  { sessions: 176, revenue: 560 },
  { sessions: 203, revenue: 610 },
  { sessions: 231, revenue: 720 },
  { sessions: 258, revenue: 690 },
]

const enterprise = [
  { sessions: 210, revenue: 1_450 },
  { sessions: 265, revenue: 1_820 },
  { sessions: 302, revenue: 1_690 },
  { sessions: 348, revenue: 2_310 },
  { sessions: 390, revenue: 2_640 },
  { sessions: 415, revenue: 2_480 },
]

export default function ScatterChartDemo() {
  return (
    <div className="w-full max-w-lg">
      <ScatterChart
        series={[
          { label: "Free", data: free },
          { label: "Pro", data: pro },
          { label: "Enterprise", data: enterprise },
        ]}
        xKey="sessions"
        yKey="revenue"
        xLabel="Sessions"
        yLabel="Revenue"
        xFormatter={(v) => formatNumber(v)}
        yFormatter={(v) => formatNumber(v, { format: "currency", compact: true })}
        showLegend
      />
    </div>
  )
}
```

### Bubbles

Set sizeKey to scale each point by a third value, and nameKey to title the tooltip with the point's label.

```tsx
"use client"

import { ScatterChart } from "@/components/ui/scatter-chart"
import { formatNumber } from "@/lib/format"

const paid = [
  { channel: "Search ads", spend: 18_400, conversions: 620, reach: 410_000 },
  { channel: "Social ads", spend: 12_900, conversions: 380, reach: 860_000 },
  { channel: "Display", spend: 7_200, conversions: 140, reach: 1_250_000 },
  { channel: "Sponsorships", spend: 9_800, conversions: 210, reach: 320_000 },
  { channel: "Retargeting", spend: 4_600, conversions: 290, reach: 95_000 },
]

const organic = [
  { channel: "SEO", spend: 3_200, conversions: 540, reach: 720_000 },
  { channel: "Newsletter", spend: 1_100, conversions: 260, reach: 48_000 },
  { channel: "Referrals", spend: 600, conversions: 180, reach: 22_000 },
  { channel: "Community", spend: 2_400, conversions: 150, reach: 130_000 },
]

export default function ScatterChartBubblesDemo() {
  return (
    <div className="w-full max-w-lg">
      <ScatterChart
        series={[
          { label: "Paid", data: paid },
          { label: "Organic", data: organic },
        ]}
        xKey="spend"
        yKey="conversions"
        sizeKey="reach"
        nameKey="channel"
        xLabel="Spend"
        yLabel="Conversions"
        sizeLabel="Reach"
        xFormatter={(v) => formatNumber(v, { format: "currency", compact: true })}
        yFormatter={(v) => formatNumber(v)}
        showLegend
      />
    </div>
  )
}
```

## Source

### components/ui/scatter-chart.tsx

```tsx
"use client"

import * as React from "react"
import {
  CartesianGrid,
  Scatter,
  ScatterChart as RechartsScatterChart,
  XAxis,
  YAxis,
  ZAxis,
} from "recharts"

import { cn } from "@/lib/utils"
import { formatNumber } from "@/lib/format"
import {
  ChartContainer,
  ChartLegend,
  ChartLegendContent,
  ChartTooltip,
  ChartTooltipContent,
  type ChartConfig,
} from "@/components/ui/chart"

export interface ScatterSeries {
  /** Stable identifier. Defaults to a slug of the label. */
  key?: string
  label: string
  /** Rows for this series. Each needs the x and y keys, plus the size and name keys when set. */
  data: Record<string, unknown>[]
  /** Any CSS color. Defaults to chart-1 through chart-5 in order. */
  color?: string
}

export interface ScatterChartProps
  extends Omit<React.ComponentProps<typeof ChartContainer>, "config" | "children"> {
  series: ScatterSeries[]
  /** Key of the x value in each row. */
  xKey: string
  /** Key of the y value in each row. */
  yKey: string
  /** Key of a value that scales each point into a bubble. */
  sizeKey?: string
  /** Key of a per-point label shown as the tooltip title. */
  nameKey?: string
  /** Names for the tooltip rows. Default to the keys. */
  xLabel?: string
  yLabel?: string
  sizeLabel?: string
  showGrid?: boolean
  showXAxis?: boolean
  showYAxis?: boolean
  showLegend?: boolean
  showTooltip?: boolean
  xFormatter?: (value: number) => string
  yFormatter?: (value: number) => string
  sizeFormatter?: (value: number) => string
  /** Radius of each point in px when sizeKey is not set. */
  dotRadius?: number
  /** Bubble area range in px² when sizeKey is set, smallest to largest. */
  sizeRange?: [number, number]
  /** Recharts domain for the x-axis, e.g. ["auto", "auto"]. Defaults to [0, "auto"]. */
  xDomain?: React.ComponentProps<typeof XAxis>["domain"]
  /** Recharts domain for the y-axis, e.g. ["auto", "auto"]. Defaults to [0, "auto"]. */
  yDomain?: React.ComponentProps<typeof YAxis>["domain"]
}

/** Hidden key stamped onto each row so the tooltip can find the point's series. */
const SERIES_KEY = "__scatterSeries"

function slug(label: string) {
  return label.toLowerCase().replace(/[^a-z0-9]+/g, "-")
}

interface ScatterTooltipContentProps
  extends Pick<React.ComponentProps<typeof ChartTooltipContent>, "active" | "payload"> {
  config: ChartConfig
  rows: { key: string; label: string; format: (value: number) => string }[]
  nameKey?: string
}

function ScatterTooltipContent({
  active,
  payload,
  config,
  rows,
  nameKey,
}: ScatterTooltipContentProps) {
  const point = payload?.[0]?.payload as Record<string, unknown> | undefined
  if (!active || !point) return null
  const seriesKey = String(point[SERIES_KEY] ?? "")
  const seriesLabel = config[seriesKey]?.label ?? seriesKey
  const name = nameKey ? point[nameKey] : undefined
  const title = name != null ? String(name) : seriesLabel

  return (
    <div className="grid min-w-[8rem] gap-1.5 rounded-lg border border-border/50 bg-background px-2.5 py-1.5 text-xs shadow-xl">
      <div className="flex items-center gap-2 font-medium">
        <span
          className="size-2 shrink-0 rounded-[2px]"
          style={{ backgroundColor: `var(--color-${seriesKey})` }}
        />
        <span className="flex-1">{title}</span>
        {name != null ? (
          <span className="text-muted-foreground font-normal">{seriesLabel}</span>
        ) : null}
      </div>
      <div className="grid gap-1">
        {rows.map((row) => (
          <div key={row.key} className="flex items-center justify-between gap-4">
            <span className="text-muted-foreground">{row.label}</span>
            <span className="font-mono font-medium tabular-nums">
              {row.format(Number(point[row.key]))}
            </span>
          </div>
        ))}
      </div>
    </div>
  )
}

/** A scatter chart on shadcn's chart primitives: correlation dots per series, or bubbles when a size key is set. */
function ScatterChart({
  series,
  xKey,
  yKey,
  sizeKey,
  nameKey,
  xLabel,
  yLabel,
  sizeLabel,
  showGrid = true,
  showXAxis = true,
  showYAxis = true,
  showLegend = false,
  showTooltip = true,
  xFormatter = (value) => formatNumber(value, { format: "compact" }),
  yFormatter = (value) => formatNumber(value, { format: "compact" }),
  sizeFormatter = (value) => formatNumber(value, { format: "compact" }),
  dotRadius = 4,
  sizeRange = [40, 400],
  xDomain,
  yDomain,
  className,
  ...props
}: ScatterChartProps) {
  const resolved = React.useMemo(
    () =>
      series.map((s, index) => {
        const key = s.key ?? slug(s.label)
        return {
          key,
          label: s.label,
          color: s.color ?? `var(--chart-${(index % 5) + 1})`,
          data: s.data.map((row) => ({ ...row, [SERIES_KEY]: key })),
        }
      }),
    [series]
  )
  const config = Object.fromEntries(
    resolved.map((s) => [s.key, { label: s.label, color: s.color }])
  ) satisfies ChartConfig
  const rows = [
    { key: xKey, label: xLabel ?? xKey, format: xFormatter },
    { key: yKey, label: yLabel ?? yKey, format: yFormatter },
    ...(sizeKey ? [{ key: sizeKey, label: sizeLabel ?? sizeKey, format: sizeFormatter }] : []),
  ]
  // Recharts sizes symbols by area, so a fixed radius becomes a fixed area.
  const dotArea = Math.round(Math.PI * dotRadius * dotRadius)

  return (
    <ChartContainer
      data-slot="scatter-chart"
      config={config}
      className={cn("aspect-auto h-64 w-full", className)}
      {...props}
    >
      <RechartsScatterChart margin={{ top: 12, right: 12, bottom: 0, left: showYAxis ? 0 : 8 }}>
        {showGrid ? <CartesianGrid /> : null}
        <XAxis
          type="number"
          dataKey={xKey}
          hide={!showXAxis}
          domain={xDomain}
          tickLine={false}
          axisLine={false}
          tickMargin={8}
          tickFormatter={xFormatter}
        />
        <YAxis
          type="number"
          dataKey={yKey}
          hide={!showYAxis}
          domain={yDomain}
          tickLine={false}
          axisLine={false}
          tickMargin={8}
          width="auto"
          tickFormatter={yFormatter}
        />
        {sizeKey ? (
          <ZAxis type="number" dataKey={sizeKey} range={sizeRange} />
        ) : (
          <ZAxis type="number" range={[dotArea, dotArea]} />
        )}
        {showTooltip ? (
          <ChartTooltip
            cursor={false}
            content={<ScatterTooltipContent config={config} rows={rows} nameKey={nameKey} />}
          />
        ) : null}
        {showLegend ? <ChartLegend content={<ChartLegendContent />} /> : null}
        {resolved.map((s) => {
          const color = `var(--color-${s.key})`
          return (
            <Scatter
              key={s.key}
              name={s.key}
              data={s.data}
              fill={color}
              fillOpacity={0.35}
              stroke={color}
              strokeWidth={1.5}
              isAnimationActive={false}
            />
          )
        })}
      </RechartsScatterChart>
    </ChartContainer>
  )
}

export { ScatterChart }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Segmented Meter

A zoned bar meter with a marker at the current value, for heart-rate zones, allocations, or thresholds.

A bar meter split into zones with a marker at the current value, for heart-rate zones, portfolio allocations, or thresholds where the zone a value falls in matters more than the number.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/segmented-meter.json
```

## Usage

```tsx
import { SegmentedMeter } from "@/components/ui/segmented-meter"

<SegmentedMeter
  value={142}
  zones={[
    { label: "Rest", from: 60, to: 110 },
    { label: "Fat burn", from: 110, to: 140 },
    { label: "Cardio", from: 140, to: 170 },
    { label: "Peak", from: 170, to: 190 },
  ]}
/>
```

## Examples

### Default

```tsx
"use client"

import { SegmentedMeter } from "@/components/ui/segmented-meter"

const zones = [
  { label: "Rest", from: 60, to: 110, color: "var(--color-sky-500)" },
  { label: "Fat burn", from: 110, to: 140, color: "var(--color-emerald-500)" },
  { label: "Cardio", from: 140, to: 170, color: "var(--color-amber-500)" },
  { label: "Peak", from: 170, to: 190, color: "var(--color-red-500)" },
]

export default function SegmentedMeterDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-8">
      <div className="flex flex-col gap-3">
        <div className="flex items-baseline gap-1.5">
          <span className="text-3xl font-semibold tabular-nums">142</span>
          <span className="text-muted-foreground">bpm</span>
        </div>
        <span className="text-sm font-medium">Heart rate zone</span>
        <SegmentedMeter value={142} zones={zones} tickFormatter={(v) => `${v}bpm`} />
      </div>
      <div className="flex flex-col gap-3">
        <span className="text-sm font-medium">All zones, with labels</span>
        <SegmentedMeter
          value={142}
          zones={zones}
          highlightActive={false}
          showTicks={false}
          showLabels
        />
      </div>
    </div>
  )
}
```

## Source

### components/ui/segmented-meter.tsx

```tsx
import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber } from "@/lib/format"

export interface MeterZone {
  label?: string
  from: number
  to: number
  /** Any CSS color. Defaults to chart-1. */
  color?: string
}

export interface SegmentedMeterProps extends React.ComponentProps<"div"> {
  value: number
  zones: MeterZone[]
  /** Only color the zone that contains the value; others stay muted. */
  highlightActive?: boolean
  /** Show zone boundary values under the bar. */
  showTicks?: boolean
  /** Show zone labels under the bar. */
  showLabels?: boolean
  /** Show a marker at the current value. */
  showMarker?: boolean
  tickFormatter?: (value: number) => string
}

function SegmentedMeter({
  value,
  zones,
  highlightActive = true,
  showTicks = true,
  showLabels = false,
  showMarker = true,
  tickFormatter = (v) => formatNumber(v),
  className,
  ...props
}: SegmentedMeterProps) {
  const min = Math.min(...zones.map((z) => z.from))
  const max = Math.max(...zones.map((z) => z.to))
  const span = max - min || 1
  const position = Math.min(1, Math.max(0, (value - min) / span))
  const activeIndex = zones.findIndex(
    (z, i) => value >= z.from && (value < z.to || (i === zones.length - 1 && value <= z.to))
  )

  return (
    <div
      data-slot="segmented-meter"
      role="meter"
      aria-valuemin={min}
      aria-valuemax={max}
      aria-valuenow={value}
      className={cn("flex flex-col gap-1.5", className)}
      {...props}
    >
      <div className="relative">
        <div className="flex h-2 w-full gap-0.5">
          {zones.map((zone, index) => {
            const active = index === activeIndex
            const color = zone.color ?? "var(--chart-1)"
            return (
              <div
                key={index}
                data-active={active}
                className="bg-muted h-full rounded-sm transition-colors first:rounded-l-full last:rounded-r-full"
                style={{
                  width: `${((zone.to - zone.from) / span) * 100}%`,
                  backgroundColor: !highlightActive || active ? color : undefined,
                }}
              />
            )
          })}
        </div>
        {showMarker ? (
          <div
            aria-hidden="true"
            className="bg-foreground ring-background absolute top-1/2 size-3 -translate-x-1/2 -translate-y-1/2 rounded-full ring-2"
            style={{ left: `${position * 100}%` }}
          />
        ) : null}
      </div>
      {showTicks || showLabels ? (
        <div className="text-muted-foreground relative h-4 text-[10px] tabular-nums">
          {showTicks
            ? [min, ...zones.map((z) => z.to)].map((tick, index, all) => (
                <span
                  key={index}
                  className={cn(
                    "absolute top-0",
                    index === 0 && "left-0",
                    index === all.length - 1 && "right-0",
                    index > 0 && index < all.length - 1 && "-translate-x-1/2"
                  )}
                  style={
                    index > 0 && index < all.length - 1
                      ? { left: `${((tick - min) / span) * 100}%` }
                      : undefined
                  }
                >
                  {tickFormatter(tick)}
                </span>
              ))
            : zones.map((zone, index) => (
                <span
                  key={index}
                  className="absolute top-0 -translate-x-1/2 truncate"
                  style={{
                    left: `${(((zone.from + zone.to) / 2 - min) / span) * 100}%`,
                  }}
                >
                  {zone.label}
                </span>
              ))}
        </div>
      ) : null}
    </div>
  )
}

export { SegmentedMeter }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Sparkline

A tiny inline area or line chart for showing a trend at a glance.

A tiny inline area or line chart with no axes, for showing a trend next to a number. It is what the KPI card and metric list use, and it is small enough to drop into a table cell.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/sparkline.json
```

npm dependencies: `recharts`.

## Usage

```tsx
import { Sparkline } from "@/components/ui/sparkline"

<Sparkline data={[12, 18, 14, 22, 26, 21, 30]} className="h-8 w-24" />
```

## Examples

### Default

Set fill to "dots" to render the area as a dot grid that fades out toward the line.

```tsx
import { Sparkline } from "@/components/ui/sparkline"

const data = [12, 18, 14, 22, 26, 21, 30, 34, 28, 40, 44, 52]

export default function SparklineDemo() {
  return (
    <div className="grid w-full max-w-md gap-6">
      <div className="flex flex-col gap-1.5">
        <span className="text-muted-foreground text-xs">Area</span>
        <Sparkline data={data} className="h-12" />
      </div>
      <div className="flex flex-col gap-1.5">
        <span className="text-muted-foreground text-xs">Line</span>
        <Sparkline data={data} variant="line" className="h-12" />
      </div>
      <div className="flex flex-col gap-1.5">
        <span className="text-muted-foreground text-xs">Dot grid</span>
        <Sparkline data={data} fill="dots" color="var(--chart-1)" className="h-12" />
      </div>
      <div className="flex flex-col gap-1.5">
        <span className="text-muted-foreground text-xs">Custom color, step curve</span>
        <Sparkline
          data={data}
          curve="step"
          color="var(--chart-2)"
          className="h-12"
        />
      </div>
    </div>
  )
}
```

## Source

### components/ui/sparkline.tsx

```tsx
"use client"

import * as React from "react"
import {
  Area,
  AreaChart,
  AreaRevealShape,
  Line,
  LineChart,
  ResponsiveContainer,
  type AreaRevealShapeProps,
} from "recharts"

import { cn } from "@/lib/utils"

export interface SparklineProps extends React.ComponentProps<"div"> {
  /** Series to plot, oldest first. */
  data: number[]
  variant?: "area" | "line"
  /** Area fill: a plain gradient, or a dot grid that fades out toward the line. */
  fill?: "gradient" | "dots"
  /** Any CSS color. Defaults to the theme primary. */
  color?: string
  curve?: "monotone" | "linear" | "step"
  strokeWidth?: number
}

/** Area shape that masks the fill to a dot grid while keeping the stroke solid. */
function DotGridAreaShape({
  maskId,
  ...props
}: AreaRevealShapeProps & { maskId: string }) {
  return (
    <>
      <g mask={`url(#${maskId})`}>
        <AreaRevealShape {...props} stroke="none" />
      </g>
      <AreaRevealShape {...props} id={undefined} fill="none" />
    </>
  )
}

function Sparkline({
  data,
  variant = "area",
  fill = "gradient",
  color = "var(--primary)",
  curve = "monotone",
  strokeWidth = 1.5,
  className,
  ...props
}: SparklineProps) {
  const id = React.useId()
  const dots = variant === "area" && fill === "dots"
  const points = React.useMemo(() => data.map((y, i) => ({ i, y })), [data])
  const margin = { top: 2, right: 0, bottom: 0, left: 0 }

  return (
    <div
      data-slot="sparkline"
      aria-hidden="true"
      className={cn("h-10 w-full", className)}
      {...props}
    >
      <ResponsiveContainer width="100%" height="100%">
        {variant === "line" ? (
          <LineChart data={points} margin={margin}>
            <Line
              type={curve}
              dataKey="y"
              stroke={color}
              strokeWidth={strokeWidth}
              dot={false}
              isAnimationActive={false}
            />
          </LineChart>
        ) : (
          <AreaChart data={points} margin={margin}>
            <defs>
              <linearGradient id={id} x1="0" y1="0" x2="0" y2="1">
                <stop offset="0%" stopColor={color} stopOpacity={dots ? 0.08 : 0.3} />
                <stop offset="100%" stopColor={color} stopOpacity={dots ? 0.9 : 0} />
              </linearGradient>
              {dots ? (
                <>
                  <pattern
                    id={`${id}-dots`}
                    patternUnits="userSpaceOnUse"
                    width={4}
                    height={4}
                  >
                    <circle cx={2} cy={2} r={0.9} fill="#fff" />
                  </pattern>
                  <mask
                    id={`${id}-mask`}
                    maskUnits="userSpaceOnUse"
                    x={0}
                    y={0}
                    width="100%"
                    height="100%"
                  >
                    <rect width="100%" height="100%" fill={`url(#${id}-dots)`} />
                  </mask>
                </>
              ) : null}
            </defs>
            <Area
              type={curve}
              dataKey="y"
              stroke={color}
              strokeWidth={strokeWidth}
              fill={`url(#${id})`}
              fillOpacity={dots ? 1 : undefined}
              dot={false}
              isAnimationActive={false}
              shape={
                dots
                  ? (shapeProps: AreaRevealShapeProps) => (
                      <DotGridAreaShape {...shapeProps} maskId={`${id}-mask`} />
                    )
                  : undefined
              }
            />
          </AreaChart>
        )}
      </ResponsiveContainer>
    </div>
  )
}

export { Sparkline }
```

# Tick Bar

A progress bar drawn as a row of ticks, lit up to the current value.

A progress bar drawn as a row of ticks lit up to the current value, for a more graphic take on progress toward a goal. Used by several of the KPI blocks.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/tick-bar.json
```

## Usage

```tsx
import { TickBar } from "@/components/ui/tick-bar"

<TickBar value={46} color="var(--color-emerald-500)" />
<TickBar value={7420} max={12300} segments={40} />
<TickBar value={16} max={24} segments={24} shape="pill" />
```

## Examples

### Default

```tsx
import { TickBar } from "@/components/ui/tick-bar"

export default function TickBarDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-6">
      <TickBar value={46} color="var(--color-emerald-500)" />
      <TickBar value={7_420} max={12_300} color="var(--color-violet-500)" />
      <TickBar value={16} max={24} segments={24} shape="pill" color="var(--foreground)" />
    </div>
  )
}
```

## Source

### components/ui/tick-bar.tsx

```tsx
import * as React from "react"

import { cn } from "@/lib/utils"

export interface TickBarProps extends React.ComponentProps<"div"> {
  /** Current value, from 0 to max. */
  value: number
  max?: number
  /** Number of ticks. */
  segments?: number
  /** Any CSS color for the filled ticks. Defaults to chart-1. */
  color?: string
  /** Any CSS color for the unfilled ticks. Defaults to muted. */
  trackColor?: string
  /** "tick" draws thin bars; "pill" draws wide rounded ones. */
  shape?: "tick" | "pill"
}

/** A progress bar drawn as a row of ticks, lit up to the current value. */
function TickBar({
  value,
  max = 100,
  segments = 40,
  color = "var(--chart-1)",
  trackColor,
  shape = "tick",
  className,
  ...props
}: TickBarProps) {
  const fraction = Math.min(1, Math.max(0, value / (max || 1)))
  // Any non-zero value lights at least one tick so small values still register.
  const filled = fraction === 0 ? 0 : Math.max(1, Math.round(fraction * segments))

  return (
    <div
      data-slot="tick-bar"
      data-shape={shape}
      role="progressbar"
      aria-valuemin={0}
      aria-valuemax={max}
      aria-valuenow={value}
      className={cn(
        "flex w-full",
        shape === "tick" ? "h-6 gap-[3px]" : "h-4 gap-1.5",
        className
      )}
      {...props}
    >
      {Array.from({ length: segments }, (_, index) => {
        const lit = index < filled
        return (
          <span
            key={index}
            data-filled={lit}
            className={cn(
              "bg-muted h-full min-w-0 flex-1 transition-colors",
              shape === "tick" ? "rounded-[1.5px]" : "rounded-full"
            )}
            style={{ backgroundColor: lit ? color : trackColor }}
          />
        )
      })}
    </div>
  )
}

export { TickBar }
```

# Timeline

A vertical chronology of events, each with a marker, connector, and free-form content. Use it for audit logs, activity feeds, and version history.

A vertical timeline for shadcn/ui: a rail, a marker per event, and free-form content beside it. Use it for audit logs, activity feeds, deployment history, and version lists.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/timeline.json
```

## Usage

```tsx
import {
  Timeline,
  TimelineConnector,
  TimelineContent,
  TimelineDescription,
  TimelineHeader,
  TimelineItem,
  TimelineMarker,
  TimelineRail,
  TimelineTime,
  TimelineTitle,
} from "@/components/ui/timeline"

<Timeline>
  <TimelineItem status="current">
    <TimelineRail>
      <TimelineMarker><Rocket /></TimelineMarker>
      <TimelineConnector />
    </TimelineRail>
    <TimelineContent>
      <TimelineHeader>
        <TimelineTitle>Canary rollout started</TimelineTitle>
        <Badge variant="secondary">Canary</Badge>
        <TimelineTime dateTime="2026-05-22T09:34">09:34</TimelineTime>
      </TimelineHeader>
      <TimelineDescription>Enabled for 5% of workspaces.</TimelineDescription>
    </TimelineContent>
  </TimelineItem>
</Timeline>
```

## Examples

### Default

```tsx
import {
  CircleCheck,
  Clock,
  Flag,
  Megaphone,
  Rocket,
  ShieldAlert,
} from "lucide-react"

import { Badge } from "@/components/ui/badge"
import {
  Timeline,
  TimelineConnector,
  TimelineContent,
  TimelineDescription,
  TimelineHeader,
  TimelineItem,
  TimelineMarker,
  TimelineRail,
  TimelineTime,
  TimelineTitle,
} from "@/components/ui/timeline"

const tones = {
  neutral: "",
  blue: "bg-sky-500/10 text-sky-700 dark:text-sky-400",
  amber: "bg-amber-500/10 text-amber-700 dark:text-amber-400",
  green: "bg-emerald-500/10 text-emerald-700 dark:text-emerald-400",
}

const events = [
  {
    icon: Flag,
    title: "Feature flag created",
    badge: "Owner assigned",
    tone: "neutral",
    time: "09:12",
    description: (
      <>
        Created <code className="text-foreground font-medium">checkout-redesign</code>{" "}
        for the billing workspace.
      </>
    ),
  },
  {
    icon: Rocket,
    title: "Canary rollout started",
    badge: "Canary",
    tone: "blue",
    time: "09:34",
    description: (
      <>
        Enabled for <span className="text-foreground font-medium">5% of workspaces</span>{" "}
        with session replay sampling on.
      </>
    ),
  },
  {
    icon: ShieldAlert,
    title: "Regional guardrail tripped",
    badge: "Paused",
    tone: "amber",
    time: "09:51",
    description: (
      <>
        Latency climbed in{" "}
        <span className="text-foreground font-medium">eu-central-1</span>; rollout is
        holding while routing warms.
      </>
    ),
  },
  {
    icon: Megaphone,
    title: "Customer messaging prepared",
    badge: "Docs",
    tone: "neutral",
    time: "10:05",
    description: (
      <>
        Support macro and changelog draft are ready in{" "}
        <span className="text-foreground font-medium">Launch notes</span>.
      </>
    ),
  },
  {
    icon: Clock,
    title: "Launch window scheduled",
    badge: "Queued",
    tone: "neutral",
    time: "10:30",
    description: "Full rollout waits for the next error-budget sweep.",
  },
  {
    icon: CircleCheck,
    title: "Release checklist verified",
    badge: "Ready",
    tone: "green",
    time: "10:42",
    description:
      "Rollback owner and dashboard checks are recorded in the release audit.",
    status: "current" as const,
  },
] satisfies Array<{
  icon: React.ElementType
  title: string
  badge: string
  tone: keyof typeof tones
  time: string
  description: React.ReactNode
  status?: "current"
}>

export default function TimelineDemo() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-4">
      <div className="flex flex-col gap-0.5">
        <span className="text-muted-foreground text-xs">Rollout audit</span>
        <span className="font-semibold">Checkout redesign</span>
      </div>
      <Timeline>
        {events.map((event) => (
          <TimelineItem key={event.title} status={event.status}>
            <TimelineRail>
              <TimelineMarker>
                <event.icon />
              </TimelineMarker>
              <TimelineConnector />
            </TimelineRail>
            <TimelineContent>
              <TimelineHeader>
                <TimelineTitle>{event.title}</TimelineTitle>
                <Badge variant="secondary" className={tones[event.tone]}>
                  {event.badge}
                </Badge>
                <TimelineTime dateTime={`2026-05-22T${event.time}`}>
                  {event.time}
                </TimelineTime>
              </TimelineHeader>
              <TimelineDescription>{event.description}</TimelineDescription>
            </TimelineContent>
          </TimelineItem>
        ))}
      </Timeline>
    </div>
  )
}
```

### Compact log

Tighten the rail and content spacing with classes. Markers take any icon and inherit text color.

```tsx
import { CircleCheck, CreditCard, FileText, ShieldAlert } from "lucide-react"

import { cn } from "@/lib/utils"
import {
  Timeline,
  TimelineConnector,
  TimelineContent,
  TimelineDescription,
  TimelineHeader,
  TimelineItem,
  TimelineMarker,
  TimelineRail,
  TimelineTime,
  TimelineTitle,
} from "@/components/ui/timeline"

const events = [
  {
    icon: ShieldAlert,
    title: "Chargeback case opened",
    time: "Mar 6, 10:34 AM",
    dateTime: "2026-03-06T10:34",
    description:
      "The customer disputed a renewal charge, and the finance team has seven days to submit evidence.",
    className: "text-amber-600 dark:text-amber-400",
  },
  {
    icon: CreditCard,
    title: "Payment captured",
    time: "Mar 6, 10:21 AM",
    dateTime: "2026-03-06T10:21",
    className: "text-emerald-600 dark:text-emerald-400",
  },
  {
    icon: CircleCheck,
    title: "Payment authorized",
    time: "Mar 6, 10:21 AM",
    dateTime: "2026-03-06T10:21",
  },
  {
    icon: FileText,
    title: "Invoice generated",
    time: "Mar 6, 10:20 AM",
    dateTime: "2026-03-06T10:20",
  },
]

export default function TimelineCompactDemo() {
  return (
    <Timeline className="w-full max-w-md">
      {events.map((event) => (
        <TimelineItem key={event.title} className="gap-2">
          <TimelineRail className="w-5">
            <TimelineMarker className={cn("size-5", event.className)}>
              <event.icon />
            </TimelineMarker>
            <TimelineConnector className="my-0.5" />
          </TimelineRail>
          <TimelineContent className="gap-0.5 pt-0 pb-3">
            <TimelineHeader>
              <TimelineTitle>{event.title}</TimelineTitle>
              <TimelineTime dateTime={event.dateTime}>{event.time}</TimelineTime>
            </TimelineHeader>
            {event.description ? (
              <TimelineDescription>{event.description}</TimelineDescription>
            ) : null}
          </TimelineContent>
        </TimelineItem>
      ))}
    </Timeline>
  )
}
```

### Activity feed

Put an avatar in the marker and any content, including cards, inside TimelineContent.

```tsx
import { ArrowUpRight } from "lucide-react"

import { Badge } from "@/components/ui/badge"
import {
  Timeline,
  TimelineConnector,
  TimelineContent,
  TimelineDescription,
  TimelineHeader,
  TimelineItem,
  TimelineMarker,
  TimelineRail,
  TimelineTime,
  TimelineTitle,
} from "@/components/ui/timeline"

const people = {
  mina: { name: "Mina Sol", gradient: "from-sky-400 to-indigo-500" },
  orin: { name: "Orin Vale", gradient: "from-amber-400 to-rose-500" },
  paz: { name: "Paz Kim", gradient: "from-emerald-400 to-teal-500" },
}

function Avatar({ person }: { person: keyof typeof people }) {
  return (
    <span
      role="img"
      aria-label={people[person].name}
      className={`size-full bg-linear-to-br ${people[person].gradient}`}
    />
  )
}

export default function TimelineActivityDemo() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-4">
      <div className="flex flex-col gap-0.5">
        <span className="text-muted-foreground text-xs">Studio review</span>
        <span className="font-semibold">Runner launch assets</span>
      </div>
      <Timeline>
        <TimelineItem>
          <TimelineRail>
            <TimelineMarker className="border-0">
              <Avatar person="mina" />
            </TimelineMarker>
            <TimelineConnector />
          </TimelineRail>
          <TimelineContent>
            <TimelineHeader>
              <TimelineTitle>Product asset uploaded</TimelineTitle>
              <Badge
                variant="secondary"
                className="bg-sky-500/10 text-sky-700 dark:text-sky-400"
              >
                Review
              </Badge>
              <TimelineTime dateTime="2026-05-22T10:18">
                <span className="text-foreground/80 font-medium">Mina Sol</span>{" "}
                10:18 AM
              </TimelineTime>
            </TimelineHeader>
            <div className="bg-card mt-1 flex gap-3 rounded-lg border p-3">
              <div className="bg-muted size-20 shrink-0 rounded-md" />
              <div className="flex flex-col gap-2">
                <TimelineDescription>
                  Final hero crop is ready for retouch review with the side profile,
                  lace detail, and marketplace thumbnail queued.
                </TimelineDescription>
                <div className="flex flex-wrap gap-1.5">
                  <Badge variant="outline">PDP hero</Badge>
                  <Badge variant="outline">4 crops</Badge>
                  <Badge variant="outline" asChild>
                    <a href="#">
                      Open board <ArrowUpRight />
                    </a>
                  </Badge>
                </div>
              </div>
            </div>
          </TimelineContent>
        </TimelineItem>
        <TimelineItem>
          <TimelineRail>
            <TimelineMarker className="border-0">
              <Avatar person="orin" />
            </TimelineMarker>
            <TimelineConnector />
          </TimelineRail>
          <TimelineContent>
            <TimelineHeader>
              <TimelineTitle>Lighting pass reviewed</TimelineTitle>
              <TimelineTime dateTime="2026-05-22T10:27">
                <span className="text-foreground/80 font-medium">Orin Vale</span>{" "}
                10:27 AM
              </TimelineTime>
            </TimelineHeader>
            <TimelineDescription>
              The side profile reads clearly on the landing page. Keep the outsole
              shadow soft so the sole texture stays visible.
            </TimelineDescription>
          </TimelineContent>
        </TimelineItem>
        <TimelineItem>
          <TimelineRail>
            <TimelineMarker className="border-0">
              <Avatar person="paz" />
            </TimelineMarker>
            <TimelineConnector />
          </TimelineRail>
          <TimelineContent>
            <TimelineHeader>
              <TimelineTitle>Copy note resolved</TimelineTitle>
              <TimelineTime dateTime="2026-05-22T10:43">
                <span className="text-foreground/80 font-medium">Paz Kim</span>{" "}
                10:43 AM
              </TimelineTime>
            </TimelineHeader>
            <TimelineDescription>
              Updated the launch tile copy and aligned the product badge with the
              approved campaign language.
            </TimelineDescription>
          </TimelineContent>
        </TimelineItem>
        <TimelineItem>
          <TimelineRail>
            <TimelineMarker className="border-0">
              <Avatar person="mina" />
            </TimelineMarker>
            <TimelineConnector />
          </TimelineRail>
          <TimelineContent>
            <TimelineHeader>
              <TimelineTitle>Review package ready</TimelineTitle>
              <TimelineTime dateTime="2026-05-22T11:06">
                <span className="text-foreground/80 font-medium">Mina Sol</span>{" "}
                11:06 AM
              </TimelineTime>
            </TimelineHeader>
            <TimelineDescription>
              Exported the approved crops and shared the board with the marketplace
              team for final sign-off.
            </TimelineDescription>
          </TimelineContent>
        </TimelineItem>
      </Timeline>
    </div>
  )
}
```

### Version history

An empty marker renders a plain ring. status="current" highlights the marker and sets aria-current.

```tsx
import { X } from "lucide-react"

import { Badge } from "@/components/ui/badge"
import { Button } from "@/components/ui/button"
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
import {
  Timeline,
  TimelineConnector,
  TimelineContent,
  TimelineDescription,
  TimelineHeader,
  TimelineItem,
  TimelineMarker,
  TimelineRail,
  TimelineTime,
  TimelineTitle,
} from "@/components/ui/timeline"

const versions = [
  {
    version: "v8",
    badge: "Draft",
    badgeClassName: "bg-sky-500/10 text-sky-700 dark:text-sky-400",
    status: "current" as const,
    description:
      "Prepared billing copy, tax preview states, and the final approval checklist.",
    author: "Maya Chen",
    gradient: "from-sky-400 to-indigo-500",
    time: "Current",
  },
  {
    version: "v7",
    badge: "Live",
    badgeClassName: "bg-emerald-500/10 text-emerald-700 dark:text-emerald-400",
    markerClassName: "border-emerald-500",
    description:
      "Published the pricing table refresh after support macros cleared review.",
    author: "Nora Vazquez",
    gradient: "from-emerald-400 to-teal-500",
    time: "May 22, 2026, 11:18 AM",
    dateTime: "2026-05-22T11:18",
  },
  {
    version: "v6",
    description:
      "Added regional tax notes and restored the upgrade confirmation banner.",
    author: "Eli Wong",
    gradient: "from-amber-400 to-rose-500",
    time: "May 21, 2026, 04:42 PM",
    dateTime: "2026-05-21T16:42",
  },
  {
    version: "v5",
    description: "Reworked mobile spacing for plan cards and invoice preview rows.",
    author: "Maya Chen",
    gradient: "from-sky-400 to-indigo-500",
    time: "May 20, 2026, 09:06 AM",
    dateTime: "2026-05-20T09:06",
  },
]

export default function TimelineVersionsDemo() {
  return (
    <Card className="w-full max-w-sm gap-4 py-4">
      <CardHeader className="flex items-center px-4">
        <CardTitle>Version history</CardTitle>
        <Button
          variant="ghost"
          size="icon-sm"
          className="text-muted-foreground ml-auto rounded-full"
          aria-label="Close"
        >
          <X />
        </Button>
      </CardHeader>
      <CardContent className="px-4">
        <Timeline>
          {versions.map((item) => (
            <TimelineItem key={item.version} status={item.status}>
              <TimelineRail>
                <TimelineMarker className={item.markerClassName} />
                <TimelineConnector />
              </TimelineRail>
              <TimelineContent className="gap-1.5">
                <TimelineHeader>
                  <TimelineTitle>{item.version}</TimelineTitle>
                  {item.badge ? (
                    <Badge variant="secondary" className={item.badgeClassName}>
                      {item.badge}
                    </Badge>
                  ) : null}
                </TimelineHeader>
                <TimelineDescription>{item.description}</TimelineDescription>
                <div className="text-muted-foreground flex items-center gap-2 text-xs">
                  <span
                    aria-hidden="true"
                    className={`size-4 rounded-full bg-linear-to-br ${item.gradient}`}
                  />
                  <span className="text-foreground/80">{item.author}</span>
                  <span aria-hidden="true">·</span>
                  <TimelineTime dateTime={item.dateTime} className="ml-0">
                    {item.time}
                  </TimelineTime>
                </div>
              </TimelineContent>
            </TimelineItem>
          ))}
        </Timeline>
      </CardContent>
    </Card>
  )
}
```

## Source

### components/ui/timeline.tsx

```tsx
import * as React from "react"

import { cn } from "@/lib/utils"

export type TimelineStatus = "default" | "current" | "done"

/**
 * Timeline owns only the chronology layout: an ordered list of items, each
 * with a rail (marker + connector) beside its content. Put your own semantic
 * content (headings, time, badges, avatars, cards) inside TimelineContent.
 */
function Timeline({ className, ...props }: React.ComponentProps<"ol">) {
  return (
    <ol
      data-slot="timeline"
      className={cn("flex flex-col", className)}
      {...props}
    />
  )
}

export interface TimelineItemProps extends React.ComponentProps<"li"> {
  /**
   * "current" marks the item as the present step (sets aria-current) and
   * highlights its marker. "done" fills the marker.
   */
  status?: TimelineStatus
}

function TimelineItem({
  status = "default",
  className,
  ...props
}: TimelineItemProps) {
  return (
    <li
      data-slot="timeline-item"
      data-status={status}
      aria-current={status === "current" ? "true" : undefined}
      className={cn("group/timeline-item relative flex gap-3", className)}
      {...props}
    />
  )
}

/** The column beside the content that holds the marker and connector. */
function TimelineRail({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="timeline-rail"
      className={cn("flex w-6 shrink-0 flex-col items-center", className)}
      {...props}
    />
  )
}

/**
 * The dot on the rail. Pass an icon, avatar, or image as children; with no
 * children it renders a plain ring and is hidden from assistive technology.
 */
function TimelineMarker({
  className,
  children,
  ...props
}: React.ComponentProps<"span">) {
  const empty = React.Children.count(children) === 0
  return (
    <span
      data-slot="timeline-marker"
      aria-hidden={empty ? "true" : undefined}
      className={cn(
        "bg-background text-muted-foreground flex size-6 shrink-0 items-center justify-center overflow-hidden rounded-full border",
        "[&>svg]:size-3 [&>img]:size-full [&>img]:object-cover",
        "group-data-[status=current]/timeline-item:border-primary group-data-[status=current]/timeline-item:text-primary group-data-[status=current]/timeline-item:ring-primary/20 group-data-[status=current]/timeline-item:ring-2",
        "group-data-[status=done]/timeline-item:bg-primary group-data-[status=done]/timeline-item:border-primary group-data-[status=done]/timeline-item:text-primary-foreground",
        className
      )}
      {...props}
    >
      {children}
    </span>
  )
}

/** The line between markers. Decorative; hidden on the last item. */
function TimelineConnector({
  className,
  ...props
}: React.ComponentProps<"span">) {
  return (
    <span
      data-slot="timeline-connector"
      aria-hidden="true"
      className={cn(
        "bg-border my-1 w-px flex-1 group-last/timeline-item:hidden",
        className
      )}
      {...props}
    />
  )
}

function TimelineContent({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="timeline-content"
      className={cn(
        "flex min-w-0 flex-1 flex-col gap-1 pt-0.5 pb-6 group-last/timeline-item:pb-0",
        className
      )}
      {...props}
    />
  )
}

/** A row for the title, badges, and time. Time floats right via TimelineTime. */
function TimelineHeader({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="timeline-header"
      className={cn("flex flex-wrap items-center gap-x-2 gap-y-1", className)}
      {...props}
    />
  )
}

function TimelineTitle({ className, ...props }: React.ComponentProps<"h3">) {
  return (
    <h3
      data-slot="timeline-title"
      className={cn("text-sm leading-5 font-medium", className)}
      {...props}
    />
  )
}

function TimelineTime({ className, ...props }: React.ComponentProps<"time">) {
  return (
    <time
      data-slot="timeline-time"
      className={cn(
        "text-muted-foreground ml-auto text-xs whitespace-nowrap tabular-nums",
        className
      )}
      {...props}
    />
  )
}

function TimelineDescription({
  className,
  ...props
}: React.ComponentProps<"p">) {
  return (
    <p
      data-slot="timeline-description"
      className={cn("text-muted-foreground text-sm", className)}
      {...props}
    />
  )
}

export {
  Timeline,
  TimelineItem,
  TimelineRail,
  TimelineMarker,
  TimelineConnector,
  TimelineContent,
  TimelineHeader,
  TimelineTitle,
  TimelineTime,
  TimelineDescription,
}
```

# Trend Chart

Area, line, or bar chart over time with tooltips and legend, built on shadcn's chart primitives.

The trend chart is the time-series chart for shadcn/ui dashboards. It renders area, line, or bar series through shadcn's chart wrapper, so tooltips, legends, and colors come from your theme, and it handles stacking, grouping, horizontal layouts, and dot-grid fills without dropping down to Recharts.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/trend-chart.json
```

Also installs `chart` from shadcn/ui if missing.

npm dependencies: `recharts`.

## Usage

```tsx
import { TrendChart } from "@/components/ui/trend-chart"

<TrendChart
  data={data}
  xKey="date"
  series={[
    { key: "desktop", label: "Desktop" },
    { key: "mobile", label: "Mobile" },
  ]}
  showLegend
/>
```

## Examples

### Default

```tsx
import { TrendChart } from "@/components/ui/trend-chart"

const data = [
  { date: "2026-08-04", desktop: 186, mobile: 80 },
  { date: "2026-08-05", desktop: 305, mobile: 200 },
  { date: "2026-08-06", desktop: 237, mobile: 120 },
  { date: "2026-08-07", desktop: 173, mobile: 190 },
  { date: "2026-08-08", desktop: 209, mobile: 130 },
  { date: "2026-08-09", desktop: 214, mobile: 140 },
  { date: "2026-08-10", desktop: 264, mobile: 160 },
  { date: "2026-08-11", desktop: 298, mobile: 210 },
  { date: "2026-08-12", desktop: 275, mobile: 180 },
  { date: "2026-08-13", desktop: 331, mobile: 240 },
  { date: "2026-08-14", desktop: 312, mobile: 220 },
  { date: "2026-08-15", desktop: 348, mobile: 260 },
  { date: "2026-08-16", desktop: 322, mobile: 250 },
  { date: "2026-08-17", desktop: 361, mobile: 270 },
]

export default function TrendChartDemo() {
  return (
    <TrendChart
      data={data}
      xKey="date"
      series={[
        { key: "desktop", label: "Desktop" },
        { key: "mobile", label: "Mobile" },
      ]}
      showLegend
    />
  )
}
```

### Line

Set type to "line" and show the y-axis with a unit formatter.

```tsx
"use client"

import { TrendChart } from "@/components/ui/trend-chart"

const data = Array.from({ length: 24 }, (_, hour) => ({
  hour: `${String(hour).padStart(2, "0")}:00`,
  p50: 120 + Math.round(Math.sin(hour / 3) * 30),
  p95: 340 + Math.round(Math.cos(hour / 4) * 90),
}))

export default function TrendChartLineDemo() {
  return (
    <TrendChart
      type="line"
      data={data}
      xKey="hour"
      series={[
        { key: "p50", label: "p50" },
        { key: "p95", label: "p95" },
      ]}
      yFormatter={(value) => `${value} ms`}
      showLegend
      showYAxis
    />
  )
}
```

### Dot grid

Set fill to "dots" to render the area as a dot grid that fades out toward the line.

```tsx
"use client"

import { TrendChart } from "@/components/ui/trend-chart"
import { formatNumber } from "@/lib/format"

const data = Array.from({ length: 60 }, (_, i) => ({
  minute: i,
  price: Math.round((3312 + i * 0.28 + Math.sin(i / 4) * 3 + Math.cos(i / 1.7) * 1.5) * 100) / 100,
}))

export default function TrendChartDotsDemo() {
  return (
    <TrendChart
      fill="dots"
      data={data}
      xKey="minute"
      series={[{ key: "price", label: "ETH / USDC", color: "var(--color-amber-500)" }]}
      xFormatter={(value) => {
        const ago = 59 - Number(value)
        return ago === 0 ? "now" : ago === 59 ? "1 h ago" : `${ago} min`
      }}
      yFormatter={(value) => formatNumber(value, { format: "currency" })}
      yDomain={["dataMin - 12", "dataMax + 4"]}
      showGrid={false}
    />
  )
}
```

### Stacked bars

Bars stack when stacked is set. Series stack bottom-up in the order given; negative values stack below zero.

```tsx
"use client"

import { TrendChart } from "@/components/ui/trend-chart"
import { formatNumber } from "@/lib/format"

const data = [
  { month: "Jan", starter: 18400, pro: 26200, enterprise: 31800 },
  { month: "Feb", starter: 19100, pro: 27900, enterprise: 33500 },
  { month: "Mar", starter: 20600, pro: 30400, enterprise: 35200 },
  { month: "Apr", starter: 20100, pro: 31800, enterprise: 38900 },
  { month: "May", starter: 21700, pro: 34100, enterprise: 41600 },
  { month: "Jun", starter: 22900, pro: 36500, enterprise: 44300 },
]

export default function TrendChartBarDemo() {
  return (
    <TrendChart
      type="bar"
      stacked
      data={data}
      xKey="month"
      series={[
        { key: "enterprise", label: "Enterprise", color: "var(--chart-4)" },
        { key: "pro", label: "Pro", color: "var(--chart-2)" },
        { key: "starter", label: "Starter", color: "var(--chart-1)" },
      ]}
      yFormatter={(value) =>
        formatNumber(value, { format: "currency", compact: true, maximumFractionDigits: 0 })
      }
      showLegend
      showYAxis
    />
  )
}
```

### Grouped pill bars

Unstacked series sit side by side. Set barRadius to "full" and a small barSize for pills, and place the legend with legendPosition and legendAlign.

```tsx
"use client"

import { TrendChart } from "@/components/ui/trend-chart"
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@/components/ui/card"

const data = [
  { day: "Mon", current: 118, previous: 88 },
  { day: "Tue", current: 178, previous: 146 },
  { day: "Wed", current: 148, previous: 168 },
  { day: "Thu", current: 208, previous: 138 },
  { day: "Fri", current: 186, previous: 158 },
  { day: "Sat", current: 78, previous: 98 },
  { day: "Sun", current: 58, previous: 68 },
]

export default function TrendChartGroupedDemo() {
  return (
    <Card className="w-full">
      <CardHeader>
        <CardTitle>Weekly Orders</CardTitle>
        <CardDescription>This week vs last week</CardDescription>
      </CardHeader>
      <CardContent>
        <TrendChart
          type="bar"
          data={data}
          xKey="day"
          series={[
            { key: "current", label: "This week", color: "var(--color-blue-500)" },
            { key: "previous", label: "Last week", color: "var(--color-blue-800)" },
          ]}
          barRadius="full"
          barSize={10}
          showYAxis
          showLegend
          legendPosition="top"
          legendAlign="right"
        />
      </CardContent>
    </Card>
  )
}
```

### Horizontal bars

Set layout to "horizontal" to run bars left to right with categories down the side. Works with any number of series, stacked or not.

```tsx
"use client"

import { TrendChart } from "@/components/ui/trend-chart"
import { formatNumber } from "@/lib/format"
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@/components/ui/card"

const data = [
  { product: "Widgets", units: 1850 },
  { product: "Gadgets", units: 1580 },
  { product: "Modules", units: 1230 },
  { product: "Plugins", units: 980 },
  { product: "Add-ons", units: 740 },
]

export default function TrendChartHorizontalDemo() {
  return (
    <Card className="w-full">
      <CardHeader>
        <CardTitle>Top Products</CardTitle>
        <CardDescription>Units sold this quarter</CardDescription>
      </CardHeader>
      <CardContent>
        <TrendChart
          type="bar"
          layout="horizontal"
          data={data}
          xKey="product"
          series={[{ key: "units", label: "Units", color: "var(--color-blue-500)" }]}
          barRadius="full"
          barSize={14}
          showGrid={false}
          showYAxis
          yFormatter={(value) => formatNumber(value, { format: "compact" })}
          className="h-56"
        />
      </CardContent>
    </Card>
  )
}
```

## Source

### components/ui/trend-chart.tsx

```tsx
"use client"

import * as React from "react"
import {
  Area,
  AreaChart,
  AreaRevealShape,
  Bar,
  BarChart,
  CartesianGrid,
  Line,
  LineChart,
  ReferenceLine,
  XAxis,
  YAxis,
  type AreaRevealShapeProps,
} from "recharts"

import { cn } from "@/lib/utils"
import {
  ChartContainer,
  ChartLegend,
  ChartLegendContent,
  ChartTooltip,
  ChartTooltipContent,
  type ChartConfig,
} from "@/components/ui/chart"

export interface TrendSeries {
  /** Key in each data row. */
  key: string
  label: string
  /** Any CSS color. Defaults to chart-1 through chart-5 in order. */
  color?: string
}

export interface TrendChartProps
  extends Omit<React.ComponentProps<typeof ChartContainer>, "config" | "children"> {
  data: Record<string, unknown>[]
  /** Key of the x-axis value in each row. */
  xKey: string
  series: TrendSeries[]
  type?: "area" | "line" | "bar"
  /** Area fill: a plain gradient, or a dot grid that fades out toward the line. */
  fill?: "gradient" | "dots"
  /** Bars only: "horizontal" runs bars left to right with categories down the side. */
  layout?: "vertical" | "horizontal"
  /** Bars only: corner radius in px, or "full" for pill-shaped bars. */
  barRadius?: number | "full"
  /** Bars only: thickness of each bar in px. Defaults to a share of the category width. */
  barSize?: number
  stacked?: boolean
  showLegend?: boolean
  legendPosition?: "top" | "bottom"
  legendAlign?: "left" | "center" | "right"
  showGrid?: boolean
  /** Show the value axis. In the horizontal layout this is the axis along the bottom. */
  showYAxis?: boolean
  /** Recharts domain for the value axis, e.g. ["dataMin", "dataMax"] or ["auto", "auto"]. Defaults to [0, "auto"]. */
  yDomain?: React.ComponentProps<typeof YAxis>["domain"]
  xFormatter?: (value: unknown) => string
  yFormatter?: (value: number) => string
}

function defaultXFormatter(value: unknown) {
  if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}/.test(value)) {
    const [y, m, d] = value.split("-").map(Number)
    return new Date(y!, m! - 1, d).toLocaleDateString("en-US", {
      month: "short",
      day: "numeric",
    })
  }
  return String(value)
}

/** Area shape that masks the fill to a dot grid while keeping the stroke solid. */
function DotGridAreaShape({
  maskId,
  ...props
}: AreaRevealShapeProps & { maskId: string }) {
  return (
    <>
      <g mask={`url(#${maskId})`}>
        <AreaRevealShape {...props} stroke="none" />
      </g>
      <AreaRevealShape {...props} id={undefined} fill="none" />
    </>
  )
}

/** Recharts clamps corner radii to half the bar, so an oversized radius draws a pill. */
const PILL = 9999

type Radius = number | [number, number, number, number]

/** Round only the outer corners of a stack; mixed-sign stacks stay square. */
function barCorners(
  radius: number | "full",
  stacked: boolean,
  hasNegative: boolean,
  horizontal: boolean,
  index: number,
  count: number
): Radius {
  const r = radius === "full" ? PILL : radius
  if (!stacked || count === 1) return r
  if (hasNegative) return 0
  // Corners run [top-left, top-right, bottom-right, bottom-left].
  if (index === count - 1) return horizontal ? [0, r, r, 0] : [r, r, 0, 0]
  if (index === 0) return horizontal ? [r, 0, 0, r] : [0, 0, r, r]
  return 0
}

function TrendChart({
  data,
  xKey,
  series,
  type = "area",
  fill = "gradient",
  layout = "vertical",
  barRadius = 4,
  barSize,
  stacked = false,
  showLegend = false,
  legendPosition = "bottom",
  legendAlign = "center",
  showGrid = true,
  showYAxis = false,
  yDomain,
  xFormatter = defaultXFormatter,
  yFormatter,
  className,
  ...props
}: TrendChartProps) {
  const id = React.useId()
  const dots = type === "area" && fill === "dots"
  const horizontal = type === "bar" && layout === "horizontal"
  const hasNegative = React.useMemo(
    () =>
      data.some((row) =>
        series.some((s) => {
          const v = row[s.key]
          return typeof v === "number" && v < 0
        })
      ),
    [data, series]
  )
  const config = Object.fromEntries(
    series.map((s, index) => [
      s.key,
      { label: s.label, color: s.color ?? `var(--chart-${(index % 5) + 1})` },
    ])
  ) satisfies ChartConfig

  const axes = (
    <>
      {showGrid ? (
        <CartesianGrid vertical={horizontal} horizontal={!horizontal} />
      ) : null}
      {horizontal ? (
        <>
          <XAxis
            type="number"
            hide={!showYAxis}
            tickLine={false}
            axisLine={false}
            tickMargin={8}
            domain={yDomain}
            tickFormatter={yFormatter}
          />
          <YAxis
            type="category"
            dataKey={xKey}
            tickLine={false}
            axisLine={false}
            tickMargin={8}
            width="auto"
            tickFormatter={xFormatter}
          />
        </>
      ) : (
        <>
          <XAxis
            dataKey={xKey}
            tickLine={false}
            axisLine={false}
            tickMargin={8}
            minTickGap={32}
            tickFormatter={xFormatter}
          />
          {showYAxis ? (
            <YAxis
              tickLine={false}
              axisLine={false}
              tickMargin={8}
              width="auto"
              domain={yDomain}
              tickFormatter={yFormatter}
            />
          ) : yDomain ? (
            <YAxis hide domain={yDomain} />
          ) : null}
        </>
      )}
      {hasNegative ? (
        <ReferenceLine
          {...(horizontal ? { x: 0 } : { y: 0 })}
          stroke="var(--border)"
          strokeWidth={1}
        />
      ) : null}
      <ChartTooltip
        cursor={false}
        content={
          <ChartTooltipContent
            indicator={type === "bar" ? "dashed" : "dot"}
            labelFormatter={(value) => xFormatter(value)}
            formatter={
              yFormatter
                ? (value, name) => (
                    <div className="flex w-full items-center justify-between gap-4">
                      <span className="text-muted-foreground">
                        {config[name as string]?.label ?? name}
                      </span>
                      <span className="font-mono font-medium tabular-nums">
                        {yFormatter(Number(value))}
                      </span>
                    </div>
                  )
                : undefined
            }
          />
        }
      />
      {showLegend ? (
        <ChartLegend
          verticalAlign={legendPosition}
          align={legendAlign}
          content={
            <ChartLegendContent
              className={
                legendAlign === "right"
                  ? "justify-end"
                  : legendAlign === "left"
                    ? "justify-start"
                    : undefined
              }
            />
          }
        />
      ) : null}
    </>
  )

  const margin = {
    top: 8,
    right: 8,
    bottom: 0,
    left: showYAxis || horizontal ? 0 : 8,
  }

  return (
    <ChartContainer
      data-slot="trend-chart"
      config={config}
      className={cn("aspect-auto h-64 w-full", className)}
      {...props}
    >
      {type === "bar" ? (
        <BarChart
          data={data}
          layout={horizontal ? "vertical" : "horizontal"}
          margin={margin}
          stackOffset={stacked ? "sign" : "none"}
        >
          {axes}
          {series.map((s, index) => (
            <Bar
              key={s.key}
              dataKey={s.key}
              fill={`var(--color-${s.key})`}
              barSize={barSize}
              radius={barCorners(
                barRadius,
                stacked,
                hasNegative,
                horizontal,
                index,
                series.length
              )}
              stackId={stacked ? "stack" : undefined}
            />
          ))}
        </BarChart>
      ) : type === "line" ? (
        <LineChart data={data} margin={margin}>
          {axes}
          {series.map((s) => (
            <Line
              key={s.key}
              type="monotone"
              dataKey={s.key}
              stroke={`var(--color-${s.key})`}
              strokeWidth={2}
              dot={false}
            />
          ))}
        </LineChart>
      ) : (
        <AreaChart
          data={data}
          margin={margin}
          stackOffset={stacked ? "sign" : "none"}
        >
          <defs>
            {series.map((s) => (
              <linearGradient
                key={s.key}
                id={`${id}-${s.key}`}
                x1="0"
                y1="0"
                x2="0"
                y2="1"
              >
                <stop
                  offset="5%"
                  stopColor={`var(--color-${s.key})`}
                  stopOpacity={dots ? 0.08 : 0.6}
                />
                <stop
                  offset="95%"
                  stopColor={`var(--color-${s.key})`}
                  stopOpacity={dots ? 0.9 : 0.05}
                />
              </linearGradient>
            ))}
            {dots ? (
              <>
                <pattern
                  id={`${id}-dots`}
                  patternUnits="userSpaceOnUse"
                  width={6}
                  height={6}
                >
                  <circle cx={3} cy={3} r={1.25} fill="#fff" />
                </pattern>
                <mask
                  id={`${id}-mask`}
                  maskUnits="userSpaceOnUse"
                  x={0}
                  y={0}
                  width="100%"
                  height="100%"
                >
                  <rect width="100%" height="100%" fill={`url(#${id}-dots)`} />
                </mask>
              </>
            ) : null}
          </defs>
          {axes}
          {series.map((s) => (
            <Area
              key={s.key}
              type="monotone"
              dataKey={s.key}
              stroke={`var(--color-${s.key})`}
              fill={`url(#${id}-${s.key})`}
              fillOpacity={dots ? 1 : undefined}
              strokeWidth={2}
              stackId={stacked ? "stack" : undefined}
              shape={
                dots
                  ? (shapeProps: AreaRevealShapeProps) => (
                      <DotGridAreaShape {...shapeProps} maskId={`${id}-mask`} />
                    )
                  : undefined
              }
            />
          ))}
        </AreaChart>
      )}
    </ChartContainer>
  )
}

export { TrendChart }
```

# Blocks

Cards composed from the primitives above.

# Activity Rings Card

A card with concentric goal rings and a tile per ring with its value. Hovering a tile or a ring focuses the pair.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/activity-rings-card.json
```

Also installs `card` from shadcn/ui if missing.

## Usage

```tsx
import { ActivityRingsCard } from "@/components/activity-rings-card"

<ActivityRingsCard
  title="Activity"
  caption="Today"
  metrics={[
    { label: "Move", value: 1592, max: 1800, unit: "kcal", color: "var(--color-pink-500)" },
    { label: "Exercise", value: 105, max: 120, display: "1h 45m", color: "var(--color-lime-500)" },
    { label: "Running", value: 5.2, max: 8, unit: "km", color: "var(--color-sky-500)" },
  ]}
/>
```

## Examples

### Default

```tsx
import { ActivityRingsCard } from "@/registry/dashboardcn/blocks/activity-rings-card"

export default function ActivityRingsCardDemo() {
  return (
    <ActivityRingsCard
      className="w-full max-w-sm"
      title="Activity"
      caption="Today"
      metrics={[
        { label: "Move", value: 1592, max: 1800, unit: "kcal", color: "var(--color-pink-500)" },
        { label: "Exercise", value: 105, max: 120, display: "1h 45m", color: "var(--color-lime-500)" },
        { label: "Running", value: 5.2, max: 8, unit: "km", color: "var(--color-sky-500)" },
      ]}
    />
  )
}
```

### Side by side

layout="side" puts the tiles next to the rings. center renders content in the middle of the rings.

```tsx
import { ActivityRingsCard } from "@/registry/dashboardcn/blocks/activity-rings-card"

export default function ActivityRingsCardSideDemo() {
  return (
    <ActivityRingsCard
      className="w-full max-w-lg"
      title="Weekly goals"
      caption="Sep 1 – Sep 7"
      layout="side"
      size={150}
      thickness={12}
      metrics={[
        { label: "Deploys", value: 42, max: 50, color: "var(--color-emerald-500)" },
        { label: "Reviews", value: 18, max: 30, color: "var(--color-violet-500)" },
        { label: "Issues closed", value: 27, max: 25, color: "var(--color-amber-500)" },
      ]}
      center={
        <>
          <span className="text-xl font-semibold tabular-nums">87</span>
          <span className="text-muted-foreground text-xs">of 105</span>
        </>
      }
    />
  )
}
```

## Source

### components/activity-rings-card.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import { Card, CardAction, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
import { ActivityRings, type ActivityRing } from "@/components/ui/activity-rings"

export interface ActivityRingsMetric extends ActivityRing {
  /** Text shown for the value, e.g. "1h 45m". Defaults to the formatted value plus `unit`. */
  display?: string
  format?: NumberFormat
  currency?: string
  /** Suffix after the number, e.g. "kcal" or "km". */
  unit?: string
}

export interface ActivityRingsCardProps
  extends Omit<React.ComponentProps<typeof Card>, "children"> {
  title: string
  /** Muted text under the title, e.g. the date. */
  caption?: string
  /** Outermost ring first. */
  metrics: ActivityRingsMetric[]
  /** "stacked" puts the tiles above the rings; "side" puts them next to the rings. */
  layout?: "stacked" | "side"
  /** Ring diameter in pixels. */
  size?: number
  thickness?: number
  gap?: number
  /** Content in the middle of the rings, e.g. a total. */
  center?: React.ReactNode
  /** Slot in the top-right corner, e.g. a menu button. */
  action?: React.ReactNode
}

const defaultColors = [
  "var(--chart-1)",
  "var(--chart-2)",
  "var(--chart-3)",
  "var(--chart-4)",
  "var(--chart-5)",
]

function metricText(metric: ActivityRingsMetric) {
  if (metric.display) return metric.display
  const number = formatNumber(metric.value, {
    format: metric.format,
    currency: metric.currency,
    maximumFractionDigits: metric.format ? undefined : 1,
  })
  return metric.unit ? `${number} ${metric.unit}` : number
}

/** A card with concentric goal rings and a tile per ring. Hovering a tile or a ring focuses the pair. */
function ActivityRingsCard({
  title,
  caption,
  metrics,
  layout = "stacked",
  size = 180,
  thickness = 14,
  gap = 4,
  center,
  action,
  className,
  ...props
}: ActivityRingsCardProps) {
  const [active, setActive] = React.useState<number | null>(null)
  const rings = metrics.map((metric, index) => ({
    ...metric,
    color: metric.color ?? defaultColors[index % defaultColors.length],
  }))

  const tiles = (
    <ul
      className="grid gap-2"
      style={{
        gridTemplateColumns: `repeat(${layout === "side" ? 1 : Math.min(rings.length, 3)}, minmax(0, 1fr))`,
      }}
    >
      {rings.map((metric, index) => {
        const max = metric.max ?? 100
        const share = Math.min(1, Math.max(0, metric.value / (max || 1)))
        return (
          <li
            key={metric.label}
            data-active={active === index || undefined}
            onMouseEnter={() => setActive(index)}
            onMouseLeave={() => setActive(null)}
            className={cn(
              "flex min-w-0 flex-col gap-1 rounded-lg border px-3 py-2.5 transition-[opacity,border-color] duration-200",
              active !== null && active !== index && "opacity-50",
              active === index && "border-foreground/20"
            )}
          >
            <span className="text-muted-foreground flex items-center gap-1.5 text-xs">
              <span
                aria-hidden="true"
                className="size-2 shrink-0 rounded-full"
                style={{ backgroundColor: metric.color }}
              />
              <span className="truncate">{metric.label}</span>
            </span>
            <span className="truncate text-sm font-semibold tabular-nums">
              {metricText(metric)}
            </span>
            <span className="sr-only">{Math.round(share * 100)}% of goal</span>
          </li>
        )
      })}
    </ul>
  )

  return (
    <Card
      data-slot="activity-rings-card"
      className={cn("@container/card gap-4", className)}
      {...props}
    >
      <CardHeader>
        <CardTitle className="text-base">{title}</CardTitle>
        {caption ? (
          <span className="text-muted-foreground text-sm">{caption}</span>
        ) : null}
        {action ? <CardAction>{action}</CardAction> : null}
      </CardHeader>
      <CardContent
        className={cn(
          "flex gap-5",
          layout === "side"
            ? "flex-col items-center @sm/card:flex-row @sm/card:items-center @sm/card:justify-between"
            : "flex-col"
        )}
      >
        {layout === "side" ? (
          <>
            <ActivityRings
              rings={rings}
              size={size}
              thickness={thickness}
              gap={gap}
              activeIndex={active}
              onActiveIndexChange={setActive}
            >
              {center}
            </ActivityRings>
            <div className="w-full @sm/card:max-w-[14rem]">{tiles}</div>
          </>
        ) : (
          <>
            {tiles}
            <ActivityRings
              rings={rings}
              size={size}
              thickness={thickness}
              gap={gap}
              activeIndex={active}
              onActiveIndexChange={setActive}
              className="self-center"
            >
              {center}
            </ActivityRings>
          </>
        )}
      </CardContent>
    </Card>
  )
}

export { ActivityRingsCard }
```

### components/ui/activity-rings.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"

export interface ActivityRing {
  label: string
  /** Progress toward `max`. Values past `max` draw a full ring. */
  value: number
  /** Goal for the ring. Defaults to 100. */
  max?: number
  /** Any CSS color. Defaults to chart-1 through chart-5 in order. */
  color?: string
}

export interface ActivityRingsProps
  extends Omit<React.ComponentProps<"div">, "children"> {
  /** Outermost ring first. */
  rings: ActivityRing[]
  /** Diameter in pixels. */
  size?: number
  /** Stroke width of each ring in pixels. */
  thickness?: number
  /** Space between rings in pixels. */
  gap?: number
  /** Opacity of the unfilled track, drawn in the ring's color. */
  trackOpacity?: number
  /** Ring drawn at full strength while the rest dim. `null` shows every ring. */
  activeIndex?: number | null
  onActiveIndexChange?: (index: number | null) => void
  /** Content rendered in the middle. */
  children?: React.ReactNode
}

const defaultColors = [
  "var(--chart-1)",
  "var(--chart-2)",
  "var(--chart-3)",
  "var(--chart-4)",
  "var(--chart-5)",
]

// Round so server and client render identical attributes.
const round = (n: number) => Math.round(n * 1000) / 1000

/** Concentric progress rings, one per goal, in the style of a fitness watch. */
function ActivityRings({
  rings,
  size = 160,
  thickness = 12,
  gap = 4,
  trackOpacity = 0.2,
  activeIndex: activeProp,
  onActiveIndexChange,
  className,
  children,
  ...props
}: ActivityRingsProps) {
  const [activeState, setActiveState] = React.useState<number | null>(null)
  const active = activeProp === undefined ? activeState : activeProp
  const setActive = (index: number | null) => {
    setActiveState(index)
    onActiveIndexChange?.(index)
  }

  const center = size / 2
  const label = rings
    .map((ring) => {
      const max = ring.max ?? 100
      return `${ring.label} ${Math.round((ring.value / (max || 1)) * 100)}%`
    })
    .join(", ")

  return (
    <div
      data-slot="activity-rings"
      className={cn("relative inline-flex shrink-0", className)}
      style={{ width: size, height: size }}
      {...props}
    >
      <svg
        width={size}
        height={size}
        viewBox={`0 0 ${size} ${size}`}
        role="img"
        aria-label={label}
        className="absolute inset-0 -rotate-90"
      >
        {rings.map((ring, index) => {
          const max = ring.max ?? 100
          const fraction = Math.min(1, Math.max(0, ring.value / (max || 1)))
          const r = center - thickness / 2 - index * (thickness + gap)
          if (r <= 0) return null
          const color = ring.color ?? defaultColors[index % defaultColors.length]
          const dimmed = active !== null && active !== index
          return (
            <g
              key={ring.label}
              data-ring=""
              data-active={active === index || undefined}
              onMouseEnter={() => setActive(index)}
              onMouseLeave={() => setActive(null)}
              className="transition-opacity duration-200"
              style={{ opacity: dimmed ? 0.35 : 1 }}
            >
              <circle
                cx={center}
                cy={center}
                r={round(r)}
                fill="none"
                stroke={color}
                strokeOpacity={trackOpacity}
                strokeWidth={thickness}
              />
              {fraction > 0 ? (
                <circle
                  cx={center}
                  cy={center}
                  r={round(r)}
                  fill="none"
                  stroke={color}
                  strokeWidth={thickness}
                  strokeLinecap="round"
                  pathLength={1}
                  strokeDasharray="1 1"
                  strokeDashoffset={round(1 - fraction)}
                  className="transition-[stroke-dashoffset] duration-700 ease-out"
                />
              ) : null}
            </g>
          )
        })}
      </svg>
      {children ? (
        <div className="pointer-events-none absolute inset-0 flex flex-col items-center justify-center text-center">
          {children}
        </div>
      ) : null}
    </div>
  )
}

export { ActivityRings }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Allocation Card

A share-of-total card with a period switcher, a big percentage with delta, a tick bar, and a footer stat with an avatar stack.

A share-of-total card with a period switcher, a big percentage with delta, a tick bar, and a footer stat with an avatar stack. Built for portfolio allocation and similar share metrics.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/allocation-card.json
```

Also installs `card`, `tabs`, `tooltip` from shadcn/ui if missing.

npm dependencies: `lucide-react`.

## Usage

```tsx
import { AllocationCard } from "@/components/allocation-card"

<AllocationCard
  title="Portfolio allocation"
  description="Share of assets under management held in equities."
  value={0.46}
  delta={0.034}
  deltaLabel="vs prior period"
  periods={[
    { value: "week", label: "Week" },
    { value: "month", label: "Month" },
  ]}
  stat={{ label: "Equities exposure", value: "$4.7M" }}
  people={[
    { name: "shadcn", src: "https://github.com/shadcn.png" },
    { name: "Kai" },
  ]}
  peopleLabel="6 members"
/>
```

## Examples

### Default

```tsx
import { AllocationCard } from "@/registry/dashboardcn/blocks/allocation-card"

export default function AllocationCardDemo() {
  return (
    <AllocationCard
      className="w-full max-w-md"
      title="Portfolio allocation"
      description="Share of assets under management currently held in equities."
      value={0.46}
      delta={0.034}
      deltaLabel="vs prior period"
      periods={[
        { value: "week", label: "Week" },
        { value: "month", label: "Month" },
        { value: "year", label: "Year" },
      ]}
      stat={{ label: "Equities exposure", value: "$4.7M" }}
      people={[
        { name: "shadcn", src: "https://github.com/shadcn.png" },
        { name: "Evil Rabbit", src: "https://github.com/evilrabbit.png" },
        { name: "Kai" },
      ]}
      peopleLabel="6 members"
    />
  )
}
```

## Source

### components/allocation-card.tsx

```tsx
"use client"

import * as React from "react"
import { Info } from "lucide-react"

import { cn } from "@/lib/utils"
import { type NumberFormat } from "@/lib/format"
import {
  Card,
  CardAction,
  CardContent,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"
import { DeltaBadge } from "@/components/ui/delta-badge"
import { PeriodTabs, type PeriodOption } from "@/components/ui/period-tabs"
import { TickBar } from "@/components/ui/tick-bar"
import { MetricValue } from "@/components/ui/metric-value"

export interface AllocationCardPerson {
  name: string
  /** Avatar image. Falls back to the first letter of the name. */
  src?: string
}

export interface AllocationCardProps extends React.ComponentProps<typeof Card> {
  title: string
  /** Shown in a tooltip behind an info icon next to the title. */
  description?: string
  /** Share of the whole, e.g. 0.46 for 46%. */
  value: number
  format?: NumberFormat
  currency?: string
  /** Bar fill from 0 to 100. Defaults to value when format is percent. */
  progress?: number
  /** Fractional change vs the prior period, e.g. 0.034 for +3.4%. */
  delta?: number
  /** Text after the delta, e.g. "vs prior period". */
  deltaLabel?: string
  /** Treat a decrease as good. */
  invertDelta?: boolean
  /** Any CSS color for the bar. */
  color?: string
  /** Number of ticks in the bar. */
  segments?: number
  /** Period options for the switcher. Omit to hide it. */
  periods?: PeriodOption[]
  period?: string
  defaultPeriod?: string
  onPeriodChange?: (period: string) => void
  /** Footer stat, e.g. { label: "Equities exposure", value: "$4.7M" }. */
  stat?: { label: string; value: React.ReactNode }
  /** Avatars shown in the footer. */
  people?: AllocationCardPerson[]
  /** Text next to the avatars, e.g. "6 members". */
  peopleLabel?: string
}

/** A share-of-total card with a period switcher, a big percentage with delta, a tick bar, and a footer stat with an avatar stack. */
function AllocationCard({
  title,
  description,
  value,
  format = "percent",
  currency,
  progress,
  delta,
  deltaLabel,
  invertDelta,
  color = "var(--color-emerald-500)",
  segments = 40,
  periods,
  period,
  defaultPeriod,
  onPeriodChange,
  stat,
  people = [],
  peopleLabel,
  className,
  ...props
}: AllocationCardProps) {
  const fill = progress ?? (format === "percent" ? value * 100 : value)

  return (
    <Card data-slot="allocation-card" className={cn("gap-4", className)} {...props}>
      <CardHeader>
        <CardTitle className="flex items-center gap-1.5 text-sm">
          <span className="truncate">{title}</span>
          {description ? (
            <TooltipProvider>
              <Tooltip>
                <TooltipTrigger asChild>
                  <button
                    type="button"
                    className="text-muted-foreground hover:text-foreground inline-flex shrink-0 rounded-full"
                  >
                    <Info className="size-3.5" />
                    <span className="sr-only">About {title}</span>
                  </button>
                </TooltipTrigger>
                <TooltipContent className="max-w-56">{description}</TooltipContent>
              </Tooltip>
            </TooltipProvider>
          ) : null}
        </CardTitle>
        {periods ? (
          <CardAction>
            <PeriodTabs
              options={periods}
              value={period}
              defaultValue={defaultPeriod ?? periods[0]?.value}
              onValueChange={onPeriodChange}
            />
          </CardAction>
        ) : null}
      </CardHeader>
      <CardContent className="flex flex-col gap-4">
        <div className="flex flex-wrap items-baseline gap-x-2 gap-y-1">
          <MetricValue
            value={value}
            format={format}
            currency={currency}
            maximumFractionDigits={0}
            className="text-4xl font-semibold tracking-tight"
          />
          {delta !== undefined ? (
            <DeltaBadge delta={delta} invert={invertDelta} variant="text" showIcon={false} className="text-sm" />
          ) : null}
          {deltaLabel ? (
            <span className="text-muted-foreground text-sm">{deltaLabel}</span>
          ) : null}
        </div>
        <TickBar value={fill} segments={segments} color={color} />
      </CardContent>
      {stat || people.length || peopleLabel ? (
        <CardFooter className="justify-between gap-4 text-sm">
          {stat ? (
            <span className="text-muted-foreground min-w-0 truncate">
              {stat.label}:{" "}
              <span className="text-foreground font-semibold tabular-nums">{stat.value}</span>
            </span>
          ) : (
            <span />
          )}
          {people.length || peopleLabel ? (
            <div className="flex shrink-0 items-center gap-2">
              {people.length ? (
                <div
                  className="flex -space-x-2"
                  aria-label={people.map((p) => p.name).join(", ")}
                >
                  {people.map((person) => (
                    <span
                      key={person.name}
                      title={person.name}
                      className="bg-muted ring-card text-muted-foreground flex size-7 items-center justify-center overflow-hidden rounded-full text-xs font-medium ring-2"
                    >
                      {person.src ? (
                        // eslint-disable-next-line @next/next/no-img-element
                        <img
                          src={person.src}
                          alt={person.name}
                          className="size-full object-cover"
                        />
                      ) : (
                        person.name.charAt(0).toUpperCase()
                      )}
                    </span>
                  ))}
                </div>
              ) : null}
              {peopleLabel ? (
                <span className="text-muted-foreground whitespace-nowrap">{peopleLabel}</span>
              ) : null}
            </div>
          ) : null}
        </CardFooter>
      ) : null}
    </Card>
  )
}

export { AllocationCard }
```

### components/ui/tick-bar.tsx

```tsx
import * as React from "react"

import { cn } from "@/lib/utils"

export interface TickBarProps extends React.ComponentProps<"div"> {
  /** Current value, from 0 to max. */
  value: number
  max?: number
  /** Number of ticks. */
  segments?: number
  /** Any CSS color for the filled ticks. Defaults to chart-1. */
  color?: string
  /** Any CSS color for the unfilled ticks. Defaults to muted. */
  trackColor?: string
  /** "tick" draws thin bars; "pill" draws wide rounded ones. */
  shape?: "tick" | "pill"
}

/** A progress bar drawn as a row of ticks, lit up to the current value. */
function TickBar({
  value,
  max = 100,
  segments = 40,
  color = "var(--chart-1)",
  trackColor,
  shape = "tick",
  className,
  ...props
}: TickBarProps) {
  const fraction = Math.min(1, Math.max(0, value / (max || 1)))
  // Any non-zero value lights at least one tick so small values still register.
  const filled = fraction === 0 ? 0 : Math.max(1, Math.round(fraction * segments))

  return (
    <div
      data-slot="tick-bar"
      data-shape={shape}
      role="progressbar"
      aria-valuemin={0}
      aria-valuemax={max}
      aria-valuenow={value}
      className={cn(
        "flex w-full",
        shape === "tick" ? "h-6 gap-[3px]" : "h-4 gap-1.5",
        className
      )}
      {...props}
    >
      {Array.from({ length: segments }, (_, index) => {
        const lit = index < filled
        return (
          <span
            key={index}
            data-filled={lit}
            className={cn(
              "bg-muted h-full min-w-0 flex-1 transition-colors",
              shape === "tick" ? "rounded-[1.5px]" : "rounded-full"
            )}
            style={{ backgroundColor: lit ? color : trackColor }}
          />
        )
      })}
    </div>
  )
}

export { TickBar }
```

### components/ui/delta-badge.tsx

```tsx
import * as React from "react"
import { Minus, TrendingDown, TrendingUp } from "lucide-react"

import { cn } from "@/lib/utils"
import { formatDelta } from "@/lib/format"

export type DeltaDirection = "up" | "down" | "flat"

export function getDeltaDirection(delta: number | undefined): DeltaDirection {
  if (delta === undefined || delta === 0 || !Number.isFinite(delta)) return "flat"
  return delta > 0 ? "up" : "down"
}

const directionIcon: Record<DeltaDirection, React.ElementType> = {
  up: TrendingUp,
  down: TrendingDown,
  flat: Minus,
}

export interface DeltaBadgeProps extends React.ComponentProps<"span"> {
  /** Fractional change, e.g. 0.124 for +12.4%. */
  delta: number
  /** Treat a decrease as good and an increase as bad (churn, latency, errors). */
  invert?: boolean
  variant?: "outline" | "soft" | "text"
  showIcon?: boolean
}

function DeltaBadge({
  delta,
  invert = false,
  variant = "outline",
  showIcon = true,
  className,
  children,
  ...props
}: DeltaBadgeProps) {
  const direction = getDeltaDirection(delta)
  const positive = direction === "flat" ? null : (direction === "up") !== invert
  const Icon = directionIcon[direction]

  return (
    <span
      data-slot="delta-badge"
      data-direction={direction}
      data-positive={positive}
      className={cn(
        "inline-flex items-center gap-1 text-xs font-medium tabular-nums",
        variant === "outline" && "rounded-md border px-1.5 py-0.5",
        variant === "soft" && "rounded-md px-1.5 py-0.5",
        variant === "soft" && positive === true && "bg-emerald-500/10",
        variant === "soft" && positive === false && "bg-red-500/10",
        variant === "soft" && positive === null && "bg-muted",
        positive === true && "text-emerald-600 dark:text-emerald-400",
        positive === false && "text-red-600 dark:text-red-400",
        positive === null && "text-muted-foreground",
        className
      )}
      {...props}
    >
      {showIcon ? <Icon className="size-3" aria-hidden="true" /> : null}
      {children ?? formatDelta(delta)}
    </span>
  )
}

export { DeltaBadge }
```

### components/ui/period-tabs.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"

export interface PeriodOption {
  value: string
  label: string
}

export const defaultPeriods: PeriodOption[] = [
  { value: "week", label: "Week" },
  { value: "month", label: "Month" },
  { value: "year", label: "Year" },
]

export interface PeriodTabsProps
  extends Omit<React.ComponentProps<typeof Tabs>, "children"> {
  options?: PeriodOption[]
  size?: "sm" | "default"
  /** Slide a single pill between tabs instead of swapping backgrounds. */
  animated?: boolean
}

interface IndicatorRect {
  left: number
  top: number
  width: number
  height: number
}

/** Small segmented control for switching a chart's time range. */
function PeriodTabs({
  options = defaultPeriods,
  size = "sm",
  animated = false,
  className,
  value,
  defaultValue,
  onValueChange,
  ...props
}: PeriodTabsProps) {
  const listRef = React.useRef<HTMLDivElement>(null)
  const [internalValue, setInternalValue] = React.useState(
    defaultValue ?? options[0]?.value
  )
  const active = value ?? internalValue
  const [rect, setRect] = React.useState<IndicatorRect | null>(null)

  const measure = React.useCallback(() => {
    const list = listRef.current
    if (!list) return
    const trigger = list.querySelector<HTMLElement>('[data-state="active"]')
    if (!trigger) return
    setRect({
      left: trigger.offsetLeft,
      top: trigger.offsetTop,
      width: trigger.offsetWidth,
      height: trigger.offsetHeight,
    })
  }, [])

  React.useLayoutEffect(() => {
    if (!animated) return
    measure()
  }, [animated, active, options, size, measure])

  React.useEffect(() => {
    if (!animated || !listRef.current) return
    const observer = new ResizeObserver(measure)
    observer.observe(listRef.current)
    return () => observer.disconnect()
  }, [animated, measure])

  return (
    <Tabs
      data-slot="period-tabs"
      className={cn("w-fit", className)}
      value={value}
      defaultValue={defaultValue}
      onValueChange={(next) => {
        setInternalValue(next)
        onValueChange?.(next)
      }}
      {...props}
    >
      <TabsList
        ref={listRef}
        className={cn(
          "relative",
          size === "sm" && "group-data-[orientation=horizontal]/tabs:h-8 p-1"
        )}
      >
        {animated && rect ? (
          <span
            aria-hidden
            data-slot="period-tabs-indicator"
            className="pointer-events-none absolute rounded-md bg-background shadow-sm transition-[left,top,width,height] duration-300 ease-[cubic-bezier(0.25,1,0.5,1)] motion-reduce:transition-none dark:border dark:border-input dark:bg-input/30"
            style={rect}
          />
        ) : null}
        {options.map((option) => (
          <TabsTrigger
            key={option.value}
            value={option.value}
            className={cn(
              size === "sm" && "h-6 px-2.5 text-xs",
              animated &&
                "relative z-10 data-[state=active]:bg-transparent group-data-[variant=default]/tabs-list:data-[state=active]:shadow-none dark:data-[state=active]:border-transparent dark:data-[state=active]:bg-transparent"
            )}
          >
            {option.label}
          </TabsTrigger>
        ))}
      </TabsList>
    </Tabs>
  )
}

export { PeriodTabs }
```

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Balance Chart Card

A balance or price card with a big value, delta, stat row, and a line chart with reference line and peak marker.

A balance or price card for shadcn/ui: a big value with delta, a row of supporting stats, and a line chart with a reference line and a peak marker. It suits account balances, stock prices, and any headline metric with history.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/balance-chart-card.json
```

Also installs `card`, `chart`, `tooltip` from shadcn/ui if missing.

npm dependencies: `recharts`, `lucide-react`.

## Usage

```tsx
import { BalanceChartCard } from "@/components/balance-chart-card"

<BalanceChartCard
  title="Current balance"
  value={24847.83}
  delta={0.127}
  deltaLabel="Last 24 hours"
  stats={[
    { label: "High", value: 25900.08 },
    { label: "Low", value: 20850.42 },
  ]}
  data={data}
  xKey="time"
  yKey="balance"
  referenceValue={23400}
  referenceLabel="Prev. close"
/>
```

## Examples

### Default

```tsx
import { BalanceChartCard } from "@/registry/dashboardcn/blocks/balance-chart-card"

const data = Array.from({ length: 24 }, (_, hour) => ({
  time: `${String(hour).padStart(2, "0")}:00`,
  balance: 22_000 + Math.round(Math.sin(hour / 3.5) * 1_800 + hour * 110 + (hour === 19 ? 900 : 0)),
}))

export default function BalanceChartCardDemo() {
  return (
    <BalanceChartCard
      className="w-full"
      title="Current balance"
      value={24_847.83}
      delta={0.127}
      deltaLabel="Last 24 hours"
      stats={[
        { label: "Today's sales", value: 1_249, delta: 0.08 },
        { label: "High", value: 25_900.08, color: "var(--color-emerald-500)" },
        { label: "Low", value: 20_850.42, color: "var(--color-red-500)" },
        { label: "Change", value: "-0.062%" },
      ]}
      data={data}
      xKey="time"
      yKey="balance"
      referenceValue={23_400}
      referenceLabel="Prev. close"
    />
  )
}
```

## Source

### components/balance-chart-card.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
import { ComposedChart, type ReferenceLineSpec } from "@/components/ui/composed-chart"
import { DeltaBadge } from "@/components/ui/delta-badge"
import { MetricValue } from "@/components/ui/metric-value"

export interface BalanceStat {
  label: string
  value: number | string
  delta?: number
  format?: NumberFormat
  /** Any CSS color for the value, e.g. emerald for a high. */
  color?: string
}

export interface BalanceChartCardProps extends React.ComponentProps<typeof Card> {
  title: string
  value: number
  delta?: number
  deltaLabel?: string
  format?: NumberFormat
  currency?: string
  stats?: BalanceStat[]
  data: Record<string, unknown>[]
  xKey: string
  yKey: string
  seriesLabel?: string
  /** Horizontal reference, e.g. previous close. */
  referenceValue?: number
  referenceLabel?: string
  /** Mark the highest point. */
  highlightMax?: boolean
  chartClassName?: string
}

/** A balance or price card with a big value, stat row, and line chart. */
function BalanceChartCard({
  title,
  value,
  delta,
  deltaLabel,
  format = "currency",
  currency,
  stats = [],
  data,
  xKey,
  yKey,
  seriesLabel = "Balance",
  referenceValue,
  referenceLabel,
  highlightMax = true,
  chartClassName,
  className,
  ...props
}: BalanceChartCardProps) {
  const yFormatter = React.useCallback(
    (v: number) => formatNumber(v, { format, currency, maximumFractionDigits: 0 }),
    [format, currency]
  )
  const referenceLines: ReferenceLineSpec[] =
    referenceValue !== undefined
      ? [{ y: referenceValue, label: referenceLabel, dashed: true }]
      : []

  return (
    <Card data-slot="balance-chart-card" className={cn("gap-4", className)} {...props}>
      <CardHeader>
        <CardDescription>{title}</CardDescription>
        <CardTitle className="flex flex-wrap items-baseline gap-x-3 gap-y-1 text-3xl font-semibold tabular-nums tracking-tight">
          <MetricValue value={value} format={format} currency={currency} />
          {delta !== undefined ? (
            <span className="flex items-center gap-1.5 text-sm font-normal">
              <DeltaBadge delta={delta} variant="text" />
              {deltaLabel ? (
                <span className="text-muted-foreground">{deltaLabel}</span>
              ) : null}
            </span>
          ) : null}
        </CardTitle>
      </CardHeader>
      {stats.length ? (
        <CardContent className="flex flex-wrap gap-x-6 gap-y-2 text-sm">
          {stats.map((stat) => (
            <div key={stat.label} className="flex items-center gap-1.5">
              <span className="text-muted-foreground">{stat.label}</span>
              <MetricValue
                value={stat.value}
                format={stat.format ?? format}
                currency={currency}
                className="font-medium"
                style={{ color: stat.color }}
              />
              {stat.delta !== undefined ? (
                <DeltaBadge delta={stat.delta} variant="text" showIcon={false} />
              ) : null}
            </div>
          ))}
        </CardContent>
      ) : null}
      <CardContent>
        <ComposedChart
          data={data}
          xKey={xKey}
          series={[{ key: yKey, label: seriesLabel, type: "line", highlightMax }]}
          referenceLines={referenceLines}
          yFormatter={yFormatter}
          yDomain="auto"
          showYAxis
          className={cn("h-56", chartClassName)}
        />
      </CardContent>
    </Card>
  )
}

export { BalanceChartCard }
```

### components/ui/composed-chart.tsx

```tsx
"use client"

import * as React from "react"
import {
  Area,
  Bar,
  CartesianGrid,
  ComposedChart as RechartsComposedChart,
  Line,
  ReferenceDot,
  ReferenceLine,
  XAxis,
  YAxis,
} from "recharts"

import { cn } from "@/lib/utils"
import {
  ChartContainer,
  ChartLegend,
  ChartLegendContent,
  ChartTooltip,
  ChartTooltipContent,
  type ChartConfig,
} from "@/components/ui/chart"

export interface ComposedSeries {
  /** Key in each data row. */
  key: string
  label: string
  type?: "area" | "line" | "bar"
  /** Any CSS color. Defaults to chart-1 through chart-5 in order. */
  color?: string
  /** Plot against the right axis. */
  axis?: "left" | "right"
  /** Series with the same stackId stack on top of each other. */
  stackId?: string
  /** Bars only: fill with a diagonal hatch instead of a solid color. */
  pattern?: "solid" | "hatched"
  /** Lines and areas only. */
  dashed?: boolean
  curve?: "monotone" | "linear" | "step"
  /** Lines only: draw a dot on every point. */
  dots?: boolean
  /** Mark the highest point of this series with a dot. */
  highlightMax?: boolean
}

export interface ReferenceLineSpec {
  /** Horizontal line at this y value. */
  y?: number
  /** Vertical line at this x value. */
  x?: string | number
  label?: string
  /** Any CSS color. Defaults to the muted foreground. */
  color?: string
  dashed?: boolean
  axis?: "left" | "right"
}

export interface ComposedChartProps
  extends Omit<React.ComponentProps<typeof ChartContainer>, "config" | "children"> {
  data: Record<string, unknown>[]
  /** Key of the x-axis value in each row. */
  xKey: string
  series: ComposedSeries[]
  referenceLines?: ReferenceLineSpec[]
  showGrid?: boolean
  showYAxis?: boolean
  showLegend?: boolean
  showTooltip?: boolean
  xFormatter?: (value: unknown) => string
  yFormatter?: (value: number) => string
  rightYFormatter?: (value: number) => string
  barRadius?: number
  /** "zero" starts the y-axis at 0; "auto" fits it to the data. */
  yDomain?: "zero" | "auto" | [number, number]
}

function defaultXFormatter(value: unknown) {
  if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}/.test(value)) {
    const [y, m, d] = value.split("-").map(Number)
    return new Date(y!, m! - 1, d).toLocaleDateString("en-US", {
      month: "short",
      day: "numeric",
    })
  }
  return String(value)
}

function ComposedChart({
  data,
  xKey,
  series,
  referenceLines = [],
  showGrid = true,
  showYAxis = false,
  showLegend = false,
  showTooltip = true,
  xFormatter = defaultXFormatter,
  yFormatter,
  rightYFormatter,
  barRadius = 4,
  yDomain = "zero",
  className,
  ...props
}: ComposedChartProps) {
  const id = React.useId()
  const config = Object.fromEntries(
    series.map((s, index) => [
      s.key,
      { label: s.label, color: s.color ?? `var(--chart-${(index % 5) + 1})` },
    ])
  ) satisfies ChartConfig
  const hasRightAxis = series.some((s) => s.axis === "right")
  const domain =
    yDomain === "auto" ? (["auto", "auto"] as const) : yDomain === "zero" ? undefined : yDomain

  const maxPoints = series
    .filter((s) => s.highlightMax)
    .map((s) => {
      let best: { x: unknown; y: number } | null = null
      for (const row of data) {
        const y = Number(row[s.key])
        if (Number.isFinite(y) && (!best || y > best.y)) best = { x: row[xKey], y }
      }
      return best ? { ...best, key: s.key, axis: s.axis ?? "left" } : null
    })
    .filter((p): p is NonNullable<typeof p> => p !== null)

  return (
    <ChartContainer
      data-slot="composed-chart"
      config={config}
      className={cn("aspect-auto h-64 w-full", className)}
      {...props}
    >
      <RechartsComposedChart
        data={data}
        margin={{ top: 8, right: hasRightAxis ? 0 : 8, bottom: 0, left: showYAxis ? 0 : 8 }}
      >
        <defs>
          {series.map((s) => (
            <React.Fragment key={s.key}>
              <linearGradient id={`${id}-fill-${s.key}`} x1="0" y1="0" x2="0" y2="1">
                <stop offset="5%" stopColor={`var(--color-${s.key})`} stopOpacity={0.5} />
                <stop offset="95%" stopColor={`var(--color-${s.key})`} stopOpacity={0.05} />
              </linearGradient>
              <pattern
                id={`${id}-hatch-${s.key}`}
                patternUnits="userSpaceOnUse"
                width={6}
                height={6}
                patternTransform="rotate(45)"
              >
                <rect width={6} height={6} fill={`var(--color-${s.key})`} fillOpacity={0.15} />
                <rect width={2} height={6} fill={`var(--color-${s.key})`} />
              </pattern>
            </React.Fragment>
          ))}
        </defs>
        {showGrid ? <CartesianGrid vertical={false} /> : null}
        <XAxis
          dataKey={xKey}
          tickLine={false}
          axisLine={false}
          tickMargin={8}
          minTickGap={32}
          tickFormatter={xFormatter}
        />
        <YAxis
          yAxisId="left"
          domain={domain}
          hide={!showYAxis}
          tickLine={false}
          axisLine={false}
          tickMargin={8}
          width={44}
          tickFormatter={yFormatter}
        />
        {hasRightAxis ? (
          <YAxis
            yAxisId="right"
            orientation="right"
            domain={domain}
            hide={!showYAxis}
            tickLine={false}
            axisLine={false}
            tickMargin={8}
            width={44}
            tickFormatter={rightYFormatter ?? yFormatter}
          />
        ) : null}
        {showTooltip ? (
          <ChartTooltip
            cursor={false}
            content={
              <ChartTooltipContent
                indicator="dot"
                labelFormatter={(value) => xFormatter(value)}
                formatter={(value, name, item) => {
                  const s = series.find((entry) => entry.key === name)
                  const fmt = s?.axis === "right" ? (rightYFormatter ?? yFormatter) : yFormatter
                  return (
                    <div className="flex w-full items-center gap-2">
                      <span
                        className="size-2 shrink-0 rounded-[2px]"
                        style={{ backgroundColor: item.color }}
                      />
                      <span className="text-muted-foreground flex-1">
                        {config[name as string]?.label ?? name}
                      </span>
                      <span className="font-mono font-medium tabular-nums">
                        {fmt ? fmt(Number(value)) : String(value)}
                      </span>
                    </div>
                  )
                }}
              />
            }
          />
        ) : null}
        {showLegend ? <ChartLegend content={<ChartLegendContent />} /> : null}
        {series.map((s) => {
          const color = `var(--color-${s.key})`
          const common = {
            dataKey: s.key,
            yAxisId: s.axis ?? "left",
            stackId: s.stackId,
            isAnimationActive: false,
          }
          if (s.type === "bar") {
            return (
              <Bar
                key={s.key}
                {...common}
                fill={s.pattern === "hatched" ? `url(#${id}-hatch-${s.key})` : color}
                stroke={s.pattern === "hatched" ? color : undefined}
                strokeWidth={s.pattern === "hatched" ? 1 : 0}
                radius={s.stackId ? 0 : barRadius}
              />
            )
          }
          if (s.type === "line") {
            return (
              <Line
                key={s.key}
                {...common}
                type={s.curve ?? "monotone"}
                stroke={color}
                strokeWidth={2}
                strokeDasharray={s.dashed ? "4 4" : undefined}
                dot={s.dots ? { r: 3, fill: color, strokeWidth: 0 } : false}
                activeDot={{ r: 4 }}
              />
            )
          }
          return (
            <Area
              key={s.key}
              {...common}
              type={s.curve ?? "monotone"}
              stroke={color}
              strokeWidth={2}
              strokeDasharray={s.dashed ? "4 4" : undefined}
              fill={`url(#${id}-fill-${s.key})`}
              dot={false}
            />
          )
        })}
        {referenceLines.map((line, index) => (
          <ReferenceLine
            key={index}
            y={line.y}
            x={line.x}
            yAxisId={line.axis ?? "left"}
            stroke={line.color ?? "var(--muted-foreground)"}
            strokeDasharray={line.dashed === false ? undefined : "4 4"}
            label={
              line.label
                ? {
                    value: line.label,
                    position: line.y !== undefined ? "insideTopRight" : "insideTopLeft",
                    fill: line.color ?? "var(--muted-foreground)",
                    fontSize: 11,
                  }
                : undefined
            }
          />
        ))}
        {maxPoints.map((point) => (
          <ReferenceDot
            key={point.key}
            x={point.x as string | number}
            y={point.y}
            yAxisId={point.axis}
            r={4}
            fill={`var(--color-${point.key})`}
            stroke="var(--background)"
            strokeWidth={2}
          />
        ))}
      </RechartsComposedChart>
    </ChartContainer>
  )
}

export { ComposedChart }
```

### components/ui/delta-badge.tsx

```tsx
import * as React from "react"
import { Minus, TrendingDown, TrendingUp } from "lucide-react"

import { cn } from "@/lib/utils"
import { formatDelta } from "@/lib/format"

export type DeltaDirection = "up" | "down" | "flat"

export function getDeltaDirection(delta: number | undefined): DeltaDirection {
  if (delta === undefined || delta === 0 || !Number.isFinite(delta)) return "flat"
  return delta > 0 ? "up" : "down"
}

const directionIcon: Record<DeltaDirection, React.ElementType> = {
  up: TrendingUp,
  down: TrendingDown,
  flat: Minus,
}

export interface DeltaBadgeProps extends React.ComponentProps<"span"> {
  /** Fractional change, e.g. 0.124 for +12.4%. */
  delta: number
  /** Treat a decrease as good and an increase as bad (churn, latency, errors). */
  invert?: boolean
  variant?: "outline" | "soft" | "text"
  showIcon?: boolean
}

function DeltaBadge({
  delta,
  invert = false,
  variant = "outline",
  showIcon = true,
  className,
  children,
  ...props
}: DeltaBadgeProps) {
  const direction = getDeltaDirection(delta)
  const positive = direction === "flat" ? null : (direction === "up") !== invert
  const Icon = directionIcon[direction]

  return (
    <span
      data-slot="delta-badge"
      data-direction={direction}
      data-positive={positive}
      className={cn(
        "inline-flex items-center gap-1 text-xs font-medium tabular-nums",
        variant === "outline" && "rounded-md border px-1.5 py-0.5",
        variant === "soft" && "rounded-md px-1.5 py-0.5",
        variant === "soft" && positive === true && "bg-emerald-500/10",
        variant === "soft" && positive === false && "bg-red-500/10",
        variant === "soft" && positive === null && "bg-muted",
        positive === true && "text-emerald-600 dark:text-emerald-400",
        positive === false && "text-red-600 dark:text-red-400",
        positive === null && "text-muted-foreground",
        className
      )}
      {...props}
    >
      {showIcon ? <Icon className="size-3" aria-hidden="true" /> : null}
      {children ?? formatDelta(delta)}
    </span>
  )
}

export { DeltaBadge }
```

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Breakdown Card

A total with delta and a list of contributors, each with a value and a hatched bar showing its share.

A total with delta and a list of contributors, each with a value and a hatched bar showing its share. A lighter alternative to a pie chart for gross volume, revenue mix, or cost breakdowns.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/breakdown-card.json
```

Also installs `card`, `tooltip` from shadcn/ui if missing.

npm dependencies: `lucide-react`.

## Usage

```tsx
import { BreakdownCard } from "@/components/breakdown-card"

<BreakdownCard
  title="Gross volume"
  total={41540}
  delta={0.15}
  items={[
    { name: "Online payments", value: 26800, color: "var(--color-emerald-500)" },
    { name: "Subscriptions", value: 10400, color: "var(--color-blue-500)" },
    { name: "In-store sales", value: 4340, color: "var(--color-pink-500)" },
  ]}
/>
```

## Examples

### Default

```tsx
import { Ellipsis } from "lucide-react"

import { Button } from "@/components/ui/button"
import { BreakdownCard } from "@/registry/dashboardcn/blocks/breakdown-card"

export default function BreakdownCardDemo() {
  return (
    <BreakdownCard
      className="w-full max-w-sm"
      title="Gross volume"
      action={
        <Button variant="outline" size="icon-sm" className="text-muted-foreground rounded-full">
          <Ellipsis />
          <span className="sr-only">More</span>
        </Button>
      }
      total={41_540}
      delta={0.15}
      items={[
        { name: "Online payments", value: 26_800, color: "var(--color-emerald-500)" },
        { name: "Subscriptions", value: 10_400, color: "var(--color-blue-500)" },
        { name: "In-store sales", value: 4_340, color: "var(--color-pink-500)" },
      ]}
    />
  )
}
```

## Source

### components/breakdown-card.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { type NumberFormat } from "@/lib/format"
import {
  Card,
  CardAction,
  CardContent,
  CardHeader,
  CardTitle,
} from "@/components/ui/card"
import { DeltaBadge } from "@/components/ui/delta-badge"
import { MetricValue } from "@/components/ui/metric-value"

export interface BreakdownCardItem {
  name: string
  value: number
  /** Any CSS color for the bar. Defaults to chart-1 through chart-5 in order. */
  color?: string
}

export interface BreakdownCardProps extends React.ComponentProps<typeof Card> {
  title: string
  /** Slot in the top-right corner, e.g. a menu button. */
  action?: React.ReactNode
  items: BreakdownCardItem[]
  /** Headline total. Defaults to the sum of the items. */
  total?: number
  /** Fractional change vs the prior period, e.g. 0.15 for +15%. */
  delta?: number
  /** Treat a decrease as good. */
  invertDelta?: boolean
  format?: NumberFormat
  currency?: string
  /** Bars fill relative to this. Defaults to the total. */
  max?: number
  /** Fill the bars with diagonal stripes or a solid color. */
  pattern?: "hatched" | "solid"
}

const defaultColors = [
  "var(--chart-1)",
  "var(--chart-2)",
  "var(--chart-3)",
  "var(--chart-4)",
  "var(--chart-5)",
]

/** A total with delta and a list of contributors, each with a value and a hatched bar showing its share. */
function BreakdownCard({
  title,
  action,
  items,
  total,
  delta,
  invertDelta,
  format = "currency",
  currency = "USD",
  max,
  pattern = "hatched",
  className,
  ...props
}: BreakdownCardProps) {
  const sum = total ?? items.reduce((acc, item) => acc + item.value, 0)
  const scale = max ?? sum

  return (
    <Card data-slot="breakdown-card" className={cn("gap-5", className)} {...props}>
      <CardHeader>
        <CardTitle className="text-base">{title}</CardTitle>
        {action ? <CardAction>{action}</CardAction> : null}
      </CardHeader>
      <CardContent className="flex flex-col gap-5">
        <div className="flex flex-wrap items-center gap-3">
          <MetricValue
            value={sum}
            format={format}
            currency={currency}
            maximumFractionDigits={0}
            className="text-4xl font-semibold tracking-tight"
          />
          {delta !== undefined ? (
            <DeltaBadge delta={delta} invert={invertDelta} variant="soft" className="rounded-full px-2 py-1" />
          ) : null}
        </div>
        <ul className="flex flex-col gap-6 border-t pt-5">
          {items.map((item, index) => {
            const color = item.color ?? defaultColors[index % defaultColors.length]
            const fraction = Math.min(1, Math.max(0, item.value / (scale || 1)))
            return (
              <li key={item.name} data-slot="breakdown-card-item" className="flex flex-col gap-2">
                <div className="flex items-baseline justify-between gap-4 text-sm">
                  <span className="text-muted-foreground min-w-0 truncate">{item.name}</span>
                  <MetricValue
                    value={item.value}
                    format={format}
                    currency={currency}
                    maximumFractionDigits={0}
                    className="shrink-0 font-semibold"
                  />
                </div>
                <div
                  role="progressbar"
                  aria-label={item.name}
                  aria-valuemin={0}
                  aria-valuemax={scale}
                  aria-valuenow={item.value}
                  className="bg-muted h-2.5 w-full overflow-hidden rounded-full"
                >
                  <div
                    data-pattern={pattern}
                    className="h-full rounded-full transition-[width]"
                    style={{
                      width: `${fraction * 100}%`,
                      backgroundColor:
                        pattern === "hatched"
                          ? `color-mix(in oklab, ${color} 35%, transparent)`
                          : color,
                      backgroundImage:
                        pattern === "hatched"
                          ? `repeating-linear-gradient(135deg, ${color} 0 2px, transparent 2px 5px)`
                          : undefined,
                    }}
                  />
                </div>
              </li>
            )
          })}
        </ul>
      </CardContent>
    </Card>
  )
}

export { BreakdownCard }
```

### components/ui/delta-badge.tsx

```tsx
import * as React from "react"
import { Minus, TrendingDown, TrendingUp } from "lucide-react"

import { cn } from "@/lib/utils"
import { formatDelta } from "@/lib/format"

export type DeltaDirection = "up" | "down" | "flat"

export function getDeltaDirection(delta: number | undefined): DeltaDirection {
  if (delta === undefined || delta === 0 || !Number.isFinite(delta)) return "flat"
  return delta > 0 ? "up" : "down"
}

const directionIcon: Record<DeltaDirection, React.ElementType> = {
  up: TrendingUp,
  down: TrendingDown,
  flat: Minus,
}

export interface DeltaBadgeProps extends React.ComponentProps<"span"> {
  /** Fractional change, e.g. 0.124 for +12.4%. */
  delta: number
  /** Treat a decrease as good and an increase as bad (churn, latency, errors). */
  invert?: boolean
  variant?: "outline" | "soft" | "text"
  showIcon?: boolean
}

function DeltaBadge({
  delta,
  invert = false,
  variant = "outline",
  showIcon = true,
  className,
  children,
  ...props
}: DeltaBadgeProps) {
  const direction = getDeltaDirection(delta)
  const positive = direction === "flat" ? null : (direction === "up") !== invert
  const Icon = directionIcon[direction]

  return (
    <span
      data-slot="delta-badge"
      data-direction={direction}
      data-positive={positive}
      className={cn(
        "inline-flex items-center gap-1 text-xs font-medium tabular-nums",
        variant === "outline" && "rounded-md border px-1.5 py-0.5",
        variant === "soft" && "rounded-md px-1.5 py-0.5",
        variant === "soft" && positive === true && "bg-emerald-500/10",
        variant === "soft" && positive === false && "bg-red-500/10",
        variant === "soft" && positive === null && "bg-muted",
        positive === true && "text-emerald-600 dark:text-emerald-400",
        positive === false && "text-red-600 dark:text-red-400",
        positive === null && "text-muted-foreground",
        className
      )}
      {...props}
    >
      {showIcon ? <Icon className="size-3" aria-hidden="true" /> : null}
      {children ?? formatDelta(delta)}
    </span>
  )
}

export { DeltaBadge }
```

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Contributions Card

A contribution-graph card: a headline total with delta, a row of stat tiles, a period switcher, and a year of daily activity.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/contributions-card.json
```

Also installs `card`, `tabs`, `tooltip` from shadcn/ui if missing.

npm dependencies: `lucide-react`.

## Usage

```tsx
import { ContributionsCard } from "@/components/contributions-card"

<ContributionsCard
  title="Contributions this year"
  delta={0.148}
  deltaLabel="vs last year"
  stats={[
    { label: "Lifetime tokens", value: 9000000000, format: "compact" },
    { label: "Longest task", value: "12h 54m" },
    { label: "Top streak", value: 62, unit: "days" },
  ]}
  periods={[
    { value: "month", label: "Monthly" },
    { value: "year", label: "Yearly" },
  ]}
  data={[
    { date: "2026-09-01", value: 12 },
    { date: "2026-09-02", value: 3 },
  ]}
  unit="commits"
/>
```

## Examples

### Default

```tsx
import { ContributionsCard } from "@/registry/dashboardcn/blocks/contributions-card"

// Deterministic sample data so the demo is stable between renders.
function sampleData(days: number, end: Date) {
  let seed = 7
  const random = () => {
    seed = (seed * 1664525 + 1013904223) % 4294967296
    return seed / 4294967296
  }
  return Array.from({ length: days }, (_, i) => {
    const date = new Date(end)
    date.setDate(end.getDate() - (days - 1 - i))
    const weekend = date.getDay() === 0 || date.getDay() === 6
    const value = random() < (weekend ? 0.6 : 0.2) ? 0 : Math.round(random() * (weekend ? 3 : 9))
    const key = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`
    return { date: key, value }
  })
}

const end = new Date(2026, 8, 2)
const data = sampleData(365, end)

export default function ContributionsCardDemo() {
  return (
    <ContributionsCard
      className="w-full"
      title="Contributions this year"
      delta={0.148}
      deltaLabel="vs last year"
      stats={[
        { label: "Lifetime tokens", value: 9_000_000_000, format: "compact" },
        { label: "Peak tokens", value: 562_700_000, format: "compact" },
        { label: "Longest task", value: "12h 54m" },
        { label: "Top streak", value: 62, unit: "days" },
      ]}
      periods={[
        { value: "week", label: "Weekly" },
        { value: "month", label: "Monthly" },
        { value: "year", label: "Yearly" },
      ]}
      defaultPeriod="year"
      data={data}
      endDate={end}
      color="var(--color-violet-500)"
      unit="contributions"
    />
  )
}
```

## Source

### components/contributions-card.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@/components/ui/card"
import {
  ActivityHeatmap,
  type ActivityHeatmapProps,
} from "@/components/ui/activity-heatmap"
import { DeltaBadge } from "@/components/ui/delta-badge"
import { MetricValue } from "@/components/ui/metric-value"
import { PeriodTabs, type PeriodOption } from "@/components/ui/period-tabs"

export interface ContributionsStat {
  label: string
  /** Numbers are formatted with `format`; strings render as-is, e.g. "12h 54m". */
  value: number | string
  format?: NumberFormat
  currency?: string
  /** Suffix after the number, e.g. "days". */
  unit?: string
}

export interface ContributionsCardProps
  extends Omit<React.ComponentProps<typeof Card>, "children"> {
  title: string
  /** Headline number. Defaults to the sum of `data`. */
  value?: number
  format?: NumberFormat
  currency?: string
  /** Change vs the previous period, as a fraction. */
  delta?: number
  deltaLabel?: string
  invertDelta?: boolean
  /** Tiles between the headline and the heatmap. */
  stats?: ContributionsStat[]
  /** Label above the heatmap, e.g. "Activity". */
  heatmapLabel?: string
  /** Options for the switcher next to the heatmap label. Omit to hide it. */
  periods?: PeriodOption[]
  period?: string
  defaultPeriod?: string
  onPeriodChange?: (period: string) => void
  data: ActivityHeatmapProps["data"]
  endDate?: ActivityHeatmapProps["endDate"]
  weeks?: ActivityHeatmapProps["weeks"]
  startDate?: ActivityHeatmapProps["startDate"]
  /** Any CSS color for the heatmap. Defaults to chart-1. */
  color?: ActivityHeatmapProps["color"]
  colors?: ActivityHeatmapProps["colors"]
  scale?: ActivityHeatmapProps["scale"]
  cellSize?: ActivityHeatmapProps["cellSize"]
  gap?: ActivityHeatmapProps["gap"]
  /** Label for the value in the tooltip, e.g. "commits". */
  unit?: ActivityHeatmapProps["unit"]
  weekdayLabels?: ActivityHeatmapProps["weekdayLabels"]
  showLegend?: ActivityHeatmapProps["showLegend"]
  valueFormatter?: ActivityHeatmapProps["valueFormatter"]
  onCellClick?: ActivityHeatmapProps["onCellClick"]
  /** Slot in the top-right corner, e.g. a menu button. */
  action?: React.ReactNode
}

/** A contribution-graph card: a headline total with delta, a row of stat tiles, and a year of daily activity. */
function ContributionsCard({
  title,
  value,
  format = "number",
  currency,
  delta,
  deltaLabel,
  invertDelta,
  stats,
  heatmapLabel = "Activity",
  periods,
  period,
  defaultPeriod,
  onPeriodChange,
  data,
  endDate,
  weeks,
  startDate,
  color,
  colors,
  scale,
  cellSize = 11,
  gap = 3,
  unit = "contributions",
  weekdayLabels = "none",
  showLegend = false,
  valueFormatter,
  onCellClick,
  action,
  className,
  ...props
}: ContributionsCardProps) {
  const total = React.useMemo(
    () => value ?? data.reduce((sum, datum) => sum + datum.value, 0),
    [value, data]
  )

  return (
    <Card
      data-slot="contributions-card"
      className={cn("@container/card gap-5", className)}
      {...props}
    >
      <CardHeader>
        <CardDescription>{title}</CardDescription>
        <CardTitle className="flex flex-wrap items-center gap-2 text-3xl font-semibold tabular-nums tracking-tight">
          <MetricValue value={total} format={format} currency={currency} />
          {delta !== undefined ? (
            <DeltaBadge delta={delta} invert={invertDelta} variant="soft" className="text-sm" />
          ) : null}
        </CardTitle>
        {deltaLabel ? <CardDescription>{deltaLabel}</CardDescription> : null}
        {action ? <CardAction>{action}</CardAction> : null}
      </CardHeader>
      <CardContent className="flex flex-col gap-5">
        {stats?.length ? (
          <dl className="grid grid-cols-2 gap-2 @md/card:grid-cols-4">
            {stats.map((stat) => (
              <div
                key={stat.label}
                className="flex min-w-0 flex-col gap-0.5 rounded-lg border px-3 py-2.5"
              >
                <dd className="order-1 truncate text-lg font-semibold tabular-nums tracking-tight">
                  {typeof stat.value === "number"
                    ? formatNumber(stat.value, {
                        format: stat.format,
                        currency: stat.currency,
                        maximumFractionDigits: stat.format ? undefined : 1,
                      })
                    : stat.value}
                  {stat.unit ? (
                    <span className="text-muted-foreground ml-1 text-sm font-normal">
                      {stat.unit}
                    </span>
                  ) : null}
                </dd>
                <dt className="text-muted-foreground order-2 truncate text-xs">{stat.label}</dt>
              </div>
            ))}
          </dl>
        ) : null}
        <div className="flex flex-col gap-3">
          {heatmapLabel || periods?.length ? (
            <div className="flex items-center justify-between gap-3">
              {heatmapLabel ? (
                <span className="text-sm font-medium">{heatmapLabel}</span>
              ) : null}
              {periods?.length ? (
                <PeriodTabs
                  options={periods}
                  value={period}
                  defaultValue={defaultPeriod}
                  onValueChange={onPeriodChange}
                />
              ) : null}
            </div>
          ) : null}
          <ActivityHeatmap
            data={data}
            endDate={endDate}
            weeks={weeks}
            startDate={startDate}
            color={color}
            colors={colors}
            scale={scale}
            cellSize={cellSize}
            gap={gap}
            unit={unit}
            weekdayLabels={weekdayLabels}
            showLegend={showLegend}
            valueFormatter={valueFormatter}
            onCellClick={onCellClick}
          />
        </div>
      </CardContent>
    </Card>
  )
}

export { ContributionsCard }
```

### components/ui/activity-heatmap.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

export interface ActivityDatum {
  /** ISO date, YYYY-MM-DD. */
  date: string
  value: number
}

export interface ActivityHeatmapProps extends React.ComponentProps<"div"> {
  data: ActivityDatum[]
  /** Last day shown. Defaults to today. */
  endDate?: Date
  /** Number of week columns. Ignored when `startDate` is set. */
  weeks?: number
  /** First day shown. Overrides `weeks`. */
  startDate?: Date
  /** Any CSS color. Levels are mixed from this and `--muted`. Defaults to chart-1. */
  color?: string
  /**
   * Explicit color per level, from empty to most active.
   * Overrides `color`. Length sets the number of levels.
   */
  colors?: string[]
  /** How values map to levels. `sqrt` spreads out small values. */
  scale?: "linear" | "sqrt"
  /** Cell size in px. */
  cellSize?: number
  /** Gap between cells in px. */
  gap?: number
  valueFormatter?: (value: number) => string
  /** Label for the value in the tooltip, e.g. "events". */
  unit?: string
  showMonthLabels?: boolean
  /** Which weekday labels to show along the left edge. */
  weekdayLabels?: "mwf" | "all" | "none"
  showLegend?: boolean
  /** Scroll to the most recent weeks when the grid overflows. */
  scrollToEnd?: boolean
  /** Replace the tooltip body. Return `null` to hide it for that cell. */
  renderTooltip?: (datum: { date: Date; value: number }) => React.ReactNode
  onCellClick?: (datum: { date: Date; value: number }) => void
}

const DAY = 24 * 60 * 60 * 1000
const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]

function toKey(date: Date) {
  const y = date.getFullYear()
  const m = String(date.getMonth() + 1).padStart(2, "0")
  const d = String(date.getDate()).padStart(2, "0")
  return `${y}-${m}-${d}`
}

function startOfDay(date: Date) {
  return new Date(date.getFullYear(), date.getMonth(), date.getDate())
}

function addDays(date: Date, days: number) {
  return new Date(date.getTime() + days * DAY)
}

function levelFor(
  value: number,
  max: number,
  levels: number,
  scale: "linear" | "sqrt"
) {
  if (value <= 0 || max <= 0) return 0
  let t = value / max
  if (scale === "sqrt") t = Math.sqrt(t)
  return Math.min(levels - 1, Math.max(1, Math.ceil(t * (levels - 1))))
}

function mixedColors(color: string, levels: number) {
  return Array.from({ length: levels }, (_, level) => {
    if (level === 0) return "var(--muted)"
    const pct = Math.round(25 + ((level - 1) / (levels - 2)) * 75)
    return `color-mix(in oklab, ${color} ${pct}%, var(--muted))`
  })
}

function ActivityHeatmap({
  data,
  endDate,
  weeks = 52,
  startDate,
  color = "var(--chart-1)",
  colors,
  scale = "linear",
  cellSize = 12,
  gap = 3,
  valueFormatter = (value) => formatNumber(value),
  unit = "events",
  showMonthLabels = true,
  weekdayLabels = "mwf",
  showLegend = true,
  scrollToEnd = true,
  renderTooltip,
  onCellClick,
  className,
  ...props
}: ActivityHeatmapProps) {
  const endTime = startOfDay(endDate ?? new Date()).getTime()
  const startTime = startDate
    ? startOfDay(startDate).getTime()
    : endTime - (weeks * 7 - 1) * DAY

  const values = React.useMemo(
    () => new Map(data.map((d) => [d.date, d.value])),
    [data]
  )
  const max = React.useMemo(
    () => data.reduce((acc, d) => Math.max(acc, d.value), 0),
    [data]
  )

  // Columns are full weeks, Sunday first. Days before `start` in the first
  // week and after `end` in the last are left empty rather than filled in.
  const columns = React.useMemo(() => {
    const start = new Date(startTime)
    const end = new Date(endTime)
    const result: (Date | null)[][] = []
    let cursor = addDays(start, -start.getDay())
    while (cursor <= end) {
      const week: (Date | null)[] = []
      for (let i = 0; i < 7; i++) {
        const day = addDays(cursor, i)
        week.push(day < start || day > end ? null : day)
      }
      result.push(week)
      cursor = addDays(cursor, 7)
    }
    return result
  }, [startTime, endTime])

  // Month labels span the weeks whose first shown day falls in that month.
  const months = React.useMemo(() => {
    const groups: { label: string; from: number; to: number }[] = []
    const formatter = new Intl.DateTimeFormat("en-US", { month: "short" })
    columns.forEach((week, index) => {
      const first = week.find((d): d is Date => d !== null)
      if (!first) return
      const key = `${first.getFullYear()}-${first.getMonth()}`
      const last = groups[groups.length - 1]
      if (last && last.label === key) {
        last.to = index
      } else {
        groups.push({ label: key, from: index, to: index })
      }
    })
    return groups
      .filter((g) => g.to - g.from >= 1)
      .map((g) => ({
        ...g,
        label: formatter.format(columns[g.from]!.find(Boolean) as Date),
      }))
  }, [columns])

  const palette = colors && colors.length > 1 ? colors : mixedColors(color, 5)
  const levels = palette.length

  const dateFormatter = new Intl.DateTimeFormat("en-US", {
    weekday: "short",
    month: "short",
    day: "numeric",
    year: "numeric",
  })

  const scrollRef = React.useRef<HTMLDivElement>(null)
  React.useLayoutEffect(() => {
    const node = scrollRef.current
    if (!node || !scrollToEnd) return
    node.scrollLeft = node.scrollWidth
  }, [scrollToEnd, columns.length, cellSize, gap])

  const hasHeader = showMonthLabels
  const hasWeekdays = weekdayLabels !== "none"
  const fontSize = Math.max(10, Math.min(12, cellSize))

  return (
    <div
      data-slot="activity-heatmap"
      className={cn("flex min-w-0 flex-col gap-2 text-xs", className)}
      {...props}
    >
      <div className="flex min-w-0">
        {hasWeekdays ? (
          <div
            aria-hidden
            className="grid shrink-0 pr-1"
            style={{
              gap,
              gridTemplateRows: `${hasHeader ? `${fontSize}px` : "0px"} repeat(7, ${cellSize}px)`,
            }}
          >
            <div />
            {WEEKDAYS.map((day, index) => (
              <div
                key={day}
                className="text-muted-foreground flex items-center leading-none whitespace-nowrap"
                style={{ fontSize }}
              >
                {weekdayLabels === "all" || index % 2 === 1 ? day : ""}
              </div>
            ))}
          </div>
        ) : null}
        <div
          ref={scrollRef}
          className="min-w-0 flex-1 overflow-x-auto overscroll-x-contain [scrollbar-width:thin]"
        >
          <TooltipProvider delayDuration={100} skipDelayDuration={0}>
            <div
              role="group"
              aria-label="Activity heatmap"
              className="grid w-max"
              style={{
                gap,
                gridTemplateColumns: `repeat(${columns.length}, ${cellSize}px)`,
                gridTemplateRows: `${hasHeader ? `${fontSize}px` : "0px"} repeat(7, ${cellSize}px)`,
              }}
            >
              {hasHeader
                ? months.map((month) => (
                    <div
                      key={`${month.from}-${month.label}`}
                      className="text-muted-foreground self-end leading-none whitespace-nowrap"
                      style={{
                        gridRow: 1,
                        gridColumn: `${month.from + 1} / ${month.to + 2}`,
                        fontSize,
                      }}
                    >
                      {month.label}
                    </div>
                  ))
                : null}

              {columns.map((week, weekIndex) =>
                week.map((day, dayIndex) => {
                  const style = {
                    gridColumn: weekIndex + 1,
                    gridRow: dayIndex + 2,
                  }
                  if (!day) {
                    return <div key={dayIndex} aria-hidden style={style} />
                  }
                  const value = values.get(toKey(day)) ?? 0
                  const level = levelFor(value, max, levels, scale)
                  const datum = { date: day, value }
                  const body = renderTooltip ? (
                    renderTooltip(datum)
                  ) : (
                    <>
                      <span className="font-medium tabular-nums">
                        {valueFormatter(value)} {unit}
                      </span>
                      <span className="text-background/70 block">
                        {dateFormatter.format(day)}
                      </span>
                    </>
                  )
                  const label = `${valueFormatter(value)} ${unit} on ${dateFormatter.format(day)}`

                  const cell = (
                    <button
                      type="button"
                      aria-label={label}
                      data-level={level}
                      data-date={toKey(day)}
                      onClick={onCellClick ? () => onCellClick(datum) : undefined}
                      className={cn(
                        "focus-visible:ring-ring/60 ring-inset rounded-[2px] outline-none transition-[filter] duration-100 hover:brightness-110 focus-visible:ring-2 dark:hover:brightness-125",
                        "inset-ring-foreground/6 inset-ring",
                        onCellClick ? "cursor-pointer" : "cursor-default"
                      )}
                      style={{ ...style, backgroundColor: palette[level] }}
                    />
                  )

                  if (body === null) {
                    return <React.Fragment key={dayIndex}>{cell}</React.Fragment>
                  }

                  return (
                    <Tooltip key={dayIndex}>
                      <TooltipTrigger asChild>{cell}</TooltipTrigger>
                      <TooltipContent sideOffset={4} className="text-left">
                        {body}
                      </TooltipContent>
                    </Tooltip>
                  )
                })
              )}
            </div>
          </TooltipProvider>
        </div>
      </div>

      {showLegend ? (
        <div
          className="text-muted-foreground flex items-center justify-end gap-1"
          style={{ fontSize }}
        >
          <span className="mr-0.5">Less</span>
          {palette.map((fill, level) => (
            <span
              key={level}
              className="inset-ring-foreground/6 inset-ring rounded-[2px]"
              style={{
                width: cellSize,
                height: cellSize,
                backgroundColor: fill,
              }}
            />
          ))}
          <span className="ml-0.5">More</span>
        </div>
      ) : null}
    </div>
  )
}

export { ActivityHeatmap }
```

### components/ui/delta-badge.tsx

```tsx
import * as React from "react"
import { Minus, TrendingDown, TrendingUp } from "lucide-react"

import { cn } from "@/lib/utils"
import { formatDelta } from "@/lib/format"

export type DeltaDirection = "up" | "down" | "flat"

export function getDeltaDirection(delta: number | undefined): DeltaDirection {
  if (delta === undefined || delta === 0 || !Number.isFinite(delta)) return "flat"
  return delta > 0 ? "up" : "down"
}

const directionIcon: Record<DeltaDirection, React.ElementType> = {
  up: TrendingUp,
  down: TrendingDown,
  flat: Minus,
}

export interface DeltaBadgeProps extends React.ComponentProps<"span"> {
  /** Fractional change, e.g. 0.124 for +12.4%. */
  delta: number
  /** Treat a decrease as good and an increase as bad (churn, latency, errors). */
  invert?: boolean
  variant?: "outline" | "soft" | "text"
  showIcon?: boolean
}

function DeltaBadge({
  delta,
  invert = false,
  variant = "outline",
  showIcon = true,
  className,
  children,
  ...props
}: DeltaBadgeProps) {
  const direction = getDeltaDirection(delta)
  const positive = direction === "flat" ? null : (direction === "up") !== invert
  const Icon = directionIcon[direction]

  return (
    <span
      data-slot="delta-badge"
      data-direction={direction}
      data-positive={positive}
      className={cn(
        "inline-flex items-center gap-1 text-xs font-medium tabular-nums",
        variant === "outline" && "rounded-md border px-1.5 py-0.5",
        variant === "soft" && "rounded-md px-1.5 py-0.5",
        variant === "soft" && positive === true && "bg-emerald-500/10",
        variant === "soft" && positive === false && "bg-red-500/10",
        variant === "soft" && positive === null && "bg-muted",
        positive === true && "text-emerald-600 dark:text-emerald-400",
        positive === false && "text-red-600 dark:text-red-400",
        positive === null && "text-muted-foreground",
        className
      )}
      {...props}
    >
      {showIcon ? <Icon className="size-3" aria-hidden="true" /> : null}
      {children ?? formatDelta(delta)}
    </span>
  )
}

export { DeltaBadge }
```

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### components/ui/period-tabs.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"

export interface PeriodOption {
  value: string
  label: string
}

export const defaultPeriods: PeriodOption[] = [
  { value: "week", label: "Week" },
  { value: "month", label: "Month" },
  { value: "year", label: "Year" },
]

export interface PeriodTabsProps
  extends Omit<React.ComponentProps<typeof Tabs>, "children"> {
  options?: PeriodOption[]
  size?: "sm" | "default"
  /** Slide a single pill between tabs instead of swapping backgrounds. */
  animated?: boolean
}

interface IndicatorRect {
  left: number
  top: number
  width: number
  height: number
}

/** Small segmented control for switching a chart's time range. */
function PeriodTabs({
  options = defaultPeriods,
  size = "sm",
  animated = false,
  className,
  value,
  defaultValue,
  onValueChange,
  ...props
}: PeriodTabsProps) {
  const listRef = React.useRef<HTMLDivElement>(null)
  const [internalValue, setInternalValue] = React.useState(
    defaultValue ?? options[0]?.value
  )
  const active = value ?? internalValue
  const [rect, setRect] = React.useState<IndicatorRect | null>(null)

  const measure = React.useCallback(() => {
    const list = listRef.current
    if (!list) return
    const trigger = list.querySelector<HTMLElement>('[data-state="active"]')
    if (!trigger) return
    setRect({
      left: trigger.offsetLeft,
      top: trigger.offsetTop,
      width: trigger.offsetWidth,
      height: trigger.offsetHeight,
    })
  }, [])

  React.useLayoutEffect(() => {
    if (!animated) return
    measure()
  }, [animated, active, options, size, measure])

  React.useEffect(() => {
    if (!animated || !listRef.current) return
    const observer = new ResizeObserver(measure)
    observer.observe(listRef.current)
    return () => observer.disconnect()
  }, [animated, measure])

  return (
    <Tabs
      data-slot="period-tabs"
      className={cn("w-fit", className)}
      value={value}
      defaultValue={defaultValue}
      onValueChange={(next) => {
        setInternalValue(next)
        onValueChange?.(next)
      }}
      {...props}
    >
      <TabsList
        ref={listRef}
        className={cn(
          "relative",
          size === "sm" && "group-data-[orientation=horizontal]/tabs:h-8 p-1"
        )}
      >
        {animated && rect ? (
          <span
            aria-hidden
            data-slot="period-tabs-indicator"
            className="pointer-events-none absolute rounded-md bg-background shadow-sm transition-[left,top,width,height] duration-300 ease-[cubic-bezier(0.25,1,0.5,1)] motion-reduce:transition-none dark:border dark:border-input dark:bg-input/30"
            style={rect}
          />
        ) : null}
        {options.map((option) => (
          <TabsTrigger
            key={option.value}
            value={option.value}
            className={cn(
              size === "sm" && "h-6 px-2.5 text-xs",
              animated &&
                "relative z-10 data-[state=active]:bg-transparent group-data-[variant=default]/tabs-list:data-[state=active]:shadow-none dark:data-[state=active]:border-transparent dark:data-[state=active]:bg-transparent"
            )}
          >
            {option.label}
          </TabsTrigger>
        ))}
      </TabsList>
    </Tabs>
  )
}

export { PeriodTabs }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Data Table Card

A card around a data table: title, description, toolbar, rows, and pagination in the footer.

A card around the data table: title, description, toolbar, rows, and pagination in the footer. It is the table block for shadcn/ui dashboards, ready for a list of customers, orders, or invoices.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/data-table-card.json
```

Also installs `card`, `table`, `button`, `input`, `dropdown-menu`, `checkbox`, `skeleton` from shadcn/ui if missing.

npm dependencies: `@tanstack/react-table`, `lucide-react`.

## Usage

```tsx
import { DataTableCard } from "@/components/data-table-card"

<DataTableCard
  title="Top products"
  description="Units sold and revenue, ranked."
  columns={columns}
  data={products}
  searchKey="product"
  initialSorting={[{ id: "revenue", desc: true }]}
  density="compact"
  pageSize={5}
  pageSizeOptions={[5, 10, 25]}
  toolbar={<PeriodTabs value={period} onValueChange={setPeriod} size="sm" />}
/>
```

## Examples

### Default

```tsx
"use client"

import * as React from "react"
import { Ellipsis } from "lucide-react"

import { Badge } from "@/components/ui/badge"
import { Button } from "@/components/ui/button"
import { formatNumber } from "@/lib/format"
import { DataTableCard } from "@/registry/dashboardcn/blocks/data-table-card"
import {
  DataTableColumnHeader,
  createDataTableColumnHelper,
} from "@/components/ui/data-table"
import { PeriodTabs } from "@/components/ui/period-tabs"

type ProductRow = {
  product: string
  sku: string
  stock: "in stock" | "low" | "out"
  units: number
  refunds: number
  revenue: number
}

const products: ProductRow[] = [
  { product: "Field Notes — 3 pack", sku: "FN-003", stock: "in stock", units: 1_284, refunds: 12, revenue: 19_260 },
  { product: "Enamel mug", sku: "MG-011", stock: "low", units: 942, refunds: 31, revenue: 14_130 },
  { product: "Canvas tote", sku: "TT-204", stock: "in stock", units: 810, refunds: 8, revenue: 12_150 },
  { product: "Sticker sheet", sku: "ST-088", stock: "in stock", units: 764, refunds: 2, revenue: 3_056 },
  { product: "Hoodie — heather", sku: "HD-450", stock: "out", units: 618, refunds: 44, revenue: 37_080 },
  { product: "Cap — six panel", sku: "CP-120", stock: "low", units: 512, revenue: 12_800, refunds: 19 },
  { product: "Water bottle", sku: "WB-330", stock: "in stock", units: 486, refunds: 6, revenue: 14_580 },
  { product: "Socks — two pack", sku: "SK-021", stock: "in stock", units: 402, refunds: 5, revenue: 4_824 },
  { product: "Desk mat", sku: "DM-900", stock: "low", units: 318, refunds: 11, revenue: 12_720 },
  { product: "Pin set", sku: "PN-012", stock: "in stock", units: 254, refunds: 1, revenue: 2_540 },
]

const helper = createDataTableColumnHelper<ProductRow>()

const columns = helper.columns([
  helper.accessor("product", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Product" />
    ),
    cell: ({ row }) => (
      <div className="flex flex-col">
        <span className="font-medium">{row.original.product}</span>
        <span className="text-muted-foreground font-mono text-xs">
          {row.original.sku}
        </span>
      </div>
    ),
  }),
  helper.accessor("stock", {
    header: "Stock",
    cell: ({ row }) => (
      <Badge
        variant={
          row.original.stock === "in stock"
            ? "secondary"
            : row.original.stock === "out"
              ? "destructive"
              : "outline"
        }
      >
        {row.original.stock}
      </Badge>
    ),
  }),
  helper.accessor("units", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Units" align="right" />
    ),
    cell: ({ row }) => (
      <div className="text-right tabular-nums">
        {formatNumber(row.original.units)}
      </div>
    ),
  }),
  helper.accessor("refunds", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Refunds" align="right" />
    ),
    cell: ({ row }) => (
      <div className="text-muted-foreground text-right tabular-nums">
        {formatNumber(row.original.refunds)}
      </div>
    ),
  }),
  helper.accessor("revenue", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Revenue" align="right" />
    ),
    cell: ({ row }) => (
      <div className="text-right tabular-nums">
        {formatNumber(row.original.revenue, { format: "currency", compact: true })}
      </div>
    ),
  }),
])

export default function DataTableCardDemo() {
  const [period, setPeriod] = React.useState("month")

  return (
    <DataTableCard
      className="w-full"
      title="Top products"
      description="Units sold and revenue, ranked."
      action={
        <Button
          variant="outline"
          size="icon-sm"
          className="text-muted-foreground rounded-full"
        >
          <Ellipsis />
          <span className="sr-only">More</span>
        </Button>
      }
      toolbar={
        <PeriodTabs value={period} onValueChange={setPeriod} size="sm" />
      }
      columns={columns}
      data={products}
      searchKey="product"
      searchPlaceholder="Filter products..."
      initialSorting={[{ id: "revenue", desc: true }]}
      density="compact"
      pageSize={5}
      pageSizeOptions={[5, 10, 25]}
    />
  )
}
```

## Source

### components/data-table-card.tsx

```tsx
"use client"

import * as React from "react"
import { type RowData } from "@tanstack/react-table"

import { cn } from "@/lib/utils"
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card"
import {
  DataTableContent,
  DataTablePagination,
  DataTableSearch,
  DataTableSelectionBar,
  DataTableToolbar,
  DataTableViewOptions,
  useDataTable,
  type DataTableContentProps,
  type UseDataTableOptions,
} from "@/components/ui/data-table"

export interface DataTableCardProps<TData extends RowData>
  extends Omit<React.ComponentProps<typeof Card>, "title" | "onSelect">,
    UseDataTableOptions<TData>,
    Pick<
      DataTableContentProps<TData>,
      | "loading"
      | "pending"
      | "skeletonRows"
      | "stickyHeader"
      | "maxHeight"
      | "reorderable"
      | "density"
      | "emptyMessage"
      | "onRowClick"
      | "rowClassName"
      | "rowProps"
      | "renderRow"
    > {
  title: React.ReactNode
  description?: React.ReactNode
  /** Slot in the top-right corner, e.g. a date range or a menu button. */
  action?: React.ReactNode
  /** Column id to filter with the search input. Omit to hide the input. */
  searchKey?: string
  searchPlaceholder?: string
  /** Extra toolbar content, rendered after the search input. */
  toolbar?: React.ReactNode
  showViewOptions?: boolean
  showPagination?: boolean
  pageSizeOptions?: number[]
  /** Actions shown in the bar that appears while rows are selected. */
  selectionActions?: React.ReactNode
  /** Replaces the pagination row, e.g. with a "view all" link. */
  footer?: React.ReactNode
}

/**
 * A card around a data table: title, toolbar, rows, and pagination in the
 * footer. Everything it does is `useDataTable` plus the exported parts, so
 * copy it and rearrange when the shape does not fit.
 */
function DataTableCard<TData extends RowData>({
  columns,
  data,
  pageSize = 10,
  initialSorting,
  initialColumnVisibility,
  pinnedColumns,
  enableRowSelection,
  getRowId,
  onRowSelectionChange,
  title,
  description,
  action,
  searchKey,
  searchPlaceholder = "Filter...",
  toolbar,
  showViewOptions = true,
  showPagination = true,
  pageSizeOptions,
  selectionActions,
  footer,
  loading,
  pending,
  skeletonRows,
  stickyHeader,
  maxHeight,
  reorderable,
  density,
  emptyMessage,
  onRowClick,
  rowClassName,
  rowProps,
  renderRow,
  className,
  ...props
}: DataTableCardProps<TData>) {
  const table = useDataTable({
    columns,
    data,
    pageSize,
    initialSorting,
    initialColumnVisibility,
    pinnedColumns,
    enableRowSelection,
    getRowId,
    onRowSelectionChange,
  })

  const hasToolbar = Boolean(searchKey || toolbar)
  const selectedCount = table.getSelectedRowModel().rows.length
  const showFooter = footer !== undefined || showPagination

  return (
    <Card
      data-slot="data-table-card"
      className={cn("gap-4", className)}
      {...props}
    >
      <CardHeader>
        <CardTitle className="text-base">{title}</CardTitle>
        {description ? <CardDescription>{description}</CardDescription> : null}
        {action || showViewOptions ? (
          <CardAction className="flex items-center gap-2">
            {action}
            {showViewOptions ? (
              <DataTableViewOptions
                table={table}
                reorderable={reorderable}
                disabled={loading}
              />
            ) : null}
          </CardAction>
        ) : null}
      </CardHeader>
      <CardContent className="flex flex-col gap-3">
        {hasToolbar ? (
          <DataTableToolbar>
            {searchKey ? (
              <DataTableSearch
                table={table}
                column={searchKey}
                placeholder={searchPlaceholder}
                disabled={loading}
              />
            ) : null}
            {toolbar}
          </DataTableToolbar>
        ) : null}
        {selectedCount > 0 ? (
          <DataTableSelectionBar table={table}>
            {selectionActions}
          </DataTableSelectionBar>
        ) : null}
        <DataTableContent
          table={table}
          loading={loading}
          pending={pending}
          skeletonRows={skeletonRows ?? Math.min(pageSize || 10, 10)}
          stickyHeader={stickyHeader}
          maxHeight={maxHeight}
          reorderable={reorderable}
          density={density}
          emptyMessage={emptyMessage}
          onRowClick={onRowClick}
          rowClassName={rowClassName}
          rowProps={rowProps}
          renderRow={renderRow}
        />
      </CardContent>
      {showFooter ? (
        <CardFooter>
          {footer ?? (
            <DataTablePagination
              table={table}
              pageSizeOptions={pageSizeOptions}
              className="w-full"
            />
          )}
        </CardFooter>
      ) : null}
    </Card>
  )
}

export { DataTableCard }
```

### components/ui/data-table.tsx

```tsx
"use client"

import * as React from "react"
import {
  columnFilteringFeature,
  columnOrderingFeature,
  columnPinningFeature,
  columnSizingFeature,
  columnVisibilityFeature,
  createColumnHelper,
  createFilteredRowModel,
  createPaginatedRowModel,
  createSortedRowModel,
  filterFn_includesString,
  flexRender,
  rowPaginationFeature,
  rowSelectionFeature,
  rowSortingFeature,
  sortFn_alphanumeric,
  sortFn_basic,
  sortFn_datetime,
  sortFn_text,
  tableFeatures,
  useTable,
  type Column,
  type ColumnDef,
  type ColumnFiltersState,
  type ColumnOrderState,
  type ColumnPinningState,
  type ColumnVisibilityState,
  type ReactTable,
  type Row,
  type RowData,
  type RowSelectionState,
  type SortingState,
} from "@tanstack/react-table"
import {
  ArrowDown,
  ArrowUp,
  ArrowUpDown,
  ChevronLeft,
  ChevronRight,
  ChevronsLeft,
  ChevronsRight,
  GripVertical,
  Settings2,
  X,
} from "lucide-react"

import { cn } from "@/lib/utils"
import { Button } from "@/components/ui/button"
import { Checkbox } from "@/components/ui/checkbox"
import {
  DropdownMenu,
  DropdownMenuCheckboxItem,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
import { Input } from "@/components/ui/input"
import { Skeleton } from "@/components/ui/skeleton"
import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@/components/ui/table"

/**
 * TanStack Table v9 is feature-gated: only what is registered here ships in
 * the bundle. Sorting, filtering, pagination, visibility, ordering, pinning,
 * and row selection cover the usual dashboard table.
 */
const dataTableFeatures = tableFeatures({
  columnFilteringFeature,
  columnOrderingFeature,
  columnPinningFeature,
  columnSizingFeature,
  columnVisibilityFeature,
  rowPaginationFeature,
  rowSelectionFeature,
  rowSortingFeature,
  filteredRowModel: createFilteredRowModel(),
  paginatedRowModel: createPaginatedRowModel(),
  sortedRowModel: createSortedRowModel(),
  filterFns: { includesString: filterFn_includesString },
  sortFns: {
    alphanumeric: sortFn_alphanumeric,
    basic: sortFn_basic,
    datetime: sortFn_datetime,
    text: sortFn_text,
  },
})

type DataTableFeatures = typeof dataTableFeatures

type DataTableColumnDef<TData extends RowData> = ColumnDef<
  DataTableFeatures,
  TData,
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  any
>

/** The table instance returned by `useDataTable`. */
type DataTableInstance<TData extends RowData> = ReactTable<
  DataTableFeatures,
  TData
>

type DataTableColumn<TData extends RowData> = Column<
  DataTableFeatures,
  TData,
  unknown
>

type DataTableRow<TData extends RowData> = Row<DataTableFeatures, TData>

/** Typed column helper bound to the data table's feature set. */
function createDataTableColumnHelper<TData extends RowData>() {
  return createColumnHelper<DataTableFeatures, TData>()
}

/** Row density presets. Only the cell padding changes. */
type DataTableDensity = "compact" | "default" | "relaxed"

const densityClasses: Record<DataTableDensity, string> = {
  compact:
    "[&_[data-slot=table-head]]:h-8 [&_[data-slot=table-cell]]:py-1 [&_[data-slot=table-cell]]:text-[0.8125rem]",
  default: "",
  relaxed: "[&_[data-slot=table-head]]:h-12 [&_[data-slot=table-cell]]:py-3.5",
}

/* -------------------------------------------------------------------------- */
/*                                    hook                                    */
/* -------------------------------------------------------------------------- */

export interface UseDataTableOptions<TData extends RowData> {
  columns: ReadonlyArray<DataTableColumnDef<TData>>
  data: TData[]
  /** Rows per page. Pass 0 to keep every row on a single page. */
  pageSize?: number
  initialSorting?: SortingState
  initialColumnVisibility?: ColumnVisibilityState
  /**
   * Column ids held against the leading and trailing edge. Read once, on
   * mount; use `table.setColumnPinning` to change it afterwards. Pinned
   * columns should declare a `size` so the sticky offsets line up.
   */
  pinnedColumns?: Partial<ColumnPinningState>
  /** Turn on checkbox selection, or decide per row. */
  enableRowSelection?: boolean | ((row: DataTableRow<TData>) => boolean)
  /** Stable row ids. Selection survives sorting and paging with this set. */
  getRowId?: (row: TData, index: number) => string
  onRowSelectionChange?: (selection: RowSelectionState) => void
}

/**
 * Wires the table state the components below read. Call it when you want to
 * lay the pieces out yourself; `DataTable` calls it for you.
 */
function useDataTable<TData extends RowData>({
  columns,
  data,
  pageSize = 10,
  initialSorting,
  initialColumnVisibility,
  pinnedColumns,
  enableRowSelection,
  getRowId,
  onRowSelectionChange,
}: UseDataTableOptions<TData>): DataTableInstance<TData> {
  const [sorting, setSorting] = React.useState<SortingState>(
    initialSorting ?? []
  )
  const [columnFilters, setColumnFilters] = React.useState<ColumnFiltersState>(
    []
  )
  const [columnVisibility, setColumnVisibility] =
    React.useState<ColumnVisibilityState>(initialColumnVisibility ?? {})
  const [columnOrder, setColumnOrder] = React.useState<ColumnOrderState>([])
  const [columnPinning, setColumnPinning] = React.useState<ColumnPinningState>(
    () => ({ start: pinnedColumns?.start ?? [], end: pinnedColumns?.end ?? [] })
  )
  const [rowSelection, setRowSelection] = React.useState<RowSelectionState>({})

  // Report the selection from an effect, not from inside the state updater:
  // the table can call the updater while it renders.
  const notify = React.useRef(onRowSelectionChange)
  const mounted = React.useRef(false)
  React.useEffect(() => {
    notify.current = onRowSelectionChange
  })
  React.useEffect(() => {
    if (!mounted.current) {
      mounted.current = true
      return
    }
    notify.current?.(rowSelection)
  }, [rowSelection])

  return useTable({
    features: dataTableFeatures,
    data,
    columns: columns as DataTableColumnDef<TData>[],
    initialState: {
      pagination: {
        pageIndex: 0,
        pageSize: pageSize > 0 ? pageSize : Number.MAX_SAFE_INTEGER,
      },
    },
    getRowId,
    enableRowSelection,
    // Shift-click extends the selection from the last row you touched.
    isRowRangeSelectionEvent: (event) =>
      Boolean((event as { shiftKey?: boolean }).shiftKey),
    onSortingChange: setSorting,
    onColumnFiltersChange: setColumnFilters,
    onColumnVisibilityChange: setColumnVisibility,
    onColumnOrderChange: setColumnOrder,
    onColumnPinningChange: setColumnPinning,
    onRowSelectionChange: setRowSelection,
    state: {
      sorting,
      columnFilters,
      columnVisibility,
      columnOrder,
      columnPinning,
      rowSelection,
    },
  })
}

/* -------------------------------------------------------------------------- */
/*                                   preset                                   */
/* -------------------------------------------------------------------------- */

export interface DataTableProps<TData extends RowData>
  extends Omit<React.ComponentProps<"div">, "onSelect">,
    UseDataTableOptions<TData> {
  /** Column id to filter with the search input. Omit to hide the input. */
  searchKey?: string
  searchPlaceholder?: string
  /** Extra toolbar content, rendered between the search input and view options. */
  toolbar?: React.ReactNode
  showViewOptions?: boolean
  showPagination?: boolean
  pageSizeOptions?: number[]
  emptyMessage?: React.ReactNode
  /** Swap the rows for a skeleton, e.g. on first load. */
  loading?: boolean
  /** Keep the rows but dim them, e.g. while a filter change is in flight. */
  pending?: boolean
  skeletonRows?: number
  stickyHeader?: boolean
  /** Caps the scroll area, e.g. 420 or "60vh". Pair it with stickyHeader. */
  maxHeight?: number | string
  /** Let columns be dragged into a new order. Pass ids to limit which ones. */
  reorderable?: boolean | string[]
  density?: DataTableDensity
  onRowClick?: (row: DataTableRow<TData>) => void
  rowClassName?: (row: DataTableRow<TData>) => string | undefined
  /** Anything else to put on a row, e.g. a data attribute or a handler. */
  rowProps?: (row: DataTableRow<TData>) => React.ComponentProps<"tr">
  /** Wrap the row element, e.g. in a context menu trigger. */
  renderRow?: (
    row: DataTableRow<TData>,
    element: React.ReactElement
  ) => React.ReactNode
  /** Actions shown in the bar that appears while rows are selected. */
  selectionActions?: React.ReactNode
}

/**
 * The batteries-included table: toolbar, rows, and pagination. Every part is
 * exported on its own, so reach for `useDataTable` and compose them by hand
 * when this shape is not the one you want.
 */
function DataTable<TData extends RowData>({
  columns,
  data,
  pageSize = 10,
  initialSorting,
  initialColumnVisibility,
  pinnedColumns,
  enableRowSelection,
  getRowId,
  onRowSelectionChange,
  searchKey,
  searchPlaceholder = "Filter...",
  toolbar,
  showViewOptions = true,
  showPagination = true,
  pageSizeOptions,
  emptyMessage = "No results.",
  loading = false,
  pending = false,
  skeletonRows,
  stickyHeader = false,
  maxHeight,
  reorderable = false,
  density = "default",
  onRowClick,
  rowClassName,
  rowProps,
  renderRow,
  selectionActions,
  className,
  ...props
}: DataTableProps<TData>) {
  const table = useDataTable({
    columns,
    data,
    pageSize,
    initialSorting,
    initialColumnVisibility,
    pinnedColumns,
    enableRowSelection,
    getRowId,
    onRowSelectionChange,
  })

  const hasToolbar = Boolean(searchKey || toolbar || showViewOptions)
  const selectedCount = table.getSelectedRowModel().rows.length

  return (
    <div
      data-slot="data-table"
      className={cn("flex flex-col gap-4", className)}
      {...props}
    >
      {hasToolbar ? (
        <DataTableToolbar>
          {searchKey ? (
            <DataTableSearch
              table={table}
              column={searchKey}
              placeholder={searchPlaceholder}
              disabled={loading}
            />
          ) : null}
          {toolbar}
          {showViewOptions ? (
            <DataTableViewOptions
              table={table}
              reorderable={reorderable}
              className="ml-auto"
              disabled={loading}
            />
          ) : null}
        </DataTableToolbar>
      ) : null}
      {selectedCount > 0 ? (
        <DataTableSelectionBar table={table}>
          {selectionActions}
        </DataTableSelectionBar>
      ) : null}
      <DataTableContent
        table={table}
        loading={loading}
        pending={pending}
        skeletonRows={skeletonRows ?? Math.min(pageSize || 10, 10)}
        stickyHeader={stickyHeader}
        maxHeight={maxHeight}
        reorderable={reorderable}
        density={density}
        emptyMessage={emptyMessage}
        onRowClick={onRowClick}
        rowClassName={rowClassName}
        rowProps={rowProps}
        renderRow={renderRow}
      />
      {showPagination ? (
        <DataTablePagination table={table} pageSizeOptions={pageSizeOptions} />
      ) : null}
    </div>
  )
}

/* -------------------------------------------------------------------------- */
/*                                   toolbar                                  */
/* -------------------------------------------------------------------------- */

/** The row above the table. Anything can go in it. */
function DataTableToolbar({
  className,
  ...props
}: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="data-table-toolbar"
      className={cn("flex flex-wrap items-center gap-2", className)}
      {...props}
    />
  )
}

interface DataTableSearchProps<TData extends RowData>
  extends Omit<React.ComponentProps<typeof Input>, "value" | "onChange"> {
  table: DataTableInstance<TData>
  /** Column id to filter. */
  column: string
}

/** An input bound to one column's filter. */
function DataTableSearch<TData extends RowData>({
  table,
  column,
  className,
  ...props
}: DataTableSearchProps<TData>) {
  const target = table.getColumn(column)
  if (!target) return null

  return (
    <Input
      data-slot="data-table-search"
      value={(target.getFilterValue() as string) ?? ""}
      onChange={(event) => target.setFilterValue(event.target.value)}
      className={cn("h-8 max-w-sm", className)}
      {...props}
    />
  )
}

interface DataTableViewOptionsProps<TData extends RowData>
  extends React.ComponentProps<typeof Button> {
  table: DataTableInstance<TData>
  /** Adds "move left / move right" items for the reorderable columns. */
  reorderable?: boolean | string[]
}

/** Column visibility, and column order when reordering is on. */
function DataTableViewOptions<TData extends RowData>({
  table,
  reorderable = false,
  className,
  ...props
}: DataTableViewOptionsProps<TData>) {
  const columns = table.getAllColumns().filter((column) => column.getCanHide())

  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button
          variant="outline"
          size="sm"
          className={cn("h-8", className)}
          {...props}
        >
          <Settings2 />
          View
        </Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent align="end" className="w-44">
        <DropdownMenuLabel>Toggle columns</DropdownMenuLabel>
        <DropdownMenuSeparator />
        {columns.map((column) => (
          <DropdownMenuCheckboxItem
            key={column.id}
            className="capitalize"
            checked={column.getIsVisible()}
            onCheckedChange={(value) => column.toggleVisibility(!!value)}
          >
            {column.id}
          </DropdownMenuCheckboxItem>
        ))}
        {reorderable ? (
          <>
            <DropdownMenuSeparator />
            <DropdownMenuLabel>Column order</DropdownMenuLabel>
            <DropdownMenuItem onSelect={() => table.resetColumnOrder()}>
              Reset to default
            </DropdownMenuItem>
          </>
        ) : null}
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

interface DataTableColumnHeaderProps<TData extends RowData, TValue>
  extends React.ComponentProps<"div"> {
  column: Column<DataTableFeatures, TData, TValue>
  title: string
  align?: "left" | "right"
}

function DataTableColumnHeader<TData extends RowData, TValue>({
  column,
  title,
  align = "left",
  className,
  ...props
}: DataTableColumnHeaderProps<TData, TValue>) {
  if (!column.getCanSort()) {
    return (
      <div
        className={cn(align === "right" && "text-right", className)}
        {...props}
      >
        {title}
      </div>
    )
  }

  const sorted = column.getIsSorted()
  const Icon =
    sorted === "asc" ? ArrowUp : sorted === "desc" ? ArrowDown : ArrowUpDown

  return (
    <div
      className={cn("flex", align === "right" && "justify-end", className)}
      {...props}
    >
      <Button
        variant="ghost"
        size="sm"
        className="data-[sorted=true]:text-foreground -ml-2 h-8 gap-1.5 px-2"
        data-sorted={sorted !== false}
        onClick={() => column.toggleSorting(sorted === "asc")}
      >
        {title}
        <Icon className="text-muted-foreground size-3.5" />
      </Button>
    </div>
  )
}

/* -------------------------------------------------------------------------- */
/*                                  selection                                 */
/* -------------------------------------------------------------------------- */

/**
 * A checkbox column. Put it first in your column list and give the table a
 * `getRowId` so the selection survives sorting and paging.
 */
function createSelectionColumn<TData extends RowData>(
  overrides?: Partial<DataTableColumnDef<TData>>
): DataTableColumnDef<TData> {
  return {
    id: "select",
    size: 36,
    enableSorting: false,
    enableHiding: false,
    header: ({ table }) => (
      <Checkbox
        checked={
          table.getIsAllPageRowsSelected()
            ? true
            : table.getIsSomePageRowsSelected()
              ? "indeterminate"
              : false
        }
        onCheckedChange={(value) => table.toggleAllPageRowsSelected(!!value)}
        aria-label="Select all rows on this page"
      />
    ),
    cell: ({ row }) => (
      <Checkbox
        checked={row.getIsSelected()}
        disabled={!row.getCanSelect()}
        // The handler wants the checkbox's next value and the shift key, which
        // is what turns a click into a range selection.
        onClick={(event) =>
          row.getToggleSelectedHandler()({
            target: { checked: !row.getIsSelected() },
            shiftKey: event.shiftKey,
          })
        }
        aria-label="Select row"
      />
    ),
    ...overrides,
  } as DataTableColumnDef<TData>
}

interface DataTableSelectionBarProps<TData extends RowData>
  extends React.ComponentProps<"div"> {
  table: DataTableInstance<TData>
}

/** The bar that appears once rows are selected. Children are the actions. */
function DataTableSelectionBar<TData extends RowData>({
  table,
  children,
  className,
  ...props
}: DataTableSelectionBarProps<TData>) {
  const count = table.getSelectedRowModel().rows.length

  return (
    <div
      data-slot="data-table-selection-bar"
      className={cn(
        "bg-muted/50 flex flex-wrap items-center gap-2 rounded-md border px-3 py-2",
        className
      )}
      {...props}
    >
      <span className="text-sm tabular-nums">
        {count} {count === 1 ? "row" : "rows"} selected
      </span>
      <div className="ml-auto flex items-center gap-2">
        {children}
        <Button
          variant="ghost"
          size="sm"
          className="h-8"
          onClick={() => table.resetRowSelection()}
        >
          <X />
          Clear
        </Button>
      </div>
    </div>
  )
}

/* -------------------------------------------------------------------------- */
/*                                   content                                  */
/* -------------------------------------------------------------------------- */

/** Moves `columnId` to the slot `targetId` currently occupies. */
function moveColumn<TData extends RowData>(
  table: DataTableInstance<TData>,
  columnId: string,
  targetId: string
) {
  const order = table.getAllLeafColumns().map((column) => column.id)
  const from = order.indexOf(columnId)
  const to = order.indexOf(targetId)
  if (from < 0 || to < 0 || from === to) return
  const next = order.slice()
  next.splice(from, 1)
  next.splice(to, 0, columnId)
  table.setColumnOrder(next)
}

/** Nudges `columnId` one slot left (-1) or right (1). */
function shiftColumn<TData extends RowData>(
  table: DataTableInstance<TData>,
  columnId: string,
  delta: number
) {
  const order = table.getAllLeafColumns().map((column) => column.id)
  const from = order.indexOf(columnId)
  const to = from + delta
  if (from < 0 || to < 0 || to >= order.length) return
  const next = order.slice()
  next.splice(from, 1)
  next.splice(to, 0, columnId)
  table.setColumnOrder(next)
}

/**
 * Sticky offsets and hairlines for a pinned cell. The feature computes the
 * regions; the renderer owns the CSS.
 */
function getPinnedStyle<TData extends RowData>(
  column: DataTableColumn<TData>,
  { stickyHeader = false }: { stickyHeader?: boolean } = {}
): React.CSSProperties | undefined {
  const pinned = column.getIsPinned()
  const shadows: string[] = []
  if (stickyHeader) shadows.push("inset 0 -1px 0 0 var(--border)")
  if (pinned === "start" && column.getIsLastColumn("start")) {
    shadows.push("inset -1px 0 0 0 var(--border)")
  }
  if (pinned === "end" && column.getIsFirstColumn("end")) {
    shadows.push("inset 1px 0 0 0 var(--border)")
  }
  if (!pinned && !shadows.length) return undefined

  // Auto table layout treats width as a suggestion, so pin all three: the
  // sticky offsets are computed from `size` and have to match what renders.
  const size = pinned ? column.getSize() : undefined

  return {
    insetInlineStart:
      pinned === "start" ? `${column.getStart("start")}px` : undefined,
    insetInlineEnd: pinned === "end" ? `${column.getAfter("end")}px` : undefined,
    width: size,
    minWidth: size,
    maxWidth: size,
    boxShadow: shadows.length ? shadows.join(", ") : undefined,
  }
}

/** Grip on a reorderable header. Drag it, or focus it and press an arrow. */
function DataTableDragHandle<TData extends RowData>({
  table,
  column,
}: {
  table: DataTableInstance<TData>
  column: DataTableColumn<TData>
}) {
  return (
    <button
      type="button"
      aria-label={`Reorder ${column.id} column`}
      className="text-muted-foreground/50 hover:text-foreground focus-visible:ring-ring/50 -ml-1 rounded-sm outline-none focus-visible:ring-[3px]"
      onKeyDown={(event) => {
        if (event.key !== "ArrowLeft" && event.key !== "ArrowRight") return
        event.preventDefault()
        shiftColumn(table, column.id, event.key === "ArrowLeft" ? -1 : 1)
      }}
    >
      <GripVertical className="size-3.5" />
    </button>
  )
}

const skeletonWidths = [72, 44, 58, 36, 64, 48, 52]

export interface DataTableContentProps<TData extends RowData>
  extends React.ComponentProps<"div"> {
  table: DataTableInstance<TData>
  loading?: boolean
  pending?: boolean
  skeletonRows?: number
  stickyHeader?: boolean
  maxHeight?: number | string
  reorderable?: boolean | string[]
  density?: DataTableDensity
  emptyMessage?: React.ReactNode
  onRowClick?: (row: DataTableRow<TData>) => void
  rowClassName?: (row: DataTableRow<TData>) => string | undefined
  /**
   * Anything else to put on a row: a handler, a data attribute, a title.
   * Merged after the built-in props, so it wins.
   */
  rowProps?: (row: DataTableRow<TData>) => React.ComponentProps<"tr">
  /**
   * Wrap the row element, e.g. in a context menu trigger or a link. Render
   * the element you are handed somewhere inside what you return.
   */
  renderRow?: (
    row: DataTableRow<TData>,
    element: React.ReactElement
  ) => React.ReactNode
}

/** The bordered table itself: header, rows, and their loading states. */
function DataTableContent<TData extends RowData>({
  table,
  loading = false,
  pending = false,
  skeletonRows = 8,
  stickyHeader = false,
  maxHeight,
  reorderable = false,
  density = "default",
  emptyMessage = "No results.",
  onRowClick,
  rowClassName,
  rowProps,
  renderRow,
  className,
  style,
  ...props
}: DataTableContentProps<TData>) {
  const [dragging, setDragging] = React.useState<string | null>(null)
  const [dropTarget, setDropTarget] = React.useState<string | null>(null)

  const { start, end } = table.state.columnPinning
  const hasPinned = start.length > 0 || end.length > 0
  const visibleColumns = table.getVisibleLeafColumns()
  const rows = table.getRowModel().rows

  const canReorder = (column: DataTableColumn<TData>) => {
    if (!reorderable || column.getIsPinned()) return false
    return Array.isArray(reorderable)
      ? reorderable.includes(column.id)
      : column.getCanHide()
  }

  /** Native drag and drop, so no drag library is pulled in for this. */
  const dragProps = (columnId: string): React.ComponentProps<"th"> => ({
    draggable: true,
    onDragStart: (event) => {
      setDragging(columnId)
      event.dataTransfer.effectAllowed = "move"
      event.dataTransfer.setData("text/plain", columnId)
    },
    onDragOver: (event) => {
      if (!dragging || dragging === columnId) return
      event.preventDefault()
      event.dataTransfer.dropEffect = "move"
      setDropTarget(columnId)
    },
    onDragLeave: () =>
      setDropTarget((current) => (current === columnId ? null : current)),
    onDrop: (event) => {
      event.preventDefault()
      if (dragging) moveColumn(table, dragging, columnId)
      setDragging(null)
      setDropTarget(null)
    },
    onDragEnd: () => {
      setDragging(null)
      setDropTarget(null)
    },
  })

  // Pinned cells are painted opaque so rows scroll under them, which would
  // otherwise hide the row's own hover and selected colours. Move both onto
  // the cells so pinned and unpinned columns stay in step. They have to stay
  // opaque too: a translucent hover on a pinned cell lets the columns passing
  // underneath show through, so the row hover is `bg-muted/50` pre-mixed over
  // the background rather than blended with whatever is behind the cell.
  const rowClasses = cn(
    "group/row",
    hasPinned && "hover:bg-transparent data-[state=selected]:bg-transparent"
  )
  const cellClasses = cn(
    hasPinned && [
      "group-hover/row:bg-[color-mix(in_oklab,var(--muted)_50%,var(--background))]",
      "group-data-[state=selected]/row:bg-muted",
    ]
  )

  return (
    <div
      data-slot="data-table-content"
      aria-busy={loading || pending || undefined}
      className={cn(
        "relative overflow-hidden rounded-md border",
        maxHeight !== undefined &&
          "[&>[data-slot=table-container]]:max-h-[var(--data-table-max-height)]",
        densityClasses[density],
        className
      )}
      style={
        maxHeight !== undefined
          ? ({
              ...style,
              "--data-table-max-height":
                typeof maxHeight === "number" ? `${maxHeight}px` : maxHeight,
            } as React.CSSProperties)
          : style
      }
      {...props}
    >
      {pending ? (
        <div
          aria-hidden
          className="bg-primary/60 absolute inset-x-0 top-0 z-40 h-0.5 animate-pulse"
        />
      ) : null}
      <Table>
        <TableHeader className={cn(stickyHeader && "[&_tr]:border-b-0")}>
          {table.getHeaderGroups().map((headerGroup) => (
            <TableRow
              key={headerGroup.id}
              className={cn(rowClasses, "hover:bg-transparent")}
            >
              {headerGroup.headers.map((header) => {
                const column = header.column as DataTableColumn<TData>
                const pinned = column.getIsPinned()
                const draggable = canReorder(column)

                return (
                  <TableHead
                    key={header.id}
                    colSpan={header.colSpan}
                    data-pinned={pinned || undefined}
                    data-dragging={dragging === column.id || undefined}
                    data-drop-target={dropTarget === column.id || undefined}
                    {...(draggable ? dragProps(column.id) : null)}
                    className={cn(
                      (stickyHeader || pinned) && "bg-background",
                      stickyHeader && "sticky top-0 z-20",
                      pinned && "sticky z-20 overflow-hidden",
                      pinned && stickyHeader && "z-30",
                      draggable && "cursor-grab data-[dragging]:opacity-40",
                      "data-[drop-target]:bg-muted"
                    )}
                    style={getPinnedStyle(column, { stickyHeader })}
                  >
                    {header.isPlaceholder ? null : draggable ? (
                      <div className="flex items-center gap-1">
                        <DataTableDragHandle table={table} column={column} />
                        {flexRender(
                          column.columnDef.header,
                          header.getContext()
                        )}
                      </div>
                    ) : (
                      flexRender(column.columnDef.header, header.getContext())
                    )}
                  </TableHead>
                )
              })}
            </TableRow>
          ))}
        </TableHeader>
        <TableBody
          className={cn(
            pending && "pointer-events-none opacity-50",
            "transition-opacity"
          )}
        >
          {loading ? (
            <DataTableSkeletonRows
              columns={visibleColumns.length}
              rows={skeletonRows}
            />
          ) : rows.length ? (
            rows.map((row) => {
              const extra = rowProps?.(row)
              const element = (
                <TableRow
                  data-state={row.getIsSelected() ? "selected" : undefined}
                  onClick={onRowClick ? () => onRowClick(row) : undefined}
                  {...extra}
                  className={cn(
                    rowClasses,
                    onRowClick && "cursor-pointer",
                    rowClassName?.(row),
                    extra?.className
                  )}
                >
                  {row.getVisibleCells().map((cell) => {
                    const column = cell.column as DataTableColumn<TData>
                    const pinned = column.getIsPinned()

                    return (
                      <TableCell
                        key={cell.id}
                        data-pinned={pinned || undefined}
                        className={cn(
                          cellClasses,
                          pinned && "bg-background sticky z-20 overflow-hidden"
                        )}
                        style={getPinnedStyle(column)}
                      >
                        {flexRender(column.columnDef.cell, cell.getContext())}
                      </TableCell>
                    )
                  })}
                </TableRow>
              )

              return (
                <React.Fragment key={row.id}>
                  {renderRow ? renderRow(row, element) : element}
                </React.Fragment>
              )
            })
          ) : (
            <TableRow className="hover:bg-transparent">
              <TableCell
                colSpan={visibleColumns.length}
                className="text-muted-foreground h-24 text-center"
              >
                {emptyMessage}
              </TableCell>
            </TableRow>
          )}
        </TableBody>
      </Table>
    </div>
  )
}

/* -------------------------------------------------------------------------- */
/*                                  skeletons                                 */
/* -------------------------------------------------------------------------- */

function DataTableSkeletonRows({
  columns,
  rows,
}: {
  columns: number
  rows: number
}) {
  return (
    <>
      {Array.from({ length: rows }).map((_, rowIndex) => (
        <TableRow key={rowIndex} className="hover:bg-transparent">
          {Array.from({ length: columns }).map((__, columnIndex) => (
            <TableCell key={columnIndex}>
              <Skeleton
                className="h-4"
                style={{
                  width: `${
                    skeletonWidths[
                      (rowIndex + columnIndex) % skeletonWidths.length
                    ]
                  }%`,
                }}
              />
            </TableCell>
          ))}
        </TableRow>
      ))}
    </>
  )
}

export interface DataTableSkeletonProps extends React.ComponentProps<"div"> {
  columns: number
  rows?: number
  showToolbar?: boolean
  showPagination?: boolean
}

/**
 * A standalone placeholder for when the columns are not known yet, e.g. a
 * Suspense fallback. Once you have a table instance, `loading` on
 * `DataTableContent` renders the same rows under the real header.
 */
function DataTableSkeleton({
  columns,
  rows = 8,
  showToolbar = true,
  showPagination = true,
  className,
  ...props
}: DataTableSkeletonProps) {
  return (
    <div
      data-slot="data-table-skeleton"
      aria-busy
      className={cn("flex flex-col gap-4", className)}
      {...props}
    >
      {showToolbar ? (
        <div className="flex items-center gap-2">
          <Skeleton className="h-8 w-full max-w-sm" />
          <Skeleton className="ml-auto h-8 w-20" />
        </div>
      ) : null}
      <div className="overflow-hidden rounded-md border">
        <Table>
          <TableHeader>
            <TableRow className="hover:bg-transparent">
              {Array.from({ length: columns }).map((_, index) => (
                <TableHead key={index}>
                  <Skeleton className="h-3.5 w-16" />
                </TableHead>
              ))}
            </TableRow>
          </TableHeader>
          <TableBody>
            <DataTableSkeletonRows columns={columns} rows={rows} />
          </TableBody>
        </Table>
      </div>
      {showPagination ? (
        <div className="flex items-center justify-between gap-4">
          <Skeleton className="h-5 w-28" />
          <Skeleton className="h-8 w-48" />
        </div>
      ) : null}
    </div>
  )
}

/* -------------------------------------------------------------------------- */
/*                                 pagination                                 */
/* -------------------------------------------------------------------------- */

interface DataTablePaginationProps<TData extends RowData>
  extends React.ComponentProps<"div"> {
  table: DataTableInstance<TData>
  /** Adds a rows-per-page menu. */
  pageSizeOptions?: number[]
}

function DataTablePagination<TData extends RowData>({
  table,
  pageSizeOptions,
  className,
  ...props
}: DataTablePaginationProps<TData>) {
  const { pageIndex, pageSize } = table.state.pagination
  const total = table.getFilteredRowModel().rows.length
  const from = total === 0 ? 0 : pageIndex * pageSize + 1
  const to = Math.min((pageIndex + 1) * pageSize, total)

  return (
    <div
      data-slot="data-table-pagination"
      className={cn("flex flex-wrap items-center justify-between gap-4", className)}
      {...props}
    >
      <div className="flex items-center gap-3">
        <p className="text-muted-foreground text-sm tabular-nums">
          {from}–{to} of {total}
        </p>
        {pageSizeOptions?.length ? (
          <DropdownMenu>
            <DropdownMenuTrigger asChild>
              <Button variant="ghost" size="sm" className="h-8 tabular-nums">
                {pageSize} per page
              </Button>
            </DropdownMenuTrigger>
            <DropdownMenuContent align="start" className="w-36">
              {pageSizeOptions.map((option) => (
                <DropdownMenuCheckboxItem
                  key={option}
                  checked={option === pageSize}
                  onCheckedChange={() => table.setPageSize(option)}
                  className="tabular-nums"
                >
                  {option} per page
                </DropdownMenuCheckboxItem>
              ))}
            </DropdownMenuContent>
          </DropdownMenu>
        ) : null}
      </div>
      <div className="flex items-center gap-1">
        <Button
          variant="outline"
          size="icon"
          className="size-8"
          onClick={() => table.firstPage()}
          disabled={!table.getCanPreviousPage()}
          aria-label="First page"
        >
          <ChevronsLeft />
        </Button>
        <Button
          variant="outline"
          size="icon"
          className="size-8"
          onClick={() => table.previousPage()}
          disabled={!table.getCanPreviousPage()}
          aria-label="Previous page"
        >
          <ChevronLeft />
        </Button>
        <span className="text-muted-foreground px-2 text-sm tabular-nums">
          Page {pageIndex + 1} of {Math.max(table.getPageCount(), 1)}
        </span>
        <Button
          variant="outline"
          size="icon"
          className="size-8"
          onClick={() => table.nextPage()}
          disabled={!table.getCanNextPage()}
          aria-label="Next page"
        >
          <ChevronRight />
        </Button>
        <Button
          variant="outline"
          size="icon"
          className="size-8"
          onClick={() => table.lastPage()}
          disabled={!table.getCanNextPage()}
          aria-label="Last page"
        >
          <ChevronsRight />
        </Button>
      </div>
    </div>
  )
}

export {
  DataTable,
  DataTableColumnHeader,
  DataTableContent,
  DataTablePagination,
  DataTableSearch,
  DataTableSelectionBar,
  DataTableSkeleton,
  DataTableToolbar,
  DataTableViewOptions,
  createDataTableColumnHelper,
  createSelectionColumn,
  dataTableFeatures,
  moveColumn,
  shiftColumn,
  useDataTable,
  type DataTableColumnDef,
  type DataTableDensity,
  type DataTableFeatures,
  type DataTableInstance,
  type DataTableRow,
}
```

# Distribution Card

A total with delta, a stacked share bar, and a ranked list of the contributors with their values.

A total with delta, a stacked bar showing how it splits, and a ranked list of the contributors with their values. Use it for capital inflows, revenue by source, or storage by type.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/distribution-card.json
```

Also installs `card`, `button`, `dropdown-menu`, `tooltip` from shadcn/ui if missing.

npm dependencies: `lucide-react`.

## Usage

```tsx
import { DistributionCard } from "@/components/distribution-card"

<DistributionCard
  title="Capital inflows"
  total={12400000}
  delta={390000}
  valueLabel="Capital in"
  items={[
    { name: "WaveMark Capital", value: 7928400, icon: <Gem />, color: "var(--color-teal-500)" },
    { name: "Envato Finances", value: 3214900, icon: <Hexagon />, color: "var(--color-amber-500)" },
    { name: "QBridge Tech", value: 1246300, icon: <Triangle />, color: "var(--color-orange-500)" },
  ]}
  options={[
    { value: "3", label: "Top 3 funds" },
    { value: "5", label: "Top 5 funds" },
  ]}
/>
```

## Examples

### Default

```tsx
"use client"

import * as React from "react"
import { Gem, Hexagon, Triangle } from "lucide-react"

import { DistributionCard } from "@/registry/dashboardcn/blocks/distribution-card"

const funds = [
  { name: "WaveMark Capital", value: 7_928_400, icon: <Gem className="text-teal-500" />, color: "var(--color-teal-500)" },
  { name: "Envato Finances", value: 3_214_900, icon: <Hexagon className="text-amber-500" />, color: "var(--color-amber-500)" },
  { name: "QBridge Tech", value: 1_246_300, icon: <Triangle className="text-orange-500" />, color: "var(--color-orange-500)" },
  { name: "Northline Partners", value: 612_000, icon: <Gem className="text-sky-500" />, color: "var(--color-sky-500)" },
  { name: "Halyard Ventures", value: 388_500, icon: <Hexagon className="text-violet-500" />, color: "var(--color-violet-500)" },
]

export default function DistributionCardDemo() {
  const [limit, setLimit] = React.useState("3")
  return (
    <DistributionCard
      className="w-full max-w-md"
      title="Capital inflows"
      items={funds.slice(0, Number(limit))}
      total={12_400_000}
      delta={390_000}
      valueLabel="Capital in"
      options={[
        { value: "3", label: "Top 3 funds" },
        { value: "5", label: "Top 5 funds" },
      ]}
      value={limit}
      onValueChange={setLimit}
    />
  )
}
```

## Source

### components/distribution-card.tsx

```tsx
"use client"

import * as React from "react"
import { ChevronDown } from "lucide-react"

import { cn } from "@/lib/utils"
import { type NumberFormat } from "@/lib/format"
import { Button } from "@/components/ui/button"
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
import { DeltaBadge } from "@/components/ui/delta-badge"
import { DistributionBar } from "@/components/ui/distribution-bar"
import { MetricValue } from "@/components/ui/metric-value"

export interface DistributionCardItem {
  name: string
  value: number
  icon?: React.ReactNode
  /** Any CSS color. Defaults to chart-1 through chart-5 in order. */
  color?: string
}

export interface DistributionCardOption {
  value: string
  label: string
}

export interface DistributionCardProps extends React.ComponentProps<typeof Card> {
  title: string
  items: DistributionCardItem[]
  /** Headline total. Defaults to the sum of the items. */
  total?: number
  /** Absolute change in the total, in the same unit, e.g. 390000 for +$390k. */
  delta?: number
  format?: NumberFormat
  currency?: string
  /** Small label above each item's value, e.g. "Capital in". */
  valueLabel?: string
  /** Options for the header dropdown. Omit to hide it. */
  options?: DistributionCardOption[]
  value?: string
  defaultValue?: string
  onValueChange?: (value: string) => void
}

const defaultColors = [
  "var(--chart-1)",
  "var(--chart-2)",
  "var(--chart-3)",
  "var(--chart-4)",
  "var(--chart-5)",
]

const compactFormatters = new Map<string, Intl.NumberFormat>()

/** "$12.4M", or "+$390K" when signed. */
function formatCompact(
  value: number,
  format: NumberFormat,
  currency: string,
  signed = false
) {
  const key = `${format}:${currency}:${signed}`
  let formatter = compactFormatters.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat("en-US", {
      ...(format === "currency" ? { style: "currency", currency } : {}),
      notation: "compact",
      signDisplay: signed ? "exceptZero" : "auto",
      // Explicit minimum keeps Node and browsers in agreement ("$390K", not "$390.0K").
      minimumFractionDigits: 0,
      maximumFractionDigits: 1,
    })
    compactFormatters.set(key, formatter)
  }
  return formatter.format(value)
}

/** A total with delta, a stacked share bar, and a ranked list of the contributors. */
function DistributionCard({
  title,
  items,
  total,
  delta,
  format = "currency",
  currency = "USD",
  valueLabel,
  options,
  value,
  defaultValue,
  onValueChange,
  className,
  ...props
}: DistributionCardProps) {
  const [internal, setInternal] = React.useState(defaultValue ?? options?.[0]?.value ?? "")
  const selected = value ?? internal
  const selectedLabel = options?.find((option) => option.value === selected)?.label
  const sum = total ?? items.reduce((acc, item) => acc + item.value, 0)
  const segments = items.map((item, index) => ({
    ...item,
    color: item.color ?? defaultColors[index % defaultColors.length],
  }))

  return (
    <Card data-slot="distribution-card" className={cn("gap-0 py-0", className)} {...props}>
      <CardHeader className="flex items-center justify-between gap-3 border-b py-3 [.border-b]:pb-3">
        <CardTitle className="text-sm">{title}</CardTitle>
        {options?.length ? (
          <DropdownMenu>
              <DropdownMenuTrigger asChild>
                <Button variant="outline" size="sm">
                  {selectedLabel}
                  <ChevronDown className="text-muted-foreground" />
                </Button>
              </DropdownMenuTrigger>
              <DropdownMenuContent align="end">
                <DropdownMenuRadioGroup
                  value={selected}
                  onValueChange={(next) => {
                    setInternal(next)
                    onValueChange?.(next)
                  }}
                >
                  {options.map((option) => (
                    <DropdownMenuRadioItem key={option.value} value={option.value}>
                      {option.label}
                    </DropdownMenuRadioItem>
                  ))}
                </DropdownMenuRadioGroup>
              </DropdownMenuContent>
            </DropdownMenu>
        ) : null}
      </CardHeader>
      <CardContent className="flex flex-col gap-4 py-5">
        <div className="flex flex-wrap items-center gap-2">
          <span className="text-3xl font-semibold tabular-nums tracking-tight">
            {formatCompact(sum, format, currency)}
          </span>
          {delta !== undefined ? (
            <DeltaBadge delta={delta} variant="soft">
              {formatCompact(delta, format, currency, true)}
            </DeltaBadge>
          ) : null}
        </div>
        <DistributionBar segments={segments} showLegend={false} />
        <ul className="flex flex-col divide-y">
          {segments.map((item) => (
            <li
              key={item.name}
              data-slot="distribution-card-item"
              className="flex items-center gap-3 py-3 last:pb-0"
            >
              {item.icon ? (
                <span className="bg-muted flex size-9 shrink-0 items-center justify-center rounded-lg [&>svg]:size-5">
                  {item.icon}
                </span>
              ) : (
                <span
                  aria-hidden="true"
                  className="size-2.5 shrink-0 rounded-[2px]"
                  style={{ backgroundColor: item.color }}
                />
              )}
              <span className="min-w-0 flex-1 truncate text-sm font-medium">{item.name}</span>
              <div className="flex flex-col items-end">
                {valueLabel ? (
                  <span className="text-muted-foreground text-xs">{valueLabel}</span>
                ) : null}
                <MetricValue
                  value={item.value}
                  format={format}
                  currency={currency}
                  maximumFractionDigits={0}
                  className="text-sm font-semibold"
                />
              </div>
            </li>
          ))}
        </ul>
      </CardContent>
    </Card>
  )
}

export { DistributionCard }
```

### components/ui/delta-badge.tsx

```tsx
import * as React from "react"
import { Minus, TrendingDown, TrendingUp } from "lucide-react"

import { cn } from "@/lib/utils"
import { formatDelta } from "@/lib/format"

export type DeltaDirection = "up" | "down" | "flat"

export function getDeltaDirection(delta: number | undefined): DeltaDirection {
  if (delta === undefined || delta === 0 || !Number.isFinite(delta)) return "flat"
  return delta > 0 ? "up" : "down"
}

const directionIcon: Record<DeltaDirection, React.ElementType> = {
  up: TrendingUp,
  down: TrendingDown,
  flat: Minus,
}

export interface DeltaBadgeProps extends React.ComponentProps<"span"> {
  /** Fractional change, e.g. 0.124 for +12.4%. */
  delta: number
  /** Treat a decrease as good and an increase as bad (churn, latency, errors). */
  invert?: boolean
  variant?: "outline" | "soft" | "text"
  showIcon?: boolean
}

function DeltaBadge({
  delta,
  invert = false,
  variant = "outline",
  showIcon = true,
  className,
  children,
  ...props
}: DeltaBadgeProps) {
  const direction = getDeltaDirection(delta)
  const positive = direction === "flat" ? null : (direction === "up") !== invert
  const Icon = directionIcon[direction]

  return (
    <span
      data-slot="delta-badge"
      data-direction={direction}
      data-positive={positive}
      className={cn(
        "inline-flex items-center gap-1 text-xs font-medium tabular-nums",
        variant === "outline" && "rounded-md border px-1.5 py-0.5",
        variant === "soft" && "rounded-md px-1.5 py-0.5",
        variant === "soft" && positive === true && "bg-emerald-500/10",
        variant === "soft" && positive === false && "bg-red-500/10",
        variant === "soft" && positive === null && "bg-muted",
        positive === true && "text-emerald-600 dark:text-emerald-400",
        positive === false && "text-red-600 dark:text-red-400",
        positive === null && "text-muted-foreground",
        className
      )}
      {...props}
    >
      {showIcon ? <Icon className="size-3" aria-hidden="true" /> : null}
      {children ?? formatDelta(delta)}
    </span>
  )
}

export { DeltaBadge }
```

### components/ui/distribution-bar.tsx

```tsx
import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber } from "@/lib/format"

export interface DistributionSegment {
  name: string
  value: number
  /** Any CSS color. Defaults to chart-1 through chart-5 in order. */
  color?: string
}

export interface DistributionBarProps extends React.ComponentProps<"div"> {
  segments: DistributionSegment[]
  valueFormatter?: (value: number) => string
  showLegend?: boolean
  /** Show absolute values in the legend in addition to the share. */
  showValues?: boolean
}

const defaultColors = [
  "var(--chart-1)",
  "var(--chart-2)",
  "var(--chart-3)",
  "var(--chart-4)",
  "var(--chart-5)",
]

function DistributionBar({
  segments,
  valueFormatter = (value) => formatNumber(value, { format: "compact" }),
  showLegend = true,
  showValues = false,
  className,
  ...props
}: DistributionBarProps) {
  const total = segments.reduce((sum, segment) => sum + segment.value, 0)
  const resolved = segments.map((segment, index) => ({
    ...segment,
    color: segment.color ?? defaultColors[index % defaultColors.length],
    share: total > 0 ? segment.value / total : 0,
  }))

  return (
    <div
      data-slot="distribution-bar"
      className={cn("flex flex-col gap-3", className)}
      {...props}
    >
      <div
        role="img"
        aria-label={resolved
          .map(
            (segment) =>
              `${segment.name} ${formatNumber(segment.share, { format: "percent" })}`
          )
          .join(", ")}
        className="flex h-2.5 w-full gap-0.5 overflow-hidden rounded-full"
      >
        {resolved.map((segment) =>
          segment.share > 0 ? (
            <div
              key={segment.name}
              className="h-full transition-[width] duration-300 first:rounded-l-full last:rounded-r-full"
              style={{
                width: `${segment.share * 100}%`,
                backgroundColor: segment.color,
              }}
            />
          ) : null
        )}
      </div>
      {showLegend ? (
        <ul className="flex flex-wrap gap-x-4 gap-y-1.5 text-sm">
          {resolved.map((segment) => (
            <li key={segment.name} className="flex items-center gap-2">
              <span
                aria-hidden="true"
                className="size-2.5 shrink-0 rounded-[2px]"
                style={{ backgroundColor: segment.color }}
              />
              <span className="text-muted-foreground">{segment.name}</span>
              <span className="font-medium tabular-nums">
                {formatNumber(segment.share, { format: "percent" })}
              </span>
              {showValues ? (
                <span className="text-muted-foreground tabular-nums">
                  ({valueFormatter(segment.value)})
                </span>
              ) : null}
            </li>
          ))}
        </ul>
      ) : null}
    </div>
  )
}

export { DistributionBar }
```

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Dot Plot Card

A metric card with a big value, a dot-plot distribution with its peak called out, and the change vs the previous period.

A metric card with a big value, a dot-plot distribution with its peak called out, and the change versus the previous period. Suits transactions per day and similar counts.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/dot-plot-card.json
```

Also installs `card`, `tooltip` from shadcn/ui if missing.

## Usage

```tsx
import { DotPlotCard } from "@/components/dot-plot-card"

<DotPlotCard
  title="Transactions"
  value={106000}
  format="compact"
  data={[1, 1, 2, 1, 2, 4, 6, 4, 2, 1, 2, 1, 1, 1]}
  labels={["Sat", "Sun", "Mon", "Tue", "Tue", "Wed", "Wed", "Wed", "Thu", "Thu", "Fri", "Fri", "Sat", "Sat"]}
  delta={34002}
  deltaLabel="vs last period"
  color="var(--color-green-600)"
  action={<Button variant="outline" size="icon-sm" className="rounded-full"><Ellipsis /></Button>}
/>
```

## Examples

### Default

```tsx
import { Ellipsis } from "lucide-react"

import { Button } from "@/components/ui/button"
import { DotPlotCard } from "@/registry/dashboardcn/blocks/dot-plot-card"

const hours = [
  "Sat", "Sun", "Mon", "Tue", "Tue", "Wed", "Wed", "Wed", "Thu", "Thu", "Fri", "Fri", "Sat", "Sat",
]

const menu = (
  <Button variant="outline" size="icon-sm" className="text-muted-foreground rounded-full">
    <Ellipsis />
    <span className="sr-only">More</span>
  </Button>
)

export default function DotPlotCardDemo() {
  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <DotPlotCard
        title="Transactions"
        value={106_000}
        format="compact"
        data={[1, 1, 2, 1, 2, 4, 6, 4, 2, 1, 2, 1, 1, 1]}
        labels={hours}
        delta={34_002}
        color="var(--color-green-600)"
        action={menu}
      />
      <DotPlotCard
        title="Customers"
        value={1_284}
        data={[1, 1, 2, 1, 2, 3, 4, 6, 4, 3, 2, 1, 2, 1, 1, 1]}
        labels={["Sat", "Sun", "Mon", "Mon", "Tue", "Tue", "Wed", "Thu", "Thu", "Fri", "Fri", "Sat", "Sat", "Sun", "Sun", "Sun"]}
        peakLabel="Highest"
        delta={320}
        color="var(--color-blue-600)"
        action={menu}
      />
    </div>
  )
}
```

## Source

### components/dot-plot-card.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { type NumberFormat } from "@/lib/format"
import { Card, CardAction, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
import { DotPlot } from "@/components/ui/dot-plot"
import { MetricValue } from "@/components/ui/metric-value"

export interface DotPlotCardProps extends Omit<React.ComponentProps<typeof Card>, "children"> {
  title: string
  /** Headline value. Numbers are formatted with `format`; strings render as-is. */
  value: number | string
  format?: NumberFormat
  /** ISO 4217 code, used when `format` is "currency". */
  currency?: string
  /** One value per column of the dot plot. */
  data: number[]
  /** Label per column. The peak's label is shown in the pill, e.g. "Wed". */
  labels?: string[]
  /** Text before the peak's label in the pill, e.g. "Peak" for "Peak: Wed". */
  peakLabel?: string
  /** Absolute change vs the previous period, in the same unit as `value`, e.g. 34002 for +34,002. */
  delta?: number
  /** Context for the delta, e.g. "vs last period". */
  deltaLabel?: string
  /** Format for the delta. Defaults to `format`, except a compact value gets a full number so "+34,002" is not lost to "+34K". */
  deltaFormat?: NumberFormat
  /** Any CSS color for the dots. Defaults to chart-1. */
  color?: string
  /** Number of dots in the tallest column. */
  rows?: number
  /** Formats a column's value in the pill while it is hovered. Defaults to a plain grouped number. */
  valueFormatter?: (value: number) => string
  /** Slot in the top-right corner, e.g. a menu button. */
  action?: React.ReactNode
}

const signedFormatters = new Map<string, Intl.NumberFormat>()

/** "+34,002", "-1.2K", or "+$390" depending on the format. */
function formatSigned(value: number, format: NumberFormat, currency: string) {
  const key = `${format}:${currency}`
  let formatter = signedFormatters.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat("en-US", {
      ...(format === "currency" ? { style: "currency", currency } : {}),
      ...(format === "percent" ? { style: "percent" } : {}),
      ...(format === "compact" ? { notation: "compact" } : {}),
      signDisplay: "exceptZero",
      maximumFractionDigits: format === "number" ? 0 : 1,
    })
    signedFormatters.set(key, formatter)
  }
  return formatter.format(value)
}

/** A metric card with a big value, a dot-plot distribution with its peak called out, and the change vs the previous period. */
function DotPlotCard({
  title,
  value,
  format = "number",
  currency = "USD",
  data,
  labels,
  peakLabel = "Peak",
  delta,
  deltaLabel = "vs last period",
  deltaFormat = format === "compact" ? "number" : format,
  color = "var(--chart-1)",
  rows = 6,
  valueFormatter = (columnValue) => columnValue.toLocaleString("en-US"),
  action,
  className,
  ...props
}: DotPlotCardProps) {
  const [active, setActive] = React.useState<number | null>(null)
  const peak = labels?.[data.indexOf(Math.max(...data))]
  // The pill doubles as the hover readout: it shows the peak by default and the hovered column's value while hovering.
  const pill =
    active !== null ? (
      <>
        {labels?.[active] !== undefined ? `${labels[active]}: ` : null}
        <span className="text-foreground font-medium">{valueFormatter(data[active] ?? 0)}</span>
      </>
    ) : peak !== undefined ? (
      <>
        {peakLabel}: <span className="text-foreground font-medium">{peak}</span>
      </>
    ) : null
  return (
    <Card data-slot="dot-plot-card" className={cn("gap-4 py-5", className)} {...props}>
      <CardHeader className="px-5">
        <CardTitle className="text-base">{title}</CardTitle>
        {action ? <CardAction>{action}</CardAction> : null}
      </CardHeader>
      <CardContent className="@container px-5">
        {/*
          Narrow: pill, then value and delta side by side, then the plot on its own row.
          From 24rem: value | plot | delta on one row with the pill centered above the plot.
        */}
        <div className="grid grid-cols-[minmax(0,1fr)_auto] items-center gap-x-4 gap-y-3 @sm:grid-cols-[auto_minmax(0,1fr)_auto]">
          {pill !== null ? (
            <span className="bg-muted text-muted-foreground col-span-2 justify-self-center rounded-full px-3 py-1.5 text-xs whitespace-nowrap @sm:col-span-1 @sm:col-start-2">
              {pill}
            </span>
          ) : null}
          <MetricValue
            value={value}
            format={format}
            currency={currency}
            className="col-start-1 row-start-2 text-4xl font-semibold tracking-tight"
          />
          <DotPlot
            data={data}
            labels={labels}
            rows={rows}
            color={color}
            showTooltip={false}
            onActiveIndexChange={setActive}
            className="col-span-2 row-start-3 @sm:col-span-1 @sm:col-start-2 @sm:row-start-2"
          />
          {delta !== undefined ? (
            <div className="col-start-2 row-start-2 flex flex-col items-end @sm:col-start-3">
              <span className="text-muted-foreground text-xs">{deltaLabel}</span>
              <span className="text-xl font-semibold tabular-nums tracking-tight">
                {formatSigned(delta, deltaFormat, currency)}
              </span>
            </div>
          ) : null}
        </div>
      </CardContent>
    </Card>
  )
}

export { DotPlotCard }
```

### components/ui/dot-plot.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"

export interface DotPlotProps extends React.ComponentProps<"div"> {
  /** One value per column, in order. */
  data: number[]
  /** Optional label per column, shown in the tooltip and used for the accessible name. */
  labels?: string[]
  /** The value that fills a column. Defaults to the largest value in `data`. */
  max?: number
  /** Number of dots in a full column. */
  rows?: number
  /** Any CSS color. Defaults to chart-1. */
  color?: string
  /**
   * Columns at or above this fraction of `max` are drawn at full strength and the
   * rest are faded, so the peak stands out. Set to 0 to draw every column at full strength.
   */
  emphasis?: number
  /** Opacity of the faded columns. */
  fadedOpacity?: number
  /** Show a tooltip with the column's label and value while it is hovered. */
  showTooltip?: boolean
  /** Formats the value in the tooltip. Defaults to a plain grouped number. */
  valueFormatter?: (value: number) => string
  /** Index of the hovered column, to control it from outside. */
  activeIndex?: number | null
  /** Called when the hovered column changes, with null when the pointer leaves. */
  onActiveIndexChange?: (index: number | null) => void
}

const defaultFormatter = (value: number) => value.toLocaleString("en-US")

/**
 * A distribution drawn as columns of stacked dots, with the peak columns at full strength.
 * Hovering a column lights it up, fades the others, and shows its value.
 */
function DotPlot({
  data,
  labels,
  max,
  rows = 6,
  color = "var(--chart-1)",
  emphasis = 0.5,
  fadedOpacity = 0.35,
  showTooltip = true,
  valueFormatter = defaultFormatter,
  activeIndex,
  onActiveIndexChange,
  className,
  ...props
}: DotPlotProps) {
  const [internal, setInternal] = React.useState<number | null>(null)
  const active = activeIndex === undefined ? internal : activeIndex
  const setActive = (index: number | null) => {
    setInternal(index)
    onActiveIndexChange?.(index)
  }

  const top = max ?? Math.max(0, ...data)
  const peak = data.indexOf(Math.max(...data))
  const peakLabel = labels?.[peak]

  return (
    <div
      data-slot="dot-plot"
      role="img"
      aria-label={
        peakLabel !== undefined
          ? `Distribution across ${data.length} points, peaking at ${peakLabel}`
          : `Distribution across ${data.length} points`
      }
      onPointerLeave={() => setActive(null)}
      className={cn(
        // Dot size and gap are variables so they can be tuned from className, e.g. "[--dot-size:0.75rem]".
        "flex w-full justify-center [--dot-gap:0.25rem] [--dot-size:0.625rem]",
        className
      )}
      {...props}
    >
      {data.map((value, index) => {
        const fraction = Math.min(1, Math.max(0, value / (top || 1)))
        // Any non-zero value shows at least one dot so small values still register.
        const count = fraction === 0 ? 0 : Math.max(1, Math.round(fraction * rows))
        const strong = emphasis <= 0 || fraction >= emphasis
        // While a column is hovered it alone is lit; otherwise the emphasized columns are.
        const lit = active === null ? strong : active === index
        const label = labels?.[index]
        return (
          <div
            key={index}
            data-slot="dot-plot-column"
            data-emphasis={strong}
            data-active={active === index}
            onPointerEnter={() => setActive(index)}
            // Columns stretch to the full height and carry the gap as padding, so the hover target has no dead zones.
            // They share the width equally and cap at the dot size, so dots shrink in narrow cards instead of overflowing.
            className="relative flex min-w-0 flex-1 cursor-default flex-col-reverse justify-start gap-(--dot-gap) px-[calc(var(--dot-gap)/2)] max-w-[calc(var(--dot-size)+var(--dot-gap))]"
          >
            {Array.from({ length: count }, (_, dot) => (
              <span
                key={dot}
                className="aspect-square w-full rounded-full transition-opacity"
                style={{ backgroundColor: color, opacity: lit ? 1 : fadedOpacity }}
              />
            ))}
            {showTooltip && active === index ? (
              <span
                role="tooltip"
                className="bg-popover text-popover-foreground pointer-events-none absolute bottom-full left-1/2 z-10 mb-1.5 flex -translate-x-1/2 items-baseline gap-1.5 rounded-md border px-2 py-1 text-xs whitespace-nowrap shadow-md"
              >
                {label !== undefined ? (
                  <span className="text-muted-foreground">{label}</span>
                ) : null}
                <span className="font-medium tabular-nums">{valueFormatter(value)}</span>
              </span>
            ) : null}
          </div>
        )
      })}
    </div>
  )
}

export { DotPlot }
```

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Dual Metric Card

A card with two metrics side by side, each with a value, share badge, meter, and a supporting fact.

Two metrics side by side in one card, each with a value, a share badge, a meter, and a supporting fact. Use it when two numbers are best read together, like new and returning leads.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/dual-metric-card.json
```

Also installs `card`, `button`, `dropdown-menu`, `tooltip` from shadcn/ui if missing.

npm dependencies: `lucide-react`.

## Usage

```tsx
import { DualMetricCard } from "@/components/dual-metric-card"

<DualMetricCard
  title="Leads overview"
  options={[
    { value: "month", label: "This month" },
    { value: "quarter", label: "This quarter" },
  ]}
  metrics={[
    { label: "New leads", value: 54, showShare: true, meter: "bar", detail: { label: "Top source", value: "LinkedIn" } },
    { label: "Returning leads", value: 198, meter: "ticks", detail: { label: "Conversion rate", value: "12.8%" } },
  ]}
/>
```

## Examples

### Default

```tsx
import { DualMetricCard } from "@/registry/dashboardcn/blocks/dual-metric-card"

export default function DualMetricCardDemo() {
  return (
    <DualMetricCard
      className="w-full max-w-md"
      title="Leads overview"
      options={[
        { value: "month", label: "This month" },
        { value: "quarter", label: "This quarter" },
        { value: "year", label: "This year" },
      ]}
      metrics={[
        {
          label: "New leads",
          value: 54,
          showShare: true,
          meter: "bar",
          color: "var(--color-violet-500)",
          detail: { label: "Top source", value: "LinkedIn" },
        },
        {
          label: "Returning leads",
          value: 198,
          meter: "ticks",
          color: "var(--color-emerald-500)",
          detail: {
            label: "Conversion rate",
            value: "12.8%",
            description: "Share of returning leads that converted this period.",
          },
        },
      ]}
    />
  )
}
```

## Source

### components/dual-metric-card.tsx

```tsx
"use client"

import * as React from "react"
import { ChevronDown, Info } from "lucide-react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import { Button } from "@/components/ui/button"
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"
import { TickBar } from "@/components/ui/tick-bar"
import { MetricValue } from "@/components/ui/metric-value"

export interface DualMetricCardMetric {
  label: string
  value: number
  format?: NumberFormat
  currency?: string
  /** Bar fill from 0 to 100. Defaults to the metric's share of the total across all metrics. */
  progress?: number
  /** Show the metric's share of the total as a badge next to the value. */
  showShare?: boolean
  /** "ticks" draws a tick bar, "bar" a continuous bar. */
  meter?: "ticks" | "bar"
  /** Any CSS color. Defaults to chart-1 through chart-5 in order. */
  color?: string
  /** A supporting fact under the meter, e.g. { label: "Top source", value: "LinkedIn" }. */
  detail?: {
    label: string
    value: React.ReactNode
    /** Shown in a tooltip behind an info icon next to the label. */
    description?: string
  }
}

export interface DualMetricCardOption {
  value: string
  label: string
}

export interface DualMetricCardProps extends React.ComponentProps<typeof Card> {
  title: string
  /** Usually two metrics, shown side by side. */
  metrics: DualMetricCardMetric[]
  /** Options for the header dropdown. Omit to hide it. */
  options?: DualMetricCardOption[]
  value?: string
  defaultValue?: string
  onValueChange?: (value: string) => void
  /** Number of ticks in each tick bar. */
  segments?: number
}

const defaultColors = [
  "var(--chart-1)",
  "var(--chart-2)",
  "var(--chart-3)",
  "var(--chart-4)",
  "var(--chart-5)",
]

/** A card with two metrics side by side, each with a value, share badge, meter, and a supporting fact. */
function DualMetricCard({
  title,
  metrics,
  options,
  value,
  defaultValue,
  onValueChange,
  segments = 30,
  className,
  ...props
}: DualMetricCardProps) {
  const [internal, setInternal] = React.useState(defaultValue ?? options?.[0]?.value ?? "")
  const selected = value ?? internal
  const selectedLabel = options?.find((option) => option.value === selected)?.label
  const total = metrics.reduce((acc, metric) => acc + metric.value, 0)

  return (
    <Card data-slot="dual-metric-card" className={cn("gap-0 py-0", className)} {...props}>
      <CardHeader className="flex items-center justify-between gap-3 border-b py-3 [.border-b]:pb-3">
        <CardTitle className="text-sm">{title}</CardTitle>
        {options?.length ? (
          <DropdownMenu>
            <DropdownMenuTrigger asChild>
              <Button variant="outline" size="sm">
                {selectedLabel}
                <ChevronDown className="text-muted-foreground" />
              </Button>
            </DropdownMenuTrigger>
            <DropdownMenuContent align="end">
              <DropdownMenuRadioGroup
                value={selected}
                onValueChange={(next) => {
                  setInternal(next)
                  onValueChange?.(next)
                }}
              >
                {options.map((option) => (
                  <DropdownMenuRadioItem key={option.value} value={option.value}>
                    {option.label}
                  </DropdownMenuRadioItem>
                ))}
              </DropdownMenuRadioGroup>
            </DropdownMenuContent>
          </DropdownMenu>
        ) : null}
      </CardHeader>
      <CardContent className="@container py-5">
        <TooltipProvider>
          <div className="grid gap-6 @xs:grid-cols-2 @xs:gap-0 @xs:divide-x">
            {metrics.map((metric, index) => {
              const color = metric.color ?? defaultColors[index % defaultColors.length]
              const share = total ? metric.value / total : 0
              const fill = metric.progress ?? share * 100
              return (
                <div
                  key={metric.label}
                  data-slot="dual-metric"
                  className="flex min-w-0 flex-col gap-1 @xs:px-5 @xs:first:pl-0 @xs:last:pr-0"
                >
                  <div className="flex flex-wrap items-center gap-2">
                    <MetricValue
                      value={metric.value}
                      format={metric.format}
                      currency={metric.currency}
                      className="text-3xl font-semibold tracking-tight"
                    />
                    {metric.showShare ? (
                      <span
                        className="rounded-md px-1.5 py-0.5 text-xs font-medium tabular-nums"
                        style={{
                          color,
                          backgroundColor: `color-mix(in oklab, ${color} 15%, transparent)`,
                        }}
                      >
                        {formatNumber(share, { format: "percent", maximumFractionDigits: 2 })}
                      </span>
                    ) : null}
                  </div>
                  <span className="text-muted-foreground text-sm">{metric.label}</span>
                  <div className="mt-2 flex h-4 items-center">
                    {metric.meter === "bar" ? (
                      <div
                        role="progressbar"
                        aria-valuemin={0}
                        aria-valuemax={100}
                        aria-valuenow={Math.round(fill)}
                        className="bg-muted h-2 w-full overflow-hidden rounded-full"
                      >
                        <div
                          className="h-full rounded-full transition-[width]"
                          style={{ width: `${Math.min(100, Math.max(0, fill))}%`, backgroundColor: color }}
                        />
                      </div>
                    ) : (
                      <TickBar value={fill} segments={segments} color={color} className="h-4 gap-0.5" />
                    )}
                  </div>
                  {metric.detail ? (
                    <div className="mt-4 flex flex-col gap-0.5">
                      <span className="text-muted-foreground flex items-center gap-1 text-xs">
                        {metric.detail.label}
                        {metric.detail.description ? (
                          <Tooltip>
                            <TooltipTrigger asChild>
                              <button
                                type="button"
                                className="hover:text-foreground inline-flex rounded-full"
                              >
                                <Info className="size-3.5" />
                                <span className="sr-only">About {metric.detail.label}</span>
                              </button>
                            </TooltipTrigger>
                            <TooltipContent className="max-w-56">
                              {metric.detail.description}
                            </TooltipContent>
                          </Tooltip>
                        ) : null}
                      </span>
                      <span className="text-sm font-medium tabular-nums">{metric.detail.value}</span>
                    </div>
                  ) : null}
                </div>
              )
            })}
          </div>
        </TooltipProvider>
      </CardContent>
    </Card>
  )
}

export { DualMetricCard }
```

### components/ui/tick-bar.tsx

```tsx
import * as React from "react"

import { cn } from "@/lib/utils"

export interface TickBarProps extends React.ComponentProps<"div"> {
  /** Current value, from 0 to max. */
  value: number
  max?: number
  /** Number of ticks. */
  segments?: number
  /** Any CSS color for the filled ticks. Defaults to chart-1. */
  color?: string
  /** Any CSS color for the unfilled ticks. Defaults to muted. */
  trackColor?: string
  /** "tick" draws thin bars; "pill" draws wide rounded ones. */
  shape?: "tick" | "pill"
}

/** A progress bar drawn as a row of ticks, lit up to the current value. */
function TickBar({
  value,
  max = 100,
  segments = 40,
  color = "var(--chart-1)",
  trackColor,
  shape = "tick",
  className,
  ...props
}: TickBarProps) {
  const fraction = Math.min(1, Math.max(0, value / (max || 1)))
  // Any non-zero value lights at least one tick so small values still register.
  const filled = fraction === 0 ? 0 : Math.max(1, Math.round(fraction * segments))

  return (
    <div
      data-slot="tick-bar"
      data-shape={shape}
      role="progressbar"
      aria-valuemin={0}
      aria-valuemax={max}
      aria-valuenow={value}
      className={cn(
        "flex w-full",
        shape === "tick" ? "h-6 gap-[3px]" : "h-4 gap-1.5",
        className
      )}
      {...props}
    >
      {Array.from({ length: segments }, (_, index) => {
        const lit = index < filled
        return (
          <span
            key={index}
            data-filled={lit}
            className={cn(
              "bg-muted h-full min-w-0 flex-1 transition-colors",
              shape === "tick" ? "rounded-[1.5px]" : "rounded-full"
            )}
            style={{ backgroundColor: lit ? color : trackColor }}
          />
        )
      })}
    </div>
  )
}

export { TickBar }
```

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Funnel Chart Card

A conversion card with a flow funnel: a headline value with delta, a range picker that carries its own steps, and a tile per stage. Hovering a stage swaps the headline.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/funnel-chart-card.json
```

Also installs `card`, `button`, `dropdown-menu`, `tooltip` from shadcn/ui if missing.

npm dependencies: `lucide-react`.

## Usage

```tsx
import { FunnelChartCard } from "@/components/funnel-chart-card"

// A static funnel with a caption.
<FunnelChartCard
  title="Sign-up funnel"
  caption="Last 7 days"
  delta={0.052}
  deltaLabel="vs previous period"
  steps={[
    { name: "Link opened", value: 197, color: "var(--color-lime-400)" },
    { name: "Started", value: 110, color: "var(--color-blue-500)" },
    { name: "Completed", value: 77, color: "var(--color-violet-500)" },
    { name: "Converted", value: 38, color: "var(--color-pink-500)" },
  ]}
/>

// Or a range picker where each range carries its own steps and delta.
<FunnelChartCard
  title="Sign-up funnel"
  ranges={[
    { value: "7d", label: "Last 7 days", steps: week, delta: 0.052 },
    { value: "30d", label: "Last 30 days", steps: month, delta: 0.118 },
  ]}
/>
```

## Examples

### Default

```tsx
import { FunnelChartCard } from "@/registry/dashboardcn/blocks/funnel-chart-card"

const colors = {
  opened: "var(--color-lime-400)",
  started: "var(--color-blue-500)",
  completed: "var(--color-violet-500)",
  converted: "var(--color-pink-500)",
}

const ranges = [
  {
    value: "7d",
    label: "Last 7 days",
    delta: 0.052,
    steps: [
      { name: "Link opened", value: 197, color: colors.opened },
      { name: "Started", value: 110, color: colors.started },
      { name: "Completed", value: 77, color: colors.completed },
      { name: "Converted", value: 38, color: colors.converted },
    ],
  },
  {
    value: "30d",
    label: "Last 30 days",
    delta: 0.118,
    steps: [
      { name: "Link opened", value: 842, color: colors.opened },
      { name: "Started", value: 512, color: colors.started },
      { name: "Completed", value: 301, color: colors.completed },
      { name: "Converted", value: 129, color: colors.converted },
    ],
  },
  {
    value: "90d",
    label: "Last 90 days",
    delta: -0.021,
    steps: [
      { name: "Link opened", value: 2610, color: colors.opened },
      { name: "Started", value: 1380, color: colors.started },
      { name: "Completed", value: 902, color: colors.completed },
      { name: "Converted", value: 355, color: colors.converted },
    ],
  },
]

export default function FunnelChartCardDemo() {
  return (
    <FunnelChartCard
      className="w-full max-w-xl"
      title="Sign-up funnel"
      deltaLabel="vs previous period"
      ranges={ranges}
    />
  )
}
```

## Source

### components/funnel-chart-card.tsx

```tsx
"use client"

import * as React from "react"
import { ChevronDown } from "lucide-react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import { Button } from "@/components/ui/button"
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@/components/ui/card"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
import { DeltaBadge } from "@/components/ui/delta-badge"
import { FunnelChart, type FunnelChartProps, type FunnelStep } from "@/components/ui/funnel-chart"
import { MetricValue } from "@/components/ui/metric-value"

export interface FunnelRange {
  value: string
  label: string
  /** Top of the funnel first. */
  steps: FunnelStep[]
  /** Change in the first step vs the previous range, as a fraction. */
  delta?: number
}

export interface FunnelChartCardProps
  extends Omit<React.ComponentProps<typeof Card>, "children"> {
  title: string
  /** Top of the funnel first. Ignored when `ranges` is set. */
  steps?: FunnelStep[]
  /** Change in the first step, as a fraction. Ignored when `ranges` is set. */
  delta?: number
  /** Context for the delta, e.g. "vs last week". */
  deltaLabel?: string
  invertDelta?: boolean
  /** Static text in the header, e.g. "Last 30 days". Replaced by the picker when `ranges` is set. */
  caption?: string
  /** Ranges for the header picker. Each carries its own steps. */
  ranges?: FunnelRange[]
  range?: string
  defaultRange?: string
  onRangeChange?: (value: string) => void
  format?: NumberFormat
  currency?: string
  color?: FunnelChartProps["color"]
  shape?: FunnelChartProps["shape"]
  height?: FunnelChartProps["height"]
  neckWidth?: FunnelChartProps["neckWidth"]
  showPercentages?: FunnelChartProps["showPercentages"]
  showLabels?: FunnelChartProps["showLabels"]
  chartClassName?: string
}

/** A conversion card with a flow funnel: headline value, delta, and a range picker. Hovering a stage swaps the headline to that stage. */
function FunnelChartCard({
  title,
  steps: stepsProp = [],
  delta: deltaProp,
  deltaLabel,
  invertDelta,
  caption,
  ranges,
  range: rangeProp,
  defaultRange,
  onRangeChange,
  format = "number",
  currency,
  color,
  shape,
  height,
  neckWidth,
  showPercentages,
  showLabels,
  chartClassName,
  className,
  ...props
}: FunnelChartCardProps) {
  const [rangeState, setRangeState] = React.useState(defaultRange ?? ranges?.[0]?.value)
  const range = rangeProp ?? rangeState
  const setRange = (value: string) => {
    setRangeState(value)
    onRangeChange?.(value)
  }
  const current = ranges?.find((option) => option.value === range) ?? ranges?.[0]
  const steps = current?.steps ?? stepsProp
  const delta = current ? current.delta : deltaProp

  const [active, setActive] = React.useState<number | null>(null)
  const first = steps[0]
  const hovered = active !== null ? steps[active] : undefined
  const headline = hovered ?? first
  const share = hovered && first && first.value > 0 ? hovered.value / first.value : null

  const valueFormatter = React.useCallback(
    (value: number) => formatNumber(value, { format, currency }),
    [format, currency]
  )

  return (
    <Card data-slot="funnel-chart-card" className={cn("gap-4", className)} {...props}>
      <CardHeader>
        <CardDescription>{title}</CardDescription>
        <CardTitle className="text-3xl font-semibold tabular-nums tracking-tight">
          <MetricValue value={headline?.value ?? 0} format={format} currency={currency} />
        </CardTitle>
        <div className="flex h-5 items-center gap-1.5 text-sm">
          {hovered && share !== null ? (
            <span className="text-muted-foreground truncate">
              {hovered.name}
              {hovered !== first ? (
                <>
                  {" · "}
                  <span className="text-foreground font-medium tabular-nums">
                    {formatNumber(share, { format: "percent", maximumFractionDigits: 0 })}
                  </span>{" "}
                  of {first?.name}
                </>
              ) : null}
            </span>
          ) : (
            <>
              {delta !== undefined ? (
                <DeltaBadge delta={delta} invert={invertDelta} variant="soft" />
              ) : null}
              {deltaLabel ? <span className="text-muted-foreground">{deltaLabel}</span> : null}
            </>
          )}
        </div>
        {ranges?.length ? (
          <CardAction>
            <DropdownMenu>
              <DropdownMenuTrigger asChild>
                <Button variant="outline" size="sm">
                  {current?.label}
                  <ChevronDown className="text-muted-foreground" />
                </Button>
              </DropdownMenuTrigger>
              <DropdownMenuContent align="end">
                <DropdownMenuRadioGroup value={range} onValueChange={setRange}>
                  {ranges.map((option) => (
                    <DropdownMenuRadioItem key={option.value} value={option.value}>
                      {option.label}
                    </DropdownMenuRadioItem>
                  ))}
                </DropdownMenuRadioGroup>
              </DropdownMenuContent>
            </DropdownMenu>
          </CardAction>
        ) : caption ? (
          <CardAction>
            <span className="text-muted-foreground text-sm">{caption}</span>
          </CardAction>
        ) : null}
      </CardHeader>
      <CardContent>
        <FunnelChart
          variant="flow"
          steps={steps}
          valueFormatter={valueFormatter}
          color={color}
          shape={shape}
          height={height}
          neckWidth={neckWidth}
          showPercentages={showPercentages}
          showLabels={showLabels}
          activeIndex={active}
          onActiveIndexChange={setActive}
          className={chartClassName}
        />
      </CardContent>
    </Card>
  )
}

export { FunnelChartCard }
```

### components/ui/funnel-chart.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber } from "@/lib/format"

export interface FunnelStep {
  name: string
  value: number
  /** Any CSS color for this step in the flow variant. Defaults to chart-1 through chart-5 in order. */
  color?: string
}

export interface FunnelChartProps extends React.ComponentProps<"div"> {
  steps: FunnelStep[]
  valueFormatter?: (value: number) => string
  /**
   * Any CSS color. "bars" fades it step by step. "flow" paints every stage in
   * it, in place of the per-stage palette.
   */
  color?: string
  /** Show the drop-off between consecutive steps. Bars only. */
  showDropoff?: boolean
  /** "bars" stacks one bar per step; "flow" runs the steps left to right, each tapering into the next. */
  variant?: "bars" | "flow"
  /** Flow only. "eased" curves each neck; "sharp" draws straight trapezoids. */
  shape?: "eased" | "sharp"
  /** Flow only. Height of the stages in pixels. */
  height?: number
  /** Flow only. Width of the neck between stages in pixels. */
  neckWidth?: number
  /** Flow only. Show the share of the first step as a pill on each stage. */
  showPercentages?: boolean
  /** Flow only. Show a tile with the name and value under each stage. */
  showLabels?: boolean
  /** Flow only. Stage drawn at full strength while the rest dim. */
  activeIndex?: number | null
  onActiveIndexChange?: (index: number | null) => void
}

const defaultColors = [
  "var(--chart-1)",
  "var(--chart-2)",
  "var(--chart-3)",
  "var(--chart-4)",
  "var(--chart-5)",
]

// Round so server and client render identical path strings.
const round = (n: number) => Math.round(n * 1000) / 1000

/** Path for the neck between two stages, in a 1x1 box stretched to fit. */
function neckPath(from: number, to: number, shape: "eased" | "sharp") {
  const t0 = round((1 - from) / 2)
  const b0 = round(1 - t0)
  const t1 = round((1 - to) / 2)
  const b1 = round(1 - t1)
  if (shape === "sharp") return `M0,${t0} L1,${t1} L1,${b1} L0,${b0} Z`
  return `M0,${t0} C0.5,${t0} 0.5,${t1} 1,${t1} L1,${b1} C0.5,${b1} 0.5,${b0} 0,${b0} Z`
}

function FunnelBars({
  steps,
  valueFormatter,
  color,
  showDropoff,
}: {
  steps: FunnelStep[]
  valueFormatter: (value: number) => string
  color: string
  showDropoff: boolean
}) {
  const first = steps[0]?.value ?? 0
  const last = steps[steps.length - 1]?.value ?? 0
  const overall = first > 0 ? last / first : 0

  return (
    <>
      {steps.map((step, index) => {
        const previous = index > 0 ? steps[index - 1]!.value : step.value
        const ofFirst = first > 0 ? step.value / first : 0
        const ofPrevious = previous > 0 ? step.value / previous : 0
        const dropoff = 1 - ofPrevious

        return (
          <React.Fragment key={step.name}>
            {showDropoff && index > 0 ? (
              <div className="text-muted-foreground flex items-center gap-2 py-1 pl-3 text-xs">
                <span aria-hidden="true" className="bg-border h-3 w-px" />
                <span className="tabular-nums">
                  {formatNumber(dropoff, { format: "percent" })} drop-off
                </span>
              </div>
            ) : null}
            <div data-slot="funnel-step" className="flex flex-col gap-1.5">
              <div className="flex items-baseline justify-between gap-4 text-sm">
                <span className="flex items-center gap-2 truncate">
                  <span className="text-muted-foreground w-4 shrink-0 text-xs tabular-nums">
                    {index + 1}
                  </span>
                  <span className="truncate font-medium">{step.name}</span>
                </span>
                <span className="flex shrink-0 items-baseline gap-2 tabular-nums">
                  <span className="font-medium">{valueFormatter(step.value)}</span>
                  <span className="text-muted-foreground w-12 text-right text-xs">
                    {formatNumber(ofFirst, { format: "percent" })}
                  </span>
                </span>
              </div>
              <div className="bg-muted h-6 w-full overflow-hidden rounded-md">
                <div
                  className="h-full rounded-md transition-[width] duration-300"
                  style={{
                    width: `${ofFirst * 100}%`,
                    backgroundColor: color,
                    opacity: 1 - index * (0.5 / Math.max(steps.length - 1, 1)),
                  }}
                />
              </div>
            </div>
          </React.Fragment>
        )
      })}
      {steps.length > 1 ? (
        <div className="mt-2 flex items-center justify-between border-t pt-3 text-sm">
          <span className="text-muted-foreground">Overall conversion</span>
          <span className="font-semibold tabular-nums">
            {formatNumber(overall, { format: "percent" })}
          </span>
        </div>
      ) : null}
    </>
  )
}

function FunnelFlow({
  steps,
  valueFormatter,
  color,
  shape,
  height,
  neckWidth,
  showPercentages,
  showLabels,
  activeIndex,
  onActiveIndexChange,
}: {
  steps: FunnelStep[]
  valueFormatter: (value: number) => string
  color?: string
  shape: "eased" | "sharp"
  height: number
  neckWidth: number
  showPercentages: boolean
  showLabels: boolean
  activeIndex?: number | null
  onActiveIndexChange?: (index: number | null) => void
}) {
  const id = React.useId()
  const [activeState, setActiveState] = React.useState<number | null>(null)
  const active = activeIndex === undefined ? activeState : activeIndex
  const setActive = (index: number | null) => {
    setActiveState(index)
    onActiveIndexChange?.(index)
  }

  const first = steps[0]?.value ?? 0
  const stages = steps.map((step, index) => ({
    ...step,
    share: first > 0 ? Math.min(1, Math.max(0, step.value / first)) : 0,
    fill: step.color ?? color ?? defaultColors[index % defaultColors.length],
    // A single color fades toward the end of the funnel so stages stay distinct.
    opacity: color && !step.color ? 1 - index * (0.6 / Math.max(steps.length - 1, 1)) : 1,
  }))

  return (
    <>
      <div
        data-slot="funnel-flow"
        className="flex w-full items-stretch"
        style={{ height }}
        onMouseLeave={() => setActive(null)}
      >
        {stages.map((stage, index) => {
          const next = stages[index + 1]
          const dimmed = active !== null && active !== index
          const neckDimmed = active !== null && active !== index && active !== index + 1
          const gradient = `${id}-${index}`
          return (
            <React.Fragment key={stage.name}>
              <div
                data-slot="funnel-stage"
                data-active={active === index || undefined}
                onMouseEnter={() => setActive(index)}
                className="relative flex min-w-0 flex-1 items-center transition-opacity duration-200"
                style={{ opacity: dimmed ? 0.35 : 1 }}
              >
                <div
                  className={cn(
                    "w-full transition-[height] duration-500 ease-out",
                    index === 0 && "rounded-l-lg",
                    index === stages.length - 1 && "rounded-r-lg"
                  )}
                  style={{
                    height: `${round(stage.share * 100)}%`,
                    minHeight: 4,
                    backgroundColor: stage.fill,
                    opacity: stage.opacity,
                  }}
                />
                {showPercentages ? (
                  <span className="bg-background/90 text-foreground ring-foreground/10 pointer-events-none absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 rounded-full px-2 py-0.5 text-[11px] font-medium tabular-nums shadow-xs ring-1 backdrop-blur-sm">
                    {formatNumber(stage.share, { format: "percent", maximumFractionDigits: 0 })}
                  </span>
                ) : null}
              </div>
              {next ? (
                <svg
                  aria-hidden="true"
                  data-slot="funnel-neck"
                  viewBox="0 0 1 1"
                  preserveAspectRatio="none"
                  className="h-full shrink-0 transition-opacity duration-200"
                  style={{ width: neckWidth, opacity: neckDimmed ? 0.35 : 1 }}
                >
                  <defs>
                    <linearGradient id={gradient} x1="0" y1="0" x2="1" y2="0">
                      <stop offset="0" stopColor={stage.fill} stopOpacity={stage.opacity} />
                      <stop offset="1" stopColor={next.fill} stopOpacity={next.opacity} />
                    </linearGradient>
                  </defs>
                  <path
                    d={neckPath(stage.share, next.share, shape)}
                    fill={`url(#${gradient})`}
                    className="transition-[d] duration-500 ease-out"
                  />
                </svg>
              ) : null}
            </React.Fragment>
          )
        })}
      </div>
      {showLabels ? (
        <div
          data-slot="funnel-labels"
          className="grid gap-2"
          style={{ gridTemplateColumns: `repeat(${stages.length}, minmax(0, 1fr))` }}
        >
          {stages.map((stage, index) => (
            <div
              key={stage.name}
              data-active={active === index || undefined}
              onMouseEnter={() => setActive(index)}
              onMouseLeave={() => setActive(null)}
              className={cn(
                "flex min-w-0 flex-col gap-0.5 rounded-lg border px-2.5 py-2 transition-[opacity,border-color] duration-200",
                active !== null && active !== index && "opacity-50",
                active === index && "border-foreground/20"
              )}
            >
              <span className="text-muted-foreground flex items-center gap-1.5 text-xs">
                <span
                  aria-hidden="true"
                  className="size-2 shrink-0 rounded-full"
                  style={{ backgroundColor: stage.fill, opacity: stage.opacity }}
                />
                <span className="truncate">{stage.name}</span>
              </span>
              <span className="truncate text-sm font-semibold tabular-nums">
                {valueFormatter(stage.value)}
              </span>
            </div>
          ))}
        </div>
      ) : null}
    </>
  )
}

/** Step-by-step conversion, as stacked bars with drop-off or as a flow of tapering stages. */
function FunnelChart({
  steps,
  valueFormatter = (value) => formatNumber(value),
  color,
  showDropoff = true,
  variant = "bars",
  shape = "eased",
  height = 160,
  neckWidth = 24,
  showPercentages = true,
  showLabels = true,
  activeIndex,
  onActiveIndexChange,
  className,
  ...props
}: FunnelChartProps) {
  return (
    <div
      data-slot="funnel-chart"
      data-variant={variant}
      className={cn("flex flex-col", variant === "flow" ? "gap-3" : "gap-1", className)}
      {...props}
    >
      {variant === "flow" ? (
        <FunnelFlow
          steps={steps}
          valueFormatter={valueFormatter}
          color={color}
          shape={shape}
          height={height}
          neckWidth={neckWidth}
          showPercentages={showPercentages}
          showLabels={showLabels}
          activeIndex={activeIndex}
          onActiveIndexChange={onActiveIndexChange}
        />
      ) : (
        <FunnelBars
          steps={steps}
          valueFormatter={valueFormatter}
          color={color ?? "var(--chart-1)"}
          showDropoff={showDropoff}
        />
      )}
    </div>
  )
}

export { FunnelChart }
```

### components/ui/delta-badge.tsx

```tsx
import * as React from "react"
import { Minus, TrendingDown, TrendingUp } from "lucide-react"

import { cn } from "@/lib/utils"
import { formatDelta } from "@/lib/format"

export type DeltaDirection = "up" | "down" | "flat"

export function getDeltaDirection(delta: number | undefined): DeltaDirection {
  if (delta === undefined || delta === 0 || !Number.isFinite(delta)) return "flat"
  return delta > 0 ? "up" : "down"
}

const directionIcon: Record<DeltaDirection, React.ElementType> = {
  up: TrendingUp,
  down: TrendingDown,
  flat: Minus,
}

export interface DeltaBadgeProps extends React.ComponentProps<"span"> {
  /** Fractional change, e.g. 0.124 for +12.4%. */
  delta: number
  /** Treat a decrease as good and an increase as bad (churn, latency, errors). */
  invert?: boolean
  variant?: "outline" | "soft" | "text"
  showIcon?: boolean
}

function DeltaBadge({
  delta,
  invert = false,
  variant = "outline",
  showIcon = true,
  className,
  children,
  ...props
}: DeltaBadgeProps) {
  const direction = getDeltaDirection(delta)
  const positive = direction === "flat" ? null : (direction === "up") !== invert
  const Icon = directionIcon[direction]

  return (
    <span
      data-slot="delta-badge"
      data-direction={direction}
      data-positive={positive}
      className={cn(
        "inline-flex items-center gap-1 text-xs font-medium tabular-nums",
        variant === "outline" && "rounded-md border px-1.5 py-0.5",
        variant === "soft" && "rounded-md px-1.5 py-0.5",
        variant === "soft" && positive === true && "bg-emerald-500/10",
        variant === "soft" && positive === false && "bg-red-500/10",
        variant === "soft" && positive === null && "bg-muted",
        positive === true && "text-emerald-600 dark:text-emerald-400",
        positive === false && "text-red-600 dark:text-red-400",
        positive === null && "text-muted-foreground",
        className
      )}
      {...props}
    >
      {showIcon ? <Icon className="size-3" aria-hidden="true" /> : null}
      {children ?? formatDelta(delta)}
    </span>
  )
}

export { DeltaBadge }
```

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Goal Chart Card

A card with a total, a period switcher, and a bar chart with a dashed goal line that colors the bars reaching it.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/goal-chart-card.json
```

Also installs `card`, `chart`, `tabs`, `tooltip` from shadcn/ui if missing.

npm dependencies: `recharts`, `lucide-react`.

## Usage

```tsx
import { GoalChartCard } from "@/components/goal-chart-card"

<GoalChartCard
  title="Steps"
  unit="total steps"
  data={steps}
  xKey="day"
  yKey="steps"
  goal={4000}
  color="var(--color-emerald-500)"
  delta={0.12}
  deltaLabel="vs last week"
  periods={[
    { value: "week", label: "Week" },
    { value: "month", label: "Month" },
  ]}
  onPeriodChange={setPeriod}
/>
```

## Examples

### Default

```tsx
"use client"

import * as React from "react"

import { GoalChartCard } from "@/registry/dashboardcn/blocks/goal-chart-card"

const week = [
  { day: "Mon", steps: 5_200 },
  { day: "Tue", steps: 3_100 },
  { day: "Wed", steps: 6_800 },
  { day: "Thu", steps: 2_400 },
  { day: "Fri", steps: 4_700 },
  { day: "Sat", steps: 5_600 },
  { day: "Sun", steps: 3_800 },
]

const month = Array.from({ length: 30 }, (_, i) => ({
  day: `2025-06-${String(i + 1).padStart(2, "0")}`,
  steps: 1_800 + ((i * 1_733) % 5_400),
}))

const data = { week, month }

export default function GoalChartCardDemo() {
  const [period, setPeriod] = React.useState<keyof typeof data>("week")

  return (
    <GoalChartCard
      className="w-full max-w-xl"
      title="Steps"
      unit="total steps"
      data={data[period]}
      xKey="day"
      yKey="steps"
      goal={4_000}
      color="var(--color-emerald-500)"
      delta={period === "week" ? 0.12 : 0.04}
      deltaLabel={period === "week" ? "vs last week" : "vs last month"}
      periods={[
        { value: "week", label: "Week" },
        { value: "month", label: "Month" },
      ]}
      period={period}
      onPeriodChange={(next) => setPeriod(next as keyof typeof data)}
    />
  )
}
```

## Source

### components/goal-chart-card.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@/components/ui/card"
import { BarChart, type BarChartProps, type BarRow } from "@/components/ui/bar-chart"
import { DeltaBadge } from "@/components/ui/delta-badge"
import { MetricValue } from "@/components/ui/metric-value"
import { PeriodTabs, type PeriodOption } from "@/components/ui/period-tabs"

export interface GoalChartCardProps extends React.ComponentProps<typeof Card> {
  title: string
  /** Headline number. Defaults to the sum of the rows. */
  value?: number
  format?: NumberFormat
  currency?: string
  /** Caption after the value, e.g. "total steps". */
  unit?: string
  /** Period text, e.g. "This week". Shown in the top-right corner unless periods is set. */
  caption?: string
  data: BarRow[]
  /** Key of the x-axis value in each row. */
  xKey: string
  /** Key of the bar value in each row. */
  yKey: string
  /** Target drawn as a dashed line. Bars at or above it are drawn in color. */
  goal: number
  goalLabel?: string
  /** Any CSS color for bars that reach the goal. Defaults to chart-1. */
  color?: string
  /** Any CSS color for bars below the goal. Defaults to the muted foreground. */
  mutedColor?: string
  variant?: BarChartProps["variant"]
  grid?: BarChartProps["grid"]
  xFormatter?: BarChartProps["xFormatter"]
  yFormatter?: BarChartProps["yFormatter"]
  chartClassName?: string
  /** Fractional change vs the prior period, e.g. 0.052 for +5.2%. */
  delta?: number
  /** Text after the delta, e.g. "vs last week". */
  deltaLabel?: string
  /** Treat a decrease as good. */
  invertDelta?: boolean
  /** Period options for the switcher. Omit to hide it. */
  periods?: PeriodOption[]
  period?: string
  defaultPeriod?: string
  onPeriodChange?: (period: string) => void
}

function sum(rows: BarRow[], key: string) {
  return rows.reduce((total, row) => total + (Number(row[key]) || 0), 0)
}

/** A card with a total, a period switcher, and a bar chart with a dashed goal line that colors the bars reaching it. */
function GoalChartCard({
  title,
  value,
  format = "number",
  currency,
  unit,
  caption,
  data,
  xKey,
  yKey,
  goal,
  goalLabel = "Goal",
  color,
  mutedColor,
  variant = "solid",
  grid = "none",
  xFormatter,
  yFormatter: yFormatterProp,
  chartClassName,
  delta,
  deltaLabel,
  invertDelta,
  periods,
  period,
  defaultPeriod,
  onPeriodChange,
  className,
  ...props
}: GoalChartCardProps) {
  const total = value ?? sum(data, yKey)
  const yFormatter = React.useCallback(
    (v: number) => formatNumber(v, { format, currency }),
    [format, currency]
  )
  const highlight = React.useCallback(
    (row: BarRow) => Number(row[yKey]) >= goal,
    [yKey, goal]
  )
  const showCaptionInline = Boolean(caption && periods)

  return (
    <Card data-slot="goal-chart-card" className={cn("gap-4", className)} {...props}>
      <CardHeader>
        <CardDescription>{title}</CardDescription>
        <CardTitle className="flex flex-wrap items-baseline gap-x-2 gap-y-1 text-3xl font-semibold tabular-nums tracking-tight">
          <MetricValue value={total} format={format} currency={currency} />
          {unit ? (
            <span className="text-muted-foreground text-sm font-normal">{unit}</span>
          ) : null}
        </CardTitle>
        {delta !== undefined || showCaptionInline ? (
          <div className="flex flex-wrap items-center gap-1.5 text-sm">
            {delta !== undefined ? (
              <DeltaBadge delta={delta} invert={invertDelta} variant="text" />
            ) : null}
            {deltaLabel || showCaptionInline ? (
              <span className="text-muted-foreground">
                {[deltaLabel, showCaptionInline ? caption : undefined]
                  .filter(Boolean)
                  .join(" · ")}
              </span>
            ) : null}
          </div>
        ) : null}
        {periods ? (
          <CardAction>
            <PeriodTabs
              options={periods}
              value={period}
              defaultValue={defaultPeriod ?? periods[0]?.value}
              onValueChange={onPeriodChange}
            />
          </CardAction>
        ) : caption ? (
          <CardAction>
            <span className="text-muted-foreground text-sm tabular-nums">{caption}</span>
          </CardAction>
        ) : null}
      </CardHeader>
      <CardContent>
        <BarChart
          data={data}
          xKey={xKey}
          yKey={yKey}
          variant={variant}
          color={color}
          mutedColor={mutedColor}
          grid={grid}
          highlight={highlight}
          referenceLines={[{ y: goal, label: goalLabel, dashed: true }]}
          xFormatter={xFormatter}
          yFormatter={yFormatterProp ?? yFormatter}
          className={cn("h-56", chartClassName)}
        />
      </CardContent>
    </Card>
  )
}

export { GoalChartCard }
```

### components/ui/bar-chart.tsx

```tsx
"use client"

import * as React from "react"
import {
  Bar,
  BarChart as RechartsBarChart,
  CartesianGrid,
  Cell,
  Rectangle,
  ReferenceLine,
  XAxis,
  YAxis,
} from "recharts"

import { cn } from "@/lib/utils"
import { ChartContainer, ChartTooltip } from "@/components/ui/chart"

export type BarRow = Record<string, unknown>

export interface BarReferenceLine {
  /** Horizontal line at this y value. */
  y: number
  label?: string
  /** Any CSS color. Defaults to the muted foreground. */
  color?: string
  /** Defaults to dashed. */
  dashed?: boolean
}

export interface BarChartProps
  extends Omit<React.ComponentProps<typeof ChartContainer>, "config" | "children"> {
  data: BarRow[]
  /** Key of the x-axis value in each row. */
  xKey: string
  /** Key of the bar value in each row. */
  yKey: string
  /**
   * Key of a coarser label, e.g. "month" for weekly rows. When set, the x-axis
   * shows one tick per group centered under its bars instead of a tick per bar.
   */
  groupKey?: string
  /** "gradient" fades each bar toward the bottom; "striped" fills it with diagonal bands. */
  variant?: "gradient" | "striped" | "solid"
  /** Any CSS color for highlighted bars. Defaults to chart-1. */
  color?: string
  /** Any CSS color for bars that are not highlighted. Defaults to the muted foreground. */
  mutedColor?: string
  /** Return true for bars drawn in color. Every bar is highlighted when omitted. */
  highlight?: (row: BarRow, index: number) => boolean
  grid?: "dashed" | "solid" | "none"
  showYAxis?: boolean
  showTooltip?: boolean
  /** Draw a hollow ring on top of the hovered bar. */
  showActiveMarker?: boolean
  barRadius?: number
  /** Horizontal lines, e.g. a goal or an average. The y-axis extends to fit them. */
  referenceLines?: BarReferenceLine[]
  xFormatter?: (value: unknown) => string
  yFormatter?: (value: number) => string
  /** Secondary line of the tooltip. Defaults to the formatted x value. */
  tooltipLabel?: (row: BarRow, index: number) => React.ReactNode
  onBarClick?: (row: BarRow, index: number) => void
}

function defaultXFormatter(value: unknown) {
  if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}/.test(value)) {
    const [y, m, d] = value.split("-").map(Number)
    return new Date(y!, m! - 1, d).toLocaleDateString("en-US", {
      month: "short",
      day: "numeric",
    })
  }
  return String(value)
}

/** One tick per group, placed under the middle bar of the group. */
function groupTicks(data: BarRow[], groupKey: string) {
  const labels: string[] = Array.from({ length: data.length }, () => "")
  let start = 0
  for (let i = 1; i <= data.length; i++) {
    if (i === data.length || data[i]![groupKey] !== data[start]![groupKey]) {
      labels[Math.floor((start + i - 1) / 2)] = String(data[start]![groupKey] ?? "")
      start = i
    }
  }
  return labels
}

interface ShapeProps {
  x?: number
  y?: number
  width?: number
  height?: number
  index?: number
}

/** A single-series bar chart with gradient or striped fills, highlighted bars, and a hover marker. */
function BarChart({
  data,
  xKey,
  yKey,
  groupKey,
  variant = "gradient",
  color = "var(--chart-1)",
  mutedColor = "var(--muted-foreground)",
  highlight,
  grid = "dashed",
  showYAxis = false,
  showTooltip = true,
  showActiveMarker = true,
  barRadius = 6,
  referenceLines = [],
  xFormatter = defaultXFormatter,
  yFormatter,
  tooltipLabel,
  onBarClick,
  className,
  ...props
}: BarChartProps) {
  const id = React.useId()
  const isHighlighted = React.useCallback(
    (index: number) => (highlight ? highlight(data[index]!, index) : true),
    [data, highlight]
  )
  const tickLabels = React.useMemo(
    () => (groupKey ? groupTicks(data, groupKey) : null),
    [data, groupKey]
  )
  const fillFor = (index: number) =>
    `url(#${id}-${isHighlighted(index) ? "on" : "off"})`

  const activeBar = (shape: ShapeProps) => {
    const { x = 0, y = 0, width = 0, height = 0, index = 0 } = shape
    const on = isHighlighted(index)
    return (
      <g>
        <Rectangle {...shape} fill={fillFor(index)} />
        {showActiveMarker && height > 0 ? (
          <circle
            cx={x + width / 2}
            cy={y}
            r={4}
            fill="var(--background)"
            stroke={on ? color : mutedColor}
            strokeWidth={2}
          />
        ) : null}
      </g>
    )
  }

  return (
    <ChartContainer
      data-slot="bar-chart"
      config={{ [yKey]: { label: yKey, color } }}
      className={cn("aspect-auto h-64 w-full", className)}
      {...props}
    >
      <RechartsBarChart
        data={data}
        margin={{ top: 12, right: 8, bottom: 0, left: showYAxis ? 0 : 8 }}
        barCategoryGap="28%"
      >
        <defs>
          {variant === "gradient" ? (
            <>
              <linearGradient id={`${id}-on`} x1="0" y1="0" x2="0" y2="1">
                <stop offset="0%" stopColor={color} stopOpacity={1} />
                <stop offset="100%" stopColor={color} stopOpacity={0.6} />
              </linearGradient>
              <linearGradient id={`${id}-off`} x1="0" y1="0" x2="0" y2="1">
                <stop offset="0%" stopColor={mutedColor} stopOpacity={0.35} />
                <stop offset="100%" stopColor={mutedColor} stopOpacity={0.18} />
              </linearGradient>
            </>
          ) : variant === "striped" ? (
            <>
              {(["on", "off"] as const).map((state) => {
                const fill = state === "on" ? color : mutedColor
                const opacity = state === "on" ? 1 : 0.3
                return (
                  <pattern
                    key={state}
                    id={`${id}-${state}`}
                    patternUnits="userSpaceOnUse"
                    width={10}
                    height={10}
                    patternTransform="rotate(45)"
                  >
                    <rect width={10} height={10} fill={fill} fillOpacity={opacity} />
                    <rect
                      width={5}
                      height={10}
                      fill="var(--background)"
                      fillOpacity={0.25}
                    />
                  </pattern>
                )
              })}
            </>
          ) : (
            <>
              <linearGradient id={`${id}-on`}>
                <stop stopColor={color} />
              </linearGradient>
              <linearGradient id={`${id}-off`}>
                <stop stopColor={mutedColor} stopOpacity={0.3} />
              </linearGradient>
            </>
          )}
        </defs>
        {grid !== "none" ? (
          <CartesianGrid
            vertical={false}
            strokeDasharray={grid === "dashed" ? "6 6" : undefined}
          />
        ) : null}
        <XAxis
          dataKey={xKey}
          tickLine={false}
          axisLine={false}
          tickMargin={10}
          interval={tickLabels ? 0 : "preserveStartEnd"}
          minTickGap={tickLabels ? 0 : 24}
          tickFormatter={
            tickLabels ? (_, index) => tickLabels[index] ?? "" : (v) => xFormatter(v)
          }
        />
        <YAxis
          hide={!showYAxis}
          tickLine={false}
          axisLine={false}
          tickMargin={8}
          width={44}
          tickFormatter={yFormatter}
        />
        {showTooltip ? (
          <ChartTooltip
            cursor={false}
            isAnimationActive={false}
            content={({ active, payload }) => {
              const entry = payload?.[0]
              if (!active || !entry) return null
              const row = entry.payload as BarRow
              const index = data.indexOf(row)
              const value = Number(row[yKey])
              return (
                <div className="bg-background rounded-lg border px-3 py-2 text-xs shadow-md">
                  <div className="text-sm font-semibold tabular-nums">
                    {yFormatter ? yFormatter(value) : String(value)}
                  </div>
                  <div className="text-muted-foreground">
                    {tooltipLabel ? tooltipLabel(row, index) : xFormatter(row[xKey])}
                  </div>
                </div>
              )
            }}
          />
        ) : null}
        <Bar
          dataKey={yKey}
          radius={barRadius}
          isAnimationActive={false}
          activeBar={activeBar}
          onClick={
            onBarClick
              ? (_, index) => onBarClick(data[index]!, index)
              : undefined
          }
          className={onBarClick ? "cursor-pointer" : undefined}
        >
          {data.map((_, index) => (
            <Cell key={index} fill={fillFor(index)} />
          ))}
        </Bar>
        {referenceLines.map((line, index) => (
          <ReferenceLine
            key={index}
            y={line.y}
            ifOverflow="extendDomain"
            stroke={line.color ?? "var(--muted-foreground)"}
            strokeDasharray={line.dashed === false ? undefined : "4 4"}
            label={
              line.label
                ? {
                    value: line.label,
                    position: "insideTopRight",
                    fill: line.color ?? "var(--muted-foreground)",
                    fontSize: 11,
                  }
                : undefined
            }
          />
        ))}
      </RechartsBarChart>
    </ChartContainer>
  )
}

export { BarChart }
```

### components/ui/delta-badge.tsx

```tsx
import * as React from "react"
import { Minus, TrendingDown, TrendingUp } from "lucide-react"

import { cn } from "@/lib/utils"
import { formatDelta } from "@/lib/format"

export type DeltaDirection = "up" | "down" | "flat"

export function getDeltaDirection(delta: number | undefined): DeltaDirection {
  if (delta === undefined || delta === 0 || !Number.isFinite(delta)) return "flat"
  return delta > 0 ? "up" : "down"
}

const directionIcon: Record<DeltaDirection, React.ElementType> = {
  up: TrendingUp,
  down: TrendingDown,
  flat: Minus,
}

export interface DeltaBadgeProps extends React.ComponentProps<"span"> {
  /** Fractional change, e.g. 0.124 for +12.4%. */
  delta: number
  /** Treat a decrease as good and an increase as bad (churn, latency, errors). */
  invert?: boolean
  variant?: "outline" | "soft" | "text"
  showIcon?: boolean
}

function DeltaBadge({
  delta,
  invert = false,
  variant = "outline",
  showIcon = true,
  className,
  children,
  ...props
}: DeltaBadgeProps) {
  const direction = getDeltaDirection(delta)
  const positive = direction === "flat" ? null : (direction === "up") !== invert
  const Icon = directionIcon[direction]

  return (
    <span
      data-slot="delta-badge"
      data-direction={direction}
      data-positive={positive}
      className={cn(
        "inline-flex items-center gap-1 text-xs font-medium tabular-nums",
        variant === "outline" && "rounded-md border px-1.5 py-0.5",
        variant === "soft" && "rounded-md px-1.5 py-0.5",
        variant === "soft" && positive === true && "bg-emerald-500/10",
        variant === "soft" && positive === false && "bg-red-500/10",
        variant === "soft" && positive === null && "bg-muted",
        positive === true && "text-emerald-600 dark:text-emerald-400",
        positive === false && "text-red-600 dark:text-red-400",
        positive === null && "text-muted-foreground",
        className
      )}
      {...props}
    >
      {showIcon ? <Icon className="size-3" aria-hidden="true" /> : null}
      {children ?? formatDelta(delta)}
    </span>
  )
}

export { DeltaBadge }
```

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### components/ui/period-tabs.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"

export interface PeriodOption {
  value: string
  label: string
}

export const defaultPeriods: PeriodOption[] = [
  { value: "week", label: "Week" },
  { value: "month", label: "Month" },
  { value: "year", label: "Year" },
]

export interface PeriodTabsProps
  extends Omit<React.ComponentProps<typeof Tabs>, "children"> {
  options?: PeriodOption[]
  size?: "sm" | "default"
  /** Slide a single pill between tabs instead of swapping backgrounds. */
  animated?: boolean
}

interface IndicatorRect {
  left: number
  top: number
  width: number
  height: number
}

/** Small segmented control for switching a chart's time range. */
function PeriodTabs({
  options = defaultPeriods,
  size = "sm",
  animated = false,
  className,
  value,
  defaultValue,
  onValueChange,
  ...props
}: PeriodTabsProps) {
  const listRef = React.useRef<HTMLDivElement>(null)
  const [internalValue, setInternalValue] = React.useState(
    defaultValue ?? options[0]?.value
  )
  const active = value ?? internalValue
  const [rect, setRect] = React.useState<IndicatorRect | null>(null)

  const measure = React.useCallback(() => {
    const list = listRef.current
    if (!list) return
    const trigger = list.querySelector<HTMLElement>('[data-state="active"]')
    if (!trigger) return
    setRect({
      left: trigger.offsetLeft,
      top: trigger.offsetTop,
      width: trigger.offsetWidth,
      height: trigger.offsetHeight,
    })
  }, [])

  React.useLayoutEffect(() => {
    if (!animated) return
    measure()
  }, [animated, active, options, size, measure])

  React.useEffect(() => {
    if (!animated || !listRef.current) return
    const observer = new ResizeObserver(measure)
    observer.observe(listRef.current)
    return () => observer.disconnect()
  }, [animated, measure])

  return (
    <Tabs
      data-slot="period-tabs"
      className={cn("w-fit", className)}
      value={value}
      defaultValue={defaultValue}
      onValueChange={(next) => {
        setInternalValue(next)
        onValueChange?.(next)
      }}
      {...props}
    >
      <TabsList
        ref={listRef}
        className={cn(
          "relative",
          size === "sm" && "group-data-[orientation=horizontal]/tabs:h-8 p-1"
        )}
      >
        {animated && rect ? (
          <span
            aria-hidden
            data-slot="period-tabs-indicator"
            className="pointer-events-none absolute rounded-md bg-background shadow-sm transition-[left,top,width,height] duration-300 ease-[cubic-bezier(0.25,1,0.5,1)] motion-reduce:transition-none dark:border dark:border-input dark:bg-input/30"
            style={rect}
          />
        ) : null}
        {options.map((option) => (
          <TabsTrigger
            key={option.value}
            value={option.value}
            className={cn(
              size === "sm" && "h-6 px-2.5 text-xs",
              animated &&
                "relative z-10 data-[state=active]:bg-transparent group-data-[variant=default]/tabs-list:data-[state=active]:shadow-none dark:data-[state=active]:border-transparent dark:data-[state=active]:bg-transparent"
            )}
          >
            {option.label}
          </TabsTrigger>
        ))}
      </TabsList>
    </Tabs>
  )
}

export { PeriodTabs }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Heatmap Chart Card

A card with a headline total, a delta, an optional period switcher, and a matrix heatmap whose hovered cell swaps into the headline.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/heatmap-chart-card.json
```

Also installs `card`, `tooltip`, `tabs` from shadcn/ui if missing.

npm dependencies: `lucide-react`.

## Usage

```tsx
import { HeatmapChartCard } from "@/components/heatmap-chart-card"

<HeatmapChartCard
  title="Active users"
  rows={[
    { label: "Mon", values: [12, 48, 210, 320, 260, 80] },
    { label: "Tue", values: [10, 52, 230, 340, 250, 70] },
  ]}
  columns={["00", "04", "08", "12", "16", "20"]}
  unit="sessions"
  delta={0.082}
  deltaLabel="vs previous 7 days"
  periods={[
    { value: "7d", label: "7D" },
    { value: "30d", label: "30D" },
  ]}
  onPeriodChange={setPeriod}
/>
```

## Examples

### Default

```tsx
"use client"

import * as React from "react"

import { HeatmapChartCard } from "@/registry/dashboardcn/blocks/heatmap-chart-card"

const days = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
const hours = Array.from({ length: 12 }, (_, i) => String(i * 2).padStart(2, "0"))

// Deterministic sample data with a working-hours peak on weekdays. Longer
// periods accumulate more sessions per bucket and smooth out the noise.
function sampleRows(seed: number, scale: number, noise: number) {
  const random = () => {
    seed = (seed * 1664525 + 1013904223) % 4294967296
    return seed / 4294967296
  }
  return days.map((label, d) => {
    const weekend = d >= 5
    return {
      label,
      values: hours.map((_, h) => {
        const hour = h * 2 + 1
        const shape = Math.exp(-((hour - (weekend ? 15 : 14)) ** 2) / (weekend ? 40 : 22))
        const base = (weekend ? 90 : 320) * shape + (weekend ? 6 : 12)
        return Math.round(base * scale * (1 - noise + random() * noise * 2))
      }),
    }
  })
}

const periods = {
  "7d": { rows: sampleRows(7, 1, 0.25), delta: 0.082, deltaLabel: "vs previous 7 days" },
  "30d": { rows: sampleRows(30, 4.2, 0.15), delta: 0.041, deltaLabel: "vs previous 30 days" },
  "90d": { rows: sampleRows(90, 12.5, 0.08), delta: -0.023, deltaLabel: "vs previous 90 days" },
}

type Period = keyof typeof periods

export default function HeatmapChartCardDemo() {
  const [period, setPeriod] = React.useState<Period>("7d")
  const current = periods[period]
  return (
    <HeatmapChartCard
      className="w-full max-w-xl"
      title="Active users"
      rows={current.rows}
      columns={hours}
      unit="sessions"
      delta={current.delta}
      deltaLabel={current.deltaLabel}
      periods={[
        { value: "7d", label: "7D" },
        { value: "30d", label: "30D" },
        { value: "90d", label: "90D" },
      ]}
      period={period}
      onPeriodChange={(next) => setPeriod(next as Period)}
    />
  )
}
```

## Source

### components/heatmap-chart-card.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { type NumberFormat } from "@/lib/format"
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@/components/ui/card"
import { DeltaBadge } from "@/components/ui/delta-badge"
import {
  HeatmapChart,
  type HeatmapCell,
  type HeatmapChartProps,
} from "@/components/ui/heatmap-chart"
import { MetricValue } from "@/components/ui/metric-value"
import { PeriodTabs, type PeriodOption } from "@/components/ui/period-tabs"

export interface HeatmapChartCardProps
  extends Omit<React.ComponentProps<typeof Card>, "children">,
    Pick<
      HeatmapChartProps,
      "rows" | "columns" | "color" | "max" | "scale" | "unit" | "valueFormatter"
    > {
  title: string
  /** Headline value. Defaults to the sum of every cell. Strings render as-is. */
  value?: number | string
  /** Fractional change, e.g. 0.052 for +5.2%. */
  delta?: number
  /** Context under the headline, e.g. "vs previous 7 days". */
  deltaLabel?: string
  /** Treat a decrease as good (churn, latency, errors). */
  invertDelta?: boolean
  format?: NumberFormat
  currency?: string
  /** Period options for the switcher. Omit to hide it. */
  periods?: PeriodOption[]
  period?: string
  defaultPeriod?: string
  onPeriodChange?: (period: string) => void
  chartClassName?: string
}

/**
 * A card with a headline total, a delta, an optional period switcher, and a matrix heatmap.
 * Hovering a cell swaps the headline to that cell's value and names the cell under it.
 */
function HeatmapChartCard({
  title,
  value,
  delta,
  deltaLabel,
  invertDelta,
  format,
  currency,
  unit,
  valueFormatter,
  rows,
  columns,
  color,
  max,
  scale,
  periods,
  period,
  defaultPeriod,
  onPeriodChange,
  chartClassName,
  className,
  ...props
}: HeatmapChartCardProps) {
  const [active, setActive] = React.useState<HeatmapCell | null>(null)

  const total = React.useMemo(
    () =>
      rows.reduce(
        (sum, row) => row.values.reduce((s, v) => s + (Number(v) || 0), sum),
        0
      ),
    [rows]
  )

  const hoveredRow = active ? rows[active.row] : undefined
  const hovered =
    active && hoveredRow
      ? {
          value: hoveredRow.values[active.column] ?? 0,
          label: `${hoveredRow.label} · ${columns[active.column] ?? ""}`,
        }
      : null

  return (
    <Card data-slot="heatmap-chart-card" className={cn("gap-4", className)} {...props}>
      <CardHeader>
        <CardDescription>{title}</CardDescription>
        <CardTitle className="flex items-baseline gap-2 text-3xl font-semibold tabular-nums tracking-tight">
          <MetricValue
            value={hovered ? hovered.value : (value ?? total)}
            format={format}
            currency={currency}
          />
          {delta !== undefined && !hovered ? (
            <DeltaBadge delta={delta} invert={invertDelta} />
          ) : null}
        </CardTitle>
        {/* Reserved even when empty so the caption does not shift the chart while hovering. */}
        <div
          data-slot="heatmap-chart-card-caption"
          className="text-muted-foreground min-h-5 text-sm"
        >
          {hovered ? hovered.label : deltaLabel}
        </div>
        {periods?.length ? (
          <CardAction>
            <PeriodTabs
              options={periods}
              value={period}
              defaultValue={defaultPeriod ?? periods[0]?.value}
              onValueChange={onPeriodChange}
            />
          </CardAction>
        ) : null}
      </CardHeader>
      <CardContent>
        <HeatmapChart
          rows={rows}
          columns={columns}
          color={color}
          max={max}
          scale={scale}
          unit={unit}
          valueFormatter={valueFormatter}
          activeCell={active}
          onActiveCellChange={setActive}
          className={chartClassName}
        />
      </CardContent>
    </Card>
  )
}

export { HeatmapChartCard }
```

### components/ui/heatmap-chart.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

export interface HeatmapRow {
  label: string
  /** One value per column, in column order. Missing entries read as 0. */
  values: number[]
}

/** A cell's position by row and column index. */
export interface HeatmapCell {
  row: number
  column: number
}

export interface HeatmapDatum extends HeatmapCell {
  rowLabel: string
  columnLabel: string
  value: number
}

export interface HeatmapChartProps extends React.ComponentProps<"div"> {
  /** One row per line of the matrix, top to bottom. */
  rows: HeatmapRow[]
  /** Column labels, left to right. Sets the number of columns. */
  columns: string[]
  /** Any CSS color. Cells mix this into `--muted` by value. Defaults to chart-1. */
  color?: string
  /** Value drawn fully saturated. Defaults to the largest value. */
  max?: number
  /** How values map to color. `sqrt` spreads out small values. */
  scale?: "linear" | "sqrt"
  /** Quantize the fill into this many steps instead of a continuous ramp. */
  levels?: number
  /** Gap between cells in px. Cells themselves stretch to fill the container. */
  gap?: number
  valueFormatter?: (value: number) => string
  /** Label for the value in the tooltip, e.g. "sessions". */
  unit?: string
  showLegend?: boolean
  showRowLabels?: boolean
  showColumnLabels?: boolean
  /** Show every nth column label. Defaults to whatever keeps about 12 labels. */
  columnLabelEvery?: number
  /** Replace the tooltip body. Return `null` to hide it for that cell. */
  renderTooltip?: (datum: HeatmapDatum) => React.ReactNode
  onCellClick?: (datum: HeatmapDatum) => void
  /** The hovered cell, to control it from outside. */
  activeCell?: HeatmapCell | null
  /** Called when the hovered cell changes, with null when the pointer leaves. */
  onActiveCellChange?: (cell: HeatmapCell | null) => void
}

/** Where a value sits between the muted track (0) and the accent (1). */
function fractionFor(
  value: number,
  max: number,
  scale: "linear" | "sqrt",
  levels?: number
) {
  if (value <= 0 || max <= 0) return 0
  let t = Math.min(1, value / max)
  if (scale === "sqrt") t = Math.sqrt(t)
  if (levels && levels > 1) {
    t = Math.max(1, Math.ceil(t * (levels - 1))) / (levels - 1)
  }
  return t
}

function fillFor(color: string, fraction: number) {
  if (fraction <= 0) return "var(--muted)"
  // Floor the mix so the smallest non-zero values still read against the track.
  const pct = Math.round(12 + fraction * 88)
  return `color-mix(in oklab, ${color} ${pct}%, var(--muted))`
}

/**
 * A matrix heatmap with a row per line and a column per label, e.g. weekday by hour.
 * Cells stretch to the container width. Hovering a cell rings it, lights up its row
 * and column labels, and shows its value.
 */
function HeatmapChart({
  rows,
  columns,
  color = "var(--chart-1)",
  max,
  scale = "linear",
  levels,
  gap = 4,
  valueFormatter = (value) => formatNumber(value),
  unit,
  showLegend = true,
  showRowLabels = true,
  showColumnLabels = true,
  columnLabelEvery,
  renderTooltip,
  onCellClick,
  activeCell,
  onActiveCellChange,
  className,
  ...props
}: HeatmapChartProps) {
  const [internal, setInternal] = React.useState<HeatmapCell | null>(null)
  const active = activeCell === undefined ? internal : activeCell
  const setActive = (cell: HeatmapCell | null) => {
    setInternal(cell)
    onActiveCellChange?.(cell)
  }

  const top = React.useMemo(
    () =>
      max ??
      rows.reduce(
        (acc, row) => row.values.reduce((m, v) => Math.max(m, v), acc),
        0
      ),
    [rows, max]
  )

  const every = columnLabelEvery ?? Math.max(1, Math.ceil(columns.length / 12))
  const steps = levels && levels > 1 ? levels : 5
  const swatches = Array.from({ length: steps }, (_, i) =>
    fillFor(color, i / (steps - 1))
  )

  const withUnit = (value: number) =>
    unit ? `${valueFormatter(value)} ${unit}` : valueFormatter(value)

  return (
    <div
      data-slot="heatmap-chart"
      className={cn("flex min-w-0 flex-col gap-2 text-xs", className)}
      {...props}
    >
      <TooltipProvider delayDuration={100} skipDelayDuration={0}>
        <div
          role="group"
          aria-label="Heatmap"
          className="grid min-w-0"
          style={{
            gap,
            gridTemplateColumns: `${showRowLabels ? "auto " : ""}repeat(${columns.length}, minmax(0, 1fr))`,
          }}
          onPointerLeave={() => setActive(null)}
        >
          {rows.map((row, r) => (
            <React.Fragment key={r}>
              {showRowLabels ? (
                <div
                  data-slot="heatmap-chart-row-label"
                  data-active={active?.row === r}
                  onPointerEnter={() => setActive(null)}
                  className="text-muted-foreground data-[active=true]:text-foreground flex items-center pr-1.5 leading-none whitespace-nowrap transition-colors"
                >
                  {row.label}
                </div>
              ) : null}
              {columns.map((column, c) => {
                const value = row.values[c] ?? 0
                const datum: HeatmapDatum = {
                  row: r,
                  column: c,
                  rowLabel: row.label,
                  columnLabel: column,
                  value,
                }
                const isActive = active?.row === r && active?.column === c
                const body = renderTooltip ? (
                  renderTooltip(datum)
                ) : (
                  <>
                    <span className="font-medium tabular-nums">{withUnit(value)}</span>
                    <span className="text-background/70 block">
                      {row.label} · {column}
                    </span>
                  </>
                )

                const cell = (
                  <button
                    type="button"
                    aria-label={`${withUnit(value)}, ${row.label} ${column}`}
                    data-slot="heatmap-chart-cell"
                    data-row={r}
                    data-column={c}
                    data-active={isActive}
                    onPointerEnter={() => setActive({ row: r, column: c })}
                    onFocus={() => setActive({ row: r, column: c })}
                    onBlur={(event) => {
                      // Keep the highlight while focus moves between cells so the readout does not flash.
                      const next = event.relatedTarget
                      if (next instanceof HTMLElement && next.dataset.slot === "heatmap-chart-cell") return
                      setActive(null)
                    }}
                    onClick={onCellClick ? () => onCellClick(datum) : undefined}
                    className={cn(
                      "inset-ring-foreground/6 aspect-square w-full rounded-sm outline-none inset-ring transition-[box-shadow] duration-100",
                      "data-[active=true]:inset-ring-foreground/45 data-[active=true]:inset-ring-2",
                      "focus-visible:inset-ring-ring focus-visible:inset-ring-2",
                      onCellClick ? "cursor-pointer" : "cursor-default"
                    )}
                    style={{
                      backgroundColor: fillFor(
                        color,
                        fractionFor(value, top, scale, levels)
                      ),
                    }}
                  />
                )

                if (body === null) {
                  return <React.Fragment key={c}>{cell}</React.Fragment>
                }

                return (
                  <Tooltip key={c}>
                    <TooltipTrigger asChild>{cell}</TooltipTrigger>
                    <TooltipContent sideOffset={4} className="text-left">
                      {body}
                    </TooltipContent>
                  </Tooltip>
                )
              })}
            </React.Fragment>
          ))}

          {showColumnLabels ? (
            <>
              {showRowLabels ? <div aria-hidden /> : null}
              {columns.map((column, c) => (
                <div
                  key={c}
                  data-slot="heatmap-chart-column-label"
                  data-active={active?.column === c}
                  onPointerEnter={() => setActive(null)}
                  className="text-muted-foreground data-[active=true]:text-foreground min-w-0 pt-0.5 text-center leading-none whitespace-nowrap transition-colors"
                >
                  {c % every === 0 ? column : ""}
                </div>
              ))}
            </>
          ) : null}
        </div>
      </TooltipProvider>

      {showLegend ? (
        <div className="text-muted-foreground flex items-center justify-end gap-1">
          <span className="mr-0.5">Less</span>
          {swatches.map((fill, index) => (
            <span
              key={index}
              className="inset-ring-foreground/6 size-3 rounded-[3px] inset-ring"
              style={{ backgroundColor: fill }}
            />
          ))}
          <span className="ml-0.5">More</span>
        </div>
      ) : null}
    </div>
  )
}

export { HeatmapChart }
```

### components/ui/delta-badge.tsx

```tsx
import * as React from "react"
import { Minus, TrendingDown, TrendingUp } from "lucide-react"

import { cn } from "@/lib/utils"
import { formatDelta } from "@/lib/format"

export type DeltaDirection = "up" | "down" | "flat"

export function getDeltaDirection(delta: number | undefined): DeltaDirection {
  if (delta === undefined || delta === 0 || !Number.isFinite(delta)) return "flat"
  return delta > 0 ? "up" : "down"
}

const directionIcon: Record<DeltaDirection, React.ElementType> = {
  up: TrendingUp,
  down: TrendingDown,
  flat: Minus,
}

export interface DeltaBadgeProps extends React.ComponentProps<"span"> {
  /** Fractional change, e.g. 0.124 for +12.4%. */
  delta: number
  /** Treat a decrease as good and an increase as bad (churn, latency, errors). */
  invert?: boolean
  variant?: "outline" | "soft" | "text"
  showIcon?: boolean
}

function DeltaBadge({
  delta,
  invert = false,
  variant = "outline",
  showIcon = true,
  className,
  children,
  ...props
}: DeltaBadgeProps) {
  const direction = getDeltaDirection(delta)
  const positive = direction === "flat" ? null : (direction === "up") !== invert
  const Icon = directionIcon[direction]

  return (
    <span
      data-slot="delta-badge"
      data-direction={direction}
      data-positive={positive}
      className={cn(
        "inline-flex items-center gap-1 text-xs font-medium tabular-nums",
        variant === "outline" && "rounded-md border px-1.5 py-0.5",
        variant === "soft" && "rounded-md px-1.5 py-0.5",
        variant === "soft" && positive === true && "bg-emerald-500/10",
        variant === "soft" && positive === false && "bg-red-500/10",
        variant === "soft" && positive === null && "bg-muted",
        positive === true && "text-emerald-600 dark:text-emerald-400",
        positive === false && "text-red-600 dark:text-red-400",
        positive === null && "text-muted-foreground",
        className
      )}
      {...props}
    >
      {showIcon ? <Icon className="size-3" aria-hidden="true" /> : null}
      {children ?? formatDelta(delta)}
    </span>
  )
}

export { DeltaBadge }
```

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### components/ui/period-tabs.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"

export interface PeriodOption {
  value: string
  label: string
}

export const defaultPeriods: PeriodOption[] = [
  { value: "week", label: "Week" },
  { value: "month", label: "Month" },
  { value: "year", label: "Year" },
]

export interface PeriodTabsProps
  extends Omit<React.ComponentProps<typeof Tabs>, "children"> {
  options?: PeriodOption[]
  size?: "sm" | "default"
  /** Slide a single pill between tabs instead of swapping backgrounds. */
  animated?: boolean
}

interface IndicatorRect {
  left: number
  top: number
  width: number
  height: number
}

/** Small segmented control for switching a chart's time range. */
function PeriodTabs({
  options = defaultPeriods,
  size = "sm",
  animated = false,
  className,
  value,
  defaultValue,
  onValueChange,
  ...props
}: PeriodTabsProps) {
  const listRef = React.useRef<HTMLDivElement>(null)
  const [internalValue, setInternalValue] = React.useState(
    defaultValue ?? options[0]?.value
  )
  const active = value ?? internalValue
  const [rect, setRect] = React.useState<IndicatorRect | null>(null)

  const measure = React.useCallback(() => {
    const list = listRef.current
    if (!list) return
    const trigger = list.querySelector<HTMLElement>('[data-state="active"]')
    if (!trigger) return
    setRect({
      left: trigger.offsetLeft,
      top: trigger.offsetTop,
      width: trigger.offsetWidth,
      height: trigger.offsetHeight,
    })
  }, [])

  React.useLayoutEffect(() => {
    if (!animated) return
    measure()
  }, [animated, active, options, size, measure])

  React.useEffect(() => {
    if (!animated || !listRef.current) return
    const observer = new ResizeObserver(measure)
    observer.observe(listRef.current)
    return () => observer.disconnect()
  }, [animated, measure])

  return (
    <Tabs
      data-slot="period-tabs"
      className={cn("w-fit", className)}
      value={value}
      defaultValue={defaultValue}
      onValueChange={(next) => {
        setInternalValue(next)
        onValueChange?.(next)
      }}
      {...props}
    >
      <TabsList
        ref={listRef}
        className={cn(
          "relative",
          size === "sm" && "group-data-[orientation=horizontal]/tabs:h-8 p-1"
        )}
      >
        {animated && rect ? (
          <span
            aria-hidden
            data-slot="period-tabs-indicator"
            className="pointer-events-none absolute rounded-md bg-background shadow-sm transition-[left,top,width,height] duration-300 ease-[cubic-bezier(0.25,1,0.5,1)] motion-reduce:transition-none dark:border dark:border-input dark:bg-input/30"
            style={rect}
          />
        ) : null}
        {options.map((option) => (
          <TabsTrigger
            key={option.value}
            value={option.value}
            className={cn(
              size === "sm" && "h-6 px-2.5 text-xs",
              animated &&
                "relative z-10 data-[state=active]:bg-transparent group-data-[variant=default]/tabs-list:data-[state=active]:shadow-none dark:data-[state=active]:border-transparent dark:data-[state=active]:bg-transparent"
            )}
          >
            {option.label}
          </TabsTrigger>
        ))}
      </TabsList>
    </Tabs>
  )
}

export { PeriodTabs }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Insight Card

A hero card with a badge, a very large number, a headline, and a paged set of insights over a soft gradient.

A hero card with a badge, a very large number, a headline, and a paged set of insights over a soft gradient. Use it to surface generated or curated findings at the top of a dashboard.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/insight-card.json
```

Also installs `card`, `tooltip` from shadcn/ui if missing.

npm dependencies: `lucide-react`.

## Usage

```tsx
import { InsightCard } from "@/components/insight-card"

<InsightCard
  badge="Insights"
  variant="aurora"
  interval={6000}
  items={[
    {
      value: 0.75,
      format: "percent",
      headline: "Authorization rate increased by 4% compared to last week.",
      description: "This improvement reduced failed transactions by 950 and is projected to recover $12,400.",
    },
    {
      value: 38,
      headline: "38 high-value customers have not ordered in 60 days.",
    },
  ]}
/>
```

## Examples

### Default

```tsx
import { InsightCard } from "@/registry/dashboardcn/blocks/insight-card"

export default function InsightCardDemo() {
  return (
    <InsightCard
      className="w-full max-w-sm"
      badge="Insights"
      interval={6000}
      items={[
        {
          value: 0.75,
          format: "percent",
          headline: "Authorization rate increased by 4% compared to last week.",
          description:
            "This improvement reduced failed transactions by 950 and is projected to recover $12,400.",
        },
        {
          value: 2.1,
          format: "currency",
          headline: "Average order value is up $2.10 since the checkout redesign.",
          description:
            "Bundled add-ons account for most of the lift, led by extended warranties.",
        },
        {
          value: 38,
          headline: "38 high-value customers have not ordered in 60 days.",
          description:
            "Together they made up 11% of revenue last quarter. A win-back offer is recommended.",
        },
      ]}
    />
  )
}
```

### Variants

variant picks the gradient: aurora, sunset, ocean, or graphite. size="md" shrinks the number for narrower columns.

```tsx
import { Flame, Sparkles, Waves } from "lucide-react"

import { InsightCard } from "@/registry/dashboardcn/blocks/insight-card"

export default function InsightCardVariantsDemo() {
  return (
    <div className="grid w-full gap-4 md:grid-cols-3">
      <InsightCard
        variant="sunset"
        badge="Trending"
        icon={<Flame />}
        size="md"
        items={[
          {
            value: 12400,
            format: "compact",
            headline: "Signups from social doubled this week.",
            description: "Most came from a single launch thread on Thursday.",
          },
        ]}
      />
      <InsightCard
        variant="ocean"
        badge="Forecast"
        icon={<Waves />}
        size="md"
        items={[
          {
            value: 1.28,
            format: "currency",
            headline: "Cost per lead is projected to fall 9% next month.",
            description: "Driven by improving quality scores on the top three campaigns.",
          },
        ]}
      />
      <InsightCard
        variant="graphite"
        badge="Anomaly"
        icon={<Sparkles />}
        size="md"
        items={[
          {
            value: "3.2s",
            headline: "Checkout latency spiked at 02:14 UTC.",
            description: "Traced to a cold cache after the nightly deploy. Now recovered.",
          },
        ]}
      />
    </div>
  )
}
```

### Plain

variant="plain" drops the gradient and uses the card colors, so it sits next to other blocks.

```tsx
import { EllipsisVertical } from "lucide-react"

import { Button } from "@/components/ui/button"
import { InsightCard } from "@/registry/dashboardcn/blocks/insight-card"

export default function InsightCardPlainDemo() {
  return (
    <InsightCard
      className="w-full max-w-sm"
      variant="plain"
      badge="Insights"
      action={
        <Button variant="ghost" size="icon-xs" className="text-muted-foreground -mr-1.5">
          <EllipsisVertical />
          <span className="sr-only">More</span>
        </Button>
      }
      items={[
        {
          value: 0.75,
          format: "percent",
          headline: "Authorization rate increased by 4% compared to last week.",
          description:
            "This improvement reduced failed transactions by 950 and is projected to recover $12,400.",
        },
        {
          value: 38,
          headline: "38 high-value customers have not ordered in 60 days.",
          description:
            "Together they made up 11% of revenue last quarter. A win-back offer is recommended.",
        },
      ]}
    />
  )
}
```

## Source

### components/insight-card.tsx

```tsx
"use client"

import * as React from "react"
import { Lightbulb } from "lucide-react"

import { cn } from "@/lib/utils"
import { type NumberFormat } from "@/lib/format"
import { Card } from "@/components/ui/card"
import { MetricValue } from "@/components/ui/metric-value"

export type InsightCardVariant =
  | "aurora"
  | "sunset"
  | "ocean"
  | "graphite"
  | "plain"

export interface InsightItem {
  /** The big number. Formatted when numeric. */
  value: number | string
  format?: NumberFormat
  currency?: string
  /** One-sentence takeaway under the number. */
  headline: string
  /** Supporting detail under the headline. */
  description?: React.ReactNode
}

export interface InsightCardProps
  extends Omit<React.ComponentProps<typeof Card>, "title"> {
  /** Pill label in the top-left, e.g. "Insights". */
  badge?: string
  /** Icon inside the badge. Defaults to a lightbulb. */
  icon?: React.ReactNode
  /** Slot in the top-right corner, e.g. a menu button. */
  action?: React.ReactNode
  /** Background style. "plain" uses the card colors. */
  variant?: InsightCardVariant
  /** One or more insights. More than one shows a pager at the bottom. */
  items: InsightItem[]
  /** Controlled index of the visible insight. */
  index?: number
  defaultIndex?: number
  onIndexChange?: (index: number) => void
  /** Milliseconds between automatic advances. Omit to disable. */
  interval?: number
  /** Size of the big number. */
  size?: "md" | "lg"
  /** Draws the folded light band and thin stroke over the gradient. */
  decoration?: boolean
}

const variants: Record<
  Exclude<InsightCardVariant, "plain">,
  { background: string; scrim: string }
> = {
  aurora: {
    background: [
      "radial-gradient(90% 55% at 88% 6%, #f7cfa9 0%, transparent 60%)",
      "radial-gradient(70% 55% at 104% 48%, #f4dc95 0%, transparent 60%)",
      "radial-gradient(75% 60% at 52% 34%, #fff5e8 0%, transparent 60%)",
      "radial-gradient(110% 75% at 2% 106%, #2b5ad4 0%, transparent 62%)",
      "linear-gradient(165deg, #d4dcee 0%, #a9bfe9 38%, #5f88df 72%, #3a67d4 100%)",
    ].join(", "),
    scrim: "linear-gradient(to top, rgba(18, 36, 96, 0.45), rgba(18, 36, 96, 0.08) 45%, transparent 70%)",
  },
  sunset: {
    background: [
      "radial-gradient(85% 55% at 90% 8%, #ffe1b8 0%, transparent 60%)",
      "radial-gradient(70% 55% at 100% 50%, #ffb38a 0%, transparent 60%)",
      "radial-gradient(75% 60% at 50% 36%, #fff0e6 0%, transparent 58%)",
      "radial-gradient(110% 75% at 0% 108%, #5a2fb0 0%, transparent 62%)",
      "linear-gradient(165deg, #f8d3c4 0%, #f29a9f 40%, #b9569e 72%, #6c3aa9 100%)",
    ].join(", "),
    scrim: "linear-gradient(to top, rgba(60, 16, 80, 0.45), rgba(60, 16, 80, 0.08) 45%, transparent 70%)",
  },
  ocean: {
    background: [
      "radial-gradient(85% 55% at 90% 8%, #d7f8ef 0%, transparent 60%)",
      "radial-gradient(70% 55% at 102% 50%, #a6ecd6 0%, transparent 60%)",
      "radial-gradient(75% 60% at 50% 36%, #f2fffb 0%, transparent 58%)",
      "radial-gradient(110% 75% at 0% 108%, #0f4c8a 0%, transparent 62%)",
      "linear-gradient(165deg, #cfeee6 0%, #6fd3c0 40%, #2a9cae 72%, #1a5f9c 100%)",
    ].join(", "),
    scrim: "linear-gradient(to top, rgba(8, 40, 72, 0.45), rgba(8, 40, 72, 0.08) 45%, transparent 70%)",
  },
  graphite: {
    background: [
      "radial-gradient(85% 55% at 90% 8%, rgba(255,255,255,0.22) 0%, transparent 60%)",
      "radial-gradient(75% 60% at 52% 34%, rgba(255,255,255,0.16) 0%, transparent 58%)",
      "radial-gradient(110% 75% at 0% 108%, #050506 0%, transparent 62%)",
      "linear-gradient(165deg, #5a5a60 0%, #3a3a40 40%, #232327 72%, #131316 100%)",
    ].join(", "),
    scrim: "linear-gradient(to top, rgba(0, 0, 0, 0.4), rgba(0, 0, 0, 0.08) 45%, transparent 70%)",
  },
}

/** A hero card with a badge, a very large number, a headline, and a paged set of insights over a soft gradient. */
function InsightCard({
  badge = "Insights",
  icon = <Lightbulb />,
  action,
  variant = "aurora",
  items,
  index,
  defaultIndex = 0,
  onIndexChange,
  interval,
  size = "lg",
  decoration = true,
  className,
  ...props
}: InsightCardProps) {
  const id = React.useId()
  const [internal, setInternal] = React.useState(defaultIndex)
  const active = Math.min(items.length - 1, Math.max(0, index ?? internal))
  const [paused, setPaused] = React.useState(false)

  const select = React.useCallback(
    (next: number) => {
      if (index === undefined) setInternal(next)
      onIndexChange?.(next)
    },
    [index, onIndexChange]
  )

  React.useEffect(() => {
    if (!interval || paused || items.length < 2) return
    const timer = window.setInterval(() => {
      select((active + 1) % items.length)
    }, interval)
    return () => window.clearInterval(timer)
  }, [interval, paused, items.length, active, select])

  const item = items[active]
  if (!item) return null
  const plain = variant === "plain"
  const palette = plain ? null : variants[variant]

  return (
    <Card
      data-slot="insight-card"
      data-variant={variant}
      className={cn(
        "@container/card relative isolate min-h-96 gap-0 overflow-hidden py-0",
        plain ? "" : "border-transparent text-white",
        className
      )}
      onMouseEnter={() => setPaused(true)}
      onMouseLeave={() => setPaused(false)}
      onFocusCapture={() => setPaused(true)}
      onBlurCapture={() => setPaused(false)}
      {...props}
    >
      {palette ? (
        <>
          <div
            aria-hidden
            className="absolute inset-0 -z-20"
            style={{ backgroundImage: palette.background }}
          />
          {decoration ? (
            <svg
              aria-hidden
              className="absolute inset-0 -z-10 size-full"
              viewBox="0 0 400 480"
              preserveAspectRatio="none"
              fill="none"
            >
              <defs>
                <filter id={`${id}-blur`} x="-50%" y="-50%" width="200%" height="200%">
                  <feGaussianBlur stdDeviation="26" />
                </filter>
              </defs>
              <path
                d="M 250 -40 L 250 200 L 440 400"
                stroke="rgba(255,255,255,0.75)"
                strokeWidth="64"
                strokeLinejoin="round"
                filter={`url(#${id}-blur)`}
              />
              <path
                d="M 250 -40 L 250 200 L 440 400"
                stroke="rgba(255,255,255,0.28)"
                strokeWidth="1"
                strokeLinejoin="round"
                vectorEffect="non-scaling-stroke"
              />
              <path
                d="M 310 -40 L 310 130 L 470 300"
                stroke="rgba(255,255,255,0.55)"
                strokeWidth="1"
                strokeLinejoin="round"
                vectorEffect="non-scaling-stroke"
              />
            </svg>
          ) : null}
          <div
            aria-hidden
            className="absolute inset-0 -z-10"
            style={{ backgroundImage: palette.scrim }}
          />
        </>
      ) : null}

      <div className="flex flex-1 flex-col gap-6 p-6">
        <div className="flex items-start justify-between gap-3">
          {badge ? (
            <span
              className={cn(
                "inline-flex h-8 items-center gap-1.5 rounded-full px-3 text-sm font-medium [&>svg]:size-4",
                plain
                  ? "bg-muted text-foreground"
                  : "bg-white/75 text-neutral-900 shadow-sm backdrop-blur-sm"
              )}
            >
              {icon}
              {badge}
            </span>
          ) : (
            <span />
          )}
          {action ? <div className="shrink-0">{action}</div> : null}
        </div>

        <div
          key={active}
          className="mt-auto flex flex-col gap-4 animate-in fade-in slide-in-from-bottom-2 duration-500"
        >
          <MetricValue
            value={item.value}
            format={item.format}
            currency={item.currency}
            maximumFractionDigits={item.format === "percent" ? 0 : undefined}
            className={cn(
              "font-semibold leading-none tracking-tighter",
              size === "lg" ? "text-7xl @sm/card:text-8xl" : "text-5xl @sm/card:text-6xl"
            )}
          />
          <p className="text-xl leading-snug font-semibold text-balance @sm/card:text-2xl">
            {item.headline}
          </p>
          {item.description ? (
            <p className={cn("text-sm leading-relaxed", plain ? "text-muted-foreground" : "text-white/85")}>
              {item.description}
            </p>
          ) : null}
        </div>

        {items.length > 1 ? (
          <div className="flex gap-1.5" role="tablist" aria-label={badge || "Insights"}>
            {items.map((_, i) => (
              <button
                key={i}
                type="button"
                role="tab"
                aria-selected={i === active}
                aria-label={`Insight ${i + 1} of ${items.length}`}
                onClick={() => select(i)}
                className="group/dot flex h-4 flex-1 cursor-pointer items-center"
              >
                <span
                  className={cn(
                    "h-1 w-full rounded-full transition-colors",
                    plain
                      ? i === active
                        ? "bg-foreground"
                        : "bg-muted-foreground/30 group-hover/dot:bg-muted-foreground/60"
                      : i === active
                        ? "bg-white"
                        : "bg-white/40 group-hover/dot:bg-white/70"
                  )}
                />
              </button>
            ))}
          </div>
        ) : null}
      </div>
    </Card>
  )
}

export { InsightCard }
```

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# KPI Row Card

A card with a period switcher, a row of KPI tiles with sparklines and deltas, and a footer summary.

A single card holding a row of KPI tiles, each with a sparkline and delta, plus a period switcher in the header and a summary in the footer. It is the top-of-dashboard block for shadcn/ui, composed from the KPI card, sparkline, and period tabs.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/kpi-row-card.json
```

Also installs `card`, `tabs`, `tooltip` from shadcn/ui if missing.

npm dependencies: `recharts`, `lucide-react`.

## Usage

```tsx
import { KpiRowCard } from "@/components/kpi-row-card"

<KpiRowCard
  title="Catalog health"
  description="SKU coverage, replenishment pressure, and aging stock."
  periods={[
    { value: "week", label: "Week" },
    { value: "month", label: "Month" },
  ]}
  metrics={[
    { label: "In stock", value: 8420, delta: 0.054, note: "Rising", trend: [6, 7, 7.5, 8.4] },
    { label: "Out of stock", value: 1245, delta: -0.12, invertDelta: true, trend: [1.6, 1.5, 1.3, 1.25] },
  ]}
  footer="12,845 products tracked across categories."
  action={{ label: "Show full analytics", href: "/analytics" }}
/>
```

## Examples

### Default

```tsx
import { AlertTriangle, Boxes, PackageX, Timer } from "lucide-react"

import { KpiRowCard } from "@/registry/dashboardcn/blocks/kpi-row-card"

export default function KpiRowCardDemo() {
  return (
    <KpiRowCard
      className="w-full"
      title="Catalog health"
      description="SKU coverage, replenishment pressure, and aging stock in one pass."
      periods={[
        { value: "week", label: "Week" },
        { value: "month", label: "Month" },
        { value: "year", label: "Year" },
      ]}
      metrics={[
        { icon: <Boxes />, label: "In stock", value: 8_420, delta: 0.054, note: "Rising", trend: [6, 7, 6.5, 7.5, 8, 7.8, 8.4] },
        { icon: <PackageX />, label: "Out of stock", value: 1_245, delta: -0.12, note: "Gaps easing", invertDelta: true, trend: [1.6, 1.5, 1.55, 1.4, 1.3, 1.28, 1.25] },
        { icon: <AlertTriangle />, label: "Pending restock", value: 640, delta: 0.031, note: "Moving", trend: [5.5, 6, 5.8, 6.2, 6.1, 6.3, 6.4] },
        { icon: <Timer />, label: "Slow movers", value: 1_105, delta: 0.006, note: "Stable", invertDelta: true, trend: [1.1, 1.12, 1.09, 1.1, 1.11, 1.1, 1.1] },
      ]}
      footer="12,845 products tracked across categories. 76% currently available in stock."
      action={{ label: "Show full analytics", href: "#" }}
    />
  )
}
```

## Source

### components/kpi-row-card.tsx

```tsx
"use client"

import * as React from "react"
import { ArrowRight } from "lucide-react"

import { cn } from "@/lib/utils"
import { type NumberFormat } from "@/lib/format"
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card"
import { DeltaBadge, getDeltaDirection } from "@/components/ui/delta-badge"
import { PeriodTabs, type PeriodOption } from "@/components/ui/period-tabs"
import { Sparkline } from "@/components/ui/sparkline"
import { MetricValue } from "@/components/ui/metric-value"

export interface KpiRowMetric {
  label: string
  value: number | string
  delta?: number
  /** Short word next to the delta, e.g. "Rising". */
  note?: string
  trend?: number[]
  format?: NumberFormat
  currency?: string
  invertDelta?: boolean
  icon?: React.ReactNode
}

export interface KpiRowCardProps extends React.ComponentProps<typeof Card> {
  title: string
  description?: string
  metrics: KpiRowMetric[]
  /** Period options for the switcher. Omit to hide it. */
  periods?: PeriodOption[]
  period?: string
  defaultPeriod?: string
  onPeriodChange?: (period: string) => void
  /** Text in the footer, e.g. a summary sentence. */
  footer?: React.ReactNode
  /** Footer link. */
  action?: { label: string; href: string }
}

/** A card with a row of KPI tiles, each with a sparkline and delta. */
function KpiRowCard({
  title,
  description,
  metrics,
  periods,
  period,
  defaultPeriod,
  onPeriodChange,
  footer,
  action,
  className,
  ...props
}: KpiRowCardProps) {
  return (
    <Card data-slot="kpi-row-card" className={cn("gap-4", className)} {...props}>
      <CardHeader>
        <CardTitle>{title}</CardTitle>
        {description ? <CardDescription>{description}</CardDescription> : null}
        {periods ? (
          <CardAction>
            <PeriodTabs
              options={periods}
              value={period}
              defaultValue={defaultPeriod ?? periods[0]?.value}
              onValueChange={onPeriodChange}
            />
          </CardAction>
        ) : null}
      </CardHeader>
      <CardContent>
        <div className="@container">
          <div className="grid gap-6 @lg:grid-cols-2 @3xl:grid-cols-4 @3xl:divide-x">
            {metrics.map((metric) => {
              const direction = getDeltaDirection(metric.delta)
              const positive =
                direction === "flat"
                  ? null
                  : (direction === "up") !== Boolean(metric.invertDelta)
              const color =
                positive === true
                  ? "var(--color-emerald-500)"
                  : positive === false
                    ? "var(--color-red-500)"
                    : "var(--muted-foreground)"
              return (
                <div
                  key={metric.label}
                  data-slot="kpi-row-metric"
                  className="flex flex-col gap-2 @3xl:px-6 @3xl:first:pl-0 @3xl:last:pr-0"
                >
                  <div className="text-muted-foreground flex items-center gap-1.5 text-sm [&>svg]:size-4">
                    {metric.icon}
                    {metric.label}
                  </div>
                  <div className="flex items-end justify-between gap-3">
                    <div className="flex flex-col gap-1">
                      <MetricValue
                        value={metric.value}
                        format={metric.format}
                        currency={metric.currency}
                        className="text-2xl font-semibold tracking-tight"
                      />
                      <span className="flex items-center gap-1.5 text-xs">
                        {metric.delta !== undefined ? (
                          <DeltaBadge
                            delta={metric.delta}
                            invert={metric.invertDelta}
                            variant="soft"
                            showIcon={false}
                          />
                        ) : null}
                        {metric.note ? (
                          <span className="text-muted-foreground">{metric.note}</span>
                        ) : null}
                      </span>
                    </div>
                    {metric.trend && metric.trend.length > 1 ? (
                      <Sparkline
                        data={metric.trend}
                        variant="line"
                        color={color}
                        className="h-9 w-20 shrink-0"
                      />
                    ) : null}
                  </div>
                </div>
              )
            })}
          </div>
        </div>
      </CardContent>
      {footer || action ? (
        <CardFooter className="text-muted-foreground justify-between gap-4 border-t pt-4 text-xs [.border-t]:pt-4">
          <div>{footer}</div>
          {action ? (
            <a
              href={action.href}
              className="text-foreground inline-flex shrink-0 items-center gap-1 font-medium hover:underline"
            >
              {action.label}
              <ArrowRight className="size-3.5" />
            </a>
          ) : null}
        </CardFooter>
      ) : null}
    </Card>
  )
}

export { KpiRowCard }
```

### components/ui/delta-badge.tsx

```tsx
import * as React from "react"
import { Minus, TrendingDown, TrendingUp } from "lucide-react"

import { cn } from "@/lib/utils"
import { formatDelta } from "@/lib/format"

export type DeltaDirection = "up" | "down" | "flat"

export function getDeltaDirection(delta: number | undefined): DeltaDirection {
  if (delta === undefined || delta === 0 || !Number.isFinite(delta)) return "flat"
  return delta > 0 ? "up" : "down"
}

const directionIcon: Record<DeltaDirection, React.ElementType> = {
  up: TrendingUp,
  down: TrendingDown,
  flat: Minus,
}

export interface DeltaBadgeProps extends React.ComponentProps<"span"> {
  /** Fractional change, e.g. 0.124 for +12.4%. */
  delta: number
  /** Treat a decrease as good and an increase as bad (churn, latency, errors). */
  invert?: boolean
  variant?: "outline" | "soft" | "text"
  showIcon?: boolean
}

function DeltaBadge({
  delta,
  invert = false,
  variant = "outline",
  showIcon = true,
  className,
  children,
  ...props
}: DeltaBadgeProps) {
  const direction = getDeltaDirection(delta)
  const positive = direction === "flat" ? null : (direction === "up") !== invert
  const Icon = directionIcon[direction]

  return (
    <span
      data-slot="delta-badge"
      data-direction={direction}
      data-positive={positive}
      className={cn(
        "inline-flex items-center gap-1 text-xs font-medium tabular-nums",
        variant === "outline" && "rounded-md border px-1.5 py-0.5",
        variant === "soft" && "rounded-md px-1.5 py-0.5",
        variant === "soft" && positive === true && "bg-emerald-500/10",
        variant === "soft" && positive === false && "bg-red-500/10",
        variant === "soft" && positive === null && "bg-muted",
        positive === true && "text-emerald-600 dark:text-emerald-400",
        positive === false && "text-red-600 dark:text-red-400",
        positive === null && "text-muted-foreground",
        className
      )}
      {...props}
    >
      {showIcon ? <Icon className="size-3" aria-hidden="true" /> : null}
      {children ?? formatDelta(delta)}
    </span>
  )
}

export { DeltaBadge }
```

### components/ui/period-tabs.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"

export interface PeriodOption {
  value: string
  label: string
}

export const defaultPeriods: PeriodOption[] = [
  { value: "week", label: "Week" },
  { value: "month", label: "Month" },
  { value: "year", label: "Year" },
]

export interface PeriodTabsProps
  extends Omit<React.ComponentProps<typeof Tabs>, "children"> {
  options?: PeriodOption[]
  size?: "sm" | "default"
  /** Slide a single pill between tabs instead of swapping backgrounds. */
  animated?: boolean
}

interface IndicatorRect {
  left: number
  top: number
  width: number
  height: number
}

/** Small segmented control for switching a chart's time range. */
function PeriodTabs({
  options = defaultPeriods,
  size = "sm",
  animated = false,
  className,
  value,
  defaultValue,
  onValueChange,
  ...props
}: PeriodTabsProps) {
  const listRef = React.useRef<HTMLDivElement>(null)
  const [internalValue, setInternalValue] = React.useState(
    defaultValue ?? options[0]?.value
  )
  const active = value ?? internalValue
  const [rect, setRect] = React.useState<IndicatorRect | null>(null)

  const measure = React.useCallback(() => {
    const list = listRef.current
    if (!list) return
    const trigger = list.querySelector<HTMLElement>('[data-state="active"]')
    if (!trigger) return
    setRect({
      left: trigger.offsetLeft,
      top: trigger.offsetTop,
      width: trigger.offsetWidth,
      height: trigger.offsetHeight,
    })
  }, [])

  React.useLayoutEffect(() => {
    if (!animated) return
    measure()
  }, [animated, active, options, size, measure])

  React.useEffect(() => {
    if (!animated || !listRef.current) return
    const observer = new ResizeObserver(measure)
    observer.observe(listRef.current)
    return () => observer.disconnect()
  }, [animated, measure])

  return (
    <Tabs
      data-slot="period-tabs"
      className={cn("w-fit", className)}
      value={value}
      defaultValue={defaultValue}
      onValueChange={(next) => {
        setInternalValue(next)
        onValueChange?.(next)
      }}
      {...props}
    >
      <TabsList
        ref={listRef}
        className={cn(
          "relative",
          size === "sm" && "group-data-[orientation=horizontal]/tabs:h-8 p-1"
        )}
      >
        {animated && rect ? (
          <span
            aria-hidden
            data-slot="period-tabs-indicator"
            className="pointer-events-none absolute rounded-md bg-background shadow-sm transition-[left,top,width,height] duration-300 ease-[cubic-bezier(0.25,1,0.5,1)] motion-reduce:transition-none dark:border dark:border-input dark:bg-input/30"
            style={rect}
          />
        ) : null}
        {options.map((option) => (
          <TabsTrigger
            key={option.value}
            value={option.value}
            className={cn(
              size === "sm" && "h-6 px-2.5 text-xs",
              animated &&
                "relative z-10 data-[state=active]:bg-transparent group-data-[variant=default]/tabs-list:data-[state=active]:shadow-none dark:data-[state=active]:border-transparent dark:data-[state=active]:bg-transparent"
            )}
          >
            {option.label}
          </TabsTrigger>
        ))}
      </TabsList>
    </Tabs>
  )
}

export { PeriodTabs }
```

### components/ui/sparkline.tsx

```tsx
"use client"

import * as React from "react"
import {
  Area,
  AreaChart,
  AreaRevealShape,
  Line,
  LineChart,
  ResponsiveContainer,
  type AreaRevealShapeProps,
} from "recharts"

import { cn } from "@/lib/utils"

export interface SparklineProps extends React.ComponentProps<"div"> {
  /** Series to plot, oldest first. */
  data: number[]
  variant?: "area" | "line"
  /** Area fill: a plain gradient, or a dot grid that fades out toward the line. */
  fill?: "gradient" | "dots"
  /** Any CSS color. Defaults to the theme primary. */
  color?: string
  curve?: "monotone" | "linear" | "step"
  strokeWidth?: number
}

/** Area shape that masks the fill to a dot grid while keeping the stroke solid. */
function DotGridAreaShape({
  maskId,
  ...props
}: AreaRevealShapeProps & { maskId: string }) {
  return (
    <>
      <g mask={`url(#${maskId})`}>
        <AreaRevealShape {...props} stroke="none" />
      </g>
      <AreaRevealShape {...props} id={undefined} fill="none" />
    </>
  )
}

function Sparkline({
  data,
  variant = "area",
  fill = "gradient",
  color = "var(--primary)",
  curve = "monotone",
  strokeWidth = 1.5,
  className,
  ...props
}: SparklineProps) {
  const id = React.useId()
  const dots = variant === "area" && fill === "dots"
  const points = React.useMemo(() => data.map((y, i) => ({ i, y })), [data])
  const margin = { top: 2, right: 0, bottom: 0, left: 0 }

  return (
    <div
      data-slot="sparkline"
      aria-hidden="true"
      className={cn("h-10 w-full", className)}
      {...props}
    >
      <ResponsiveContainer width="100%" height="100%">
        {variant === "line" ? (
          <LineChart data={points} margin={margin}>
            <Line
              type={curve}
              dataKey="y"
              stroke={color}
              strokeWidth={strokeWidth}
              dot={false}
              isAnimationActive={false}
            />
          </LineChart>
        ) : (
          <AreaChart data={points} margin={margin}>
            <defs>
              <linearGradient id={id} x1="0" y1="0" x2="0" y2="1">
                <stop offset="0%" stopColor={color} stopOpacity={dots ? 0.08 : 0.3} />
                <stop offset="100%" stopColor={color} stopOpacity={dots ? 0.9 : 0} />
              </linearGradient>
              {dots ? (
                <>
                  <pattern
                    id={`${id}-dots`}
                    patternUnits="userSpaceOnUse"
                    width={4}
                    height={4}
                  >
                    <circle cx={2} cy={2} r={0.9} fill="#fff" />
                  </pattern>
                  <mask
                    id={`${id}-mask`}
                    maskUnits="userSpaceOnUse"
                    x={0}
                    y={0}
                    width="100%"
                    height="100%"
                  >
                    <rect width="100%" height="100%" fill={`url(#${id}-dots)`} />
                  </mask>
                </>
              ) : null}
            </defs>
            <Area
              type={curve}
              dataKey="y"
              stroke={color}
              strokeWidth={strokeWidth}
              fill={`url(#${id})`}
              fillOpacity={dots ? 1 : undefined}
              dot={false}
              isAnimationActive={false}
              shape={
                dots
                  ? (shapeProps: AreaRevealShapeProps) => (
                      <DotGridAreaShape {...shapeProps} maskId={`${id}-mask`} />
                    )
                  : undefined
              }
            />
          </AreaChart>
        )}
      </ResponsiveContainer>
    </div>
  )
}

export { Sparkline }
```

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Metric Tabs Chart Card

A row of metric tabs, each with a value and delta, above a line chart of the selected metric against the previous period. Click a tab to switch the chart.

A row of metric tabs, each with a value and delta, above a line chart of the selected metric against the previous period. Clicking a tab switches the chart, the pattern used by Stripe-style overview pages.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/metric-tabs-chart-card.json
```

Also installs `card`, `chart`, `tooltip` from shadcn/ui if missing.

npm dependencies: `recharts`, `lucide-react`.

## Usage

```tsx
import { MetricTabsChartCard } from "@/components/metric-tabs-chart-card"

<MetricTabsChartCard
  data={data}
  xKey="date"
  metrics={[
    { key: "revenue", compareKey: "revenuePrev", label: "Revenue", format: "currency", fractionDigits: 0 },
    { key: "spend", compareKey: "spendPrev", label: "Ad spend", format: "currency", fractionDigits: 0, invertDelta: true },
    { key: "roas", compareKey: "roasPrev", label: "ROAS", aggregate: "average", fractionDigits: 2 },
    { key: "customers", compareKey: "customersPrev", label: "New customers" },
  ]}
/>
```

## Examples

### Default

```tsx
"use client"

import { MetricTabsChartCard } from "@/registry/dashboardcn/blocks/metric-tabs-chart-card"

const noise = (n: number) => {
  const x = Math.sin(n * 12.9898) * 43758.5453
  return x - Math.floor(x) - 0.5
}

const series = (base: number, swing: number, seed: number, drift = 0) =>
  Array.from({ length: 31 }, (_, i) =>
    Math.round(base + drift * i + swing * (0.6 * noise(i + seed) + 0.4 * Math.sin(i / 3 + seed)))
  )

const spend = series(1_380, 260, 1, -4)
const spendPrev = series(1_500, 220, 7)
const revenue = series(5_450, 1_100, 2, -20)
const revenuePrev = series(3_700, 700, 8)
const customers = series(88, 22, 3, -0.4)
const customersPrev = series(60, 14, 9)

const data = Array.from({ length: 31 }, (_, i) => ({
  date: `2025-07-${String(i + 1).padStart(2, "0")}`,
  revenue: revenue[i]!,
  revenuePrev: revenuePrev[i]!,
  spend: spend[i]!,
  spendPrev: spendPrev[i]!,
  roas: revenue[i]! / spend[i]!,
  roasPrev: revenuePrev[i]! / spendPrev[i]!,
  customers: customers[i]!,
  customersPrev: customersPrev[i]!,
  cac: spend[i]! / customers[i]!,
  cacPrev: spendPrev[i]! / customersPrev[i]!,
}))

export default function MetricTabsChartCardDemo() {
  return (
    <MetricTabsChartCard
      className="w-full"
      data={data}
      xKey="date"
      metrics={[
        { key: "revenue", compareKey: "revenuePrev", label: "Revenue", format: "currency", fractionDigits: 0 },
        { key: "spend", compareKey: "spendPrev", label: "Ad spend", format: "currency", fractionDigits: 0, invertDelta: true },
        { key: "roas", compareKey: "roasPrev", label: "ROAS", aggregate: "average", fractionDigits: 2 },
        { key: "customers", compareKey: "customersPrev", label: "New customers" },
        { key: "cac", compareKey: "cacPrev", label: "Cost / new customer", aggregate: "average", format: "currency", invertDelta: true },
      ]}
    />
  )
}
```

## Source

### components/metric-tabs-chart-card.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import {
  computeDelta,
  formatNumber,
  type NumberFormat,
} from "@/lib/format"
import { Card, CardContent } from "@/components/ui/card"
import { ComposedChart, type ComposedChartProps } from "@/components/ui/composed-chart"
import { DeltaBadge } from "@/components/ui/delta-badge"
import { MetricValue } from "@/components/ui/metric-value"

export interface MetricTab {
  /** Key of this metric in each data row. */
  key: string
  label: string
  /** Key of the previous-period series in each row, drawn as a dashed line. */
  compareKey?: string
  /** Headline value. Defaults to the aggregate of the metric's series. */
  value?: number | string
  /** Fractional change. Defaults to the aggregate vs the compare series. */
  delta?: number
  /** How to roll the series up into the headline value. */
  aggregate?: "sum" | "average" | "last"
  format?: NumberFormat
  currency?: string
  fractionDigits?: number
  /** Treat a decrease as good and an increase as bad (spend, cost, churn). */
  invertDelta?: boolean
}

export interface MetricTabsChartCardProps extends React.ComponentProps<typeof Card> {
  metrics: MetricTab[]
  data: Record<string, unknown>[]
  xKey: string
  /** Controlled selected metric key. */
  selected?: string
  defaultSelected?: string
  onSelectedChange?: (key: string) => void
  /** Line color for the selected metric. */
  color?: string
  /** Line color for the previous-period series. */
  compareColor?: string
  /** Tooltip label for the previous-period series. */
  compareLabel?: string
  xFormatter?: ComposedChartProps["xFormatter"]
  chartClassName?: string
}

function aggregate(
  data: Record<string, unknown>[],
  key: string,
  mode: MetricTab["aggregate"] = "sum"
) {
  const values = data.map((row) => Number(row[key])).filter(Number.isFinite)
  if (!values.length) return 0
  if (mode === "last") return values[values.length - 1]!
  const total = values.reduce((sum, value) => sum + value, 0)
  return mode === "average" ? total / values.length : total
}

/** A card with a row of metric tabs, each with a value and delta, and a line chart of the selected metric against the previous period. */
function MetricTabsChartCard({
  metrics,
  data,
  xKey,
  selected: selectedProp,
  defaultSelected,
  onSelectedChange,
  color = "var(--chart-2)",
  compareColor = "var(--chart-1)",
  compareLabel = "Previous period",
  xFormatter,
  chartClassName,
  className,
  ...props
}: MetricTabsChartCardProps) {
  const id = React.useId()
  const [selectedState, setSelectedState] = React.useState(
    defaultSelected ?? metrics[0]?.key
  )
  const selectedKey = selectedProp ?? selectedState
  const active = metrics.find((metric) => metric.key === selectedKey) ?? metrics[0]

  const select = (key: string) => {
    setSelectedState(key)
    onSelectedChange?.(key)
  }

  const onKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
    if (event.key !== "ArrowLeft" && event.key !== "ArrowRight") return
    event.preventDefault()
    const index = metrics.findIndex((metric) => metric.key === active?.key)
    const step = event.key === "ArrowRight" ? 1 : -1
    const next = metrics[(index + step + metrics.length) % metrics.length]
    if (!next) return
    select(next.key)
    document.getElementById(`${id}-tab-${next.key}`)?.focus()
  }

  const yFormatter = React.useCallback(
    (value: number) =>
      formatNumber(value, {
        format: active?.format,
        currency: active?.currency,
        maximumFractionDigits: active?.fractionDigits,
      }),
    [active?.format, active?.currency, active?.fractionDigits]
  )

  if (!active) return null

  return (
    <Card
      data-slot="metric-tabs-chart-card"
      className={cn("gap-0 overflow-hidden py-0", className)}
      {...props}
    >
      <div
        role="tablist"
        aria-label="Metrics"
        onKeyDown={onKeyDown}
        className="flex divide-x overflow-x-auto border-b"
      >
        {metrics.map((metric) => {
          const isSelected = metric.key === active.key
          const value =
            metric.value ??
            aggregate(data, metric.key, metric.aggregate)
          const delta =
            metric.delta ??
            (metric.compareKey
              ? computeDelta(
                  aggregate(data, metric.key, metric.aggregate),
                  aggregate(data, metric.compareKey, metric.aggregate)
                )
              : undefined)
          return (
            <button
              key={metric.key}
              id={`${id}-tab-${metric.key}`}
              type="button"
              role="tab"
              aria-selected={isSelected}
              aria-controls={`${id}-panel`}
              tabIndex={isSelected ? 0 : -1}
              data-slot="metric-tab"
              data-state={isSelected ? "active" : "inactive"}
              onClick={() => select(metric.key)}
              className={cn(
                "flex flex-[1_0_auto] flex-col gap-1.5 border-t-2 px-4 py-3 text-left outline-none transition-colors",
                "focus-visible:ring-ring/50 focus-visible:ring-2 focus-visible:ring-inset",
                isSelected
                  ? "border-t-foreground bg-card"
                  : "hover:bg-muted/50 border-t-transparent"
              )}
            >
              <span className="text-muted-foreground text-sm whitespace-nowrap">{metric.label}</span>
              <span className="flex items-center justify-between gap-3">
                <MetricValue
                  value={value}
                  format={metric.format}
                  currency={metric.currency}
                  maximumFractionDigits={metric.fractionDigits}
                  className="text-lg font-semibold tracking-tight"
                />
                {delta !== undefined ? (
                  <DeltaBadge
                    delta={delta}
                    invert={metric.invertDelta}
                    variant="text"
                    showIcon={false}
                  />
                ) : null}
              </span>
            </button>
          )
        })}
      </div>
      <CardContent id={`${id}-panel`} role="tabpanel" className="pt-4 pb-4">
        <ComposedChart
          data={data}
          xKey={xKey}
          series={[
            ...(active.compareKey
              ? [
                  {
                    key: active.compareKey,
                    label: compareLabel,
                    type: "line" as const,
                    color: compareColor,
                    dashed: true,
                  },
                ]
              : []),
            { key: active.key, label: active.label, type: "line" as const, color },
          ]}
          showGrid={false}
          yDomain="auto"
          xFormatter={xFormatter}
          yFormatter={yFormatter}
          className={cn("h-40", chartClassName)}
        />
      </CardContent>
    </Card>
  )
}

export { MetricTabsChartCard }
```

### components/ui/composed-chart.tsx

```tsx
"use client"

import * as React from "react"
import {
  Area,
  Bar,
  CartesianGrid,
  ComposedChart as RechartsComposedChart,
  Line,
  ReferenceDot,
  ReferenceLine,
  XAxis,
  YAxis,
} from "recharts"

import { cn } from "@/lib/utils"
import {
  ChartContainer,
  ChartLegend,
  ChartLegendContent,
  ChartTooltip,
  ChartTooltipContent,
  type ChartConfig,
} from "@/components/ui/chart"

export interface ComposedSeries {
  /** Key in each data row. */
  key: string
  label: string
  type?: "area" | "line" | "bar"
  /** Any CSS color. Defaults to chart-1 through chart-5 in order. */
  color?: string
  /** Plot against the right axis. */
  axis?: "left" | "right"
  /** Series with the same stackId stack on top of each other. */
  stackId?: string
  /** Bars only: fill with a diagonal hatch instead of a solid color. */
  pattern?: "solid" | "hatched"
  /** Lines and areas only. */
  dashed?: boolean
  curve?: "monotone" | "linear" | "step"
  /** Lines only: draw a dot on every point. */
  dots?: boolean
  /** Mark the highest point of this series with a dot. */
  highlightMax?: boolean
}

export interface ReferenceLineSpec {
  /** Horizontal line at this y value. */
  y?: number
  /** Vertical line at this x value. */
  x?: string | number
  label?: string
  /** Any CSS color. Defaults to the muted foreground. */
  color?: string
  dashed?: boolean
  axis?: "left" | "right"
}

export interface ComposedChartProps
  extends Omit<React.ComponentProps<typeof ChartContainer>, "config" | "children"> {
  data: Record<string, unknown>[]
  /** Key of the x-axis value in each row. */
  xKey: string
  series: ComposedSeries[]
  referenceLines?: ReferenceLineSpec[]
  showGrid?: boolean
  showYAxis?: boolean
  showLegend?: boolean
  showTooltip?: boolean
  xFormatter?: (value: unknown) => string
  yFormatter?: (value: number) => string
  rightYFormatter?: (value: number) => string
  barRadius?: number
  /** "zero" starts the y-axis at 0; "auto" fits it to the data. */
  yDomain?: "zero" | "auto" | [number, number]
}

function defaultXFormatter(value: unknown) {
  if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}/.test(value)) {
    const [y, m, d] = value.split("-").map(Number)
    return new Date(y!, m! - 1, d).toLocaleDateString("en-US", {
      month: "short",
      day: "numeric",
    })
  }
  return String(value)
}

function ComposedChart({
  data,
  xKey,
  series,
  referenceLines = [],
  showGrid = true,
  showYAxis = false,
  showLegend = false,
  showTooltip = true,
  xFormatter = defaultXFormatter,
  yFormatter,
  rightYFormatter,
  barRadius = 4,
  yDomain = "zero",
  className,
  ...props
}: ComposedChartProps) {
  const id = React.useId()
  const config = Object.fromEntries(
    series.map((s, index) => [
      s.key,
      { label: s.label, color: s.color ?? `var(--chart-${(index % 5) + 1})` },
    ])
  ) satisfies ChartConfig
  const hasRightAxis = series.some((s) => s.axis === "right")
  const domain =
    yDomain === "auto" ? (["auto", "auto"] as const) : yDomain === "zero" ? undefined : yDomain

  const maxPoints = series
    .filter((s) => s.highlightMax)
    .map((s) => {
      let best: { x: unknown; y: number } | null = null
      for (const row of data) {
        const y = Number(row[s.key])
        if (Number.isFinite(y) && (!best || y > best.y)) best = { x: row[xKey], y }
      }
      return best ? { ...best, key: s.key, axis: s.axis ?? "left" } : null
    })
    .filter((p): p is NonNullable<typeof p> => p !== null)

  return (
    <ChartContainer
      data-slot="composed-chart"
      config={config}
      className={cn("aspect-auto h-64 w-full", className)}
      {...props}
    >
      <RechartsComposedChart
        data={data}
        margin={{ top: 8, right: hasRightAxis ? 0 : 8, bottom: 0, left: showYAxis ? 0 : 8 }}
      >
        <defs>
          {series.map((s) => (
            <React.Fragment key={s.key}>
              <linearGradient id={`${id}-fill-${s.key}`} x1="0" y1="0" x2="0" y2="1">
                <stop offset="5%" stopColor={`var(--color-${s.key})`} stopOpacity={0.5} />
                <stop offset="95%" stopColor={`var(--color-${s.key})`} stopOpacity={0.05} />
              </linearGradient>
              <pattern
                id={`${id}-hatch-${s.key}`}
                patternUnits="userSpaceOnUse"
                width={6}
                height={6}
                patternTransform="rotate(45)"
              >
                <rect width={6} height={6} fill={`var(--color-${s.key})`} fillOpacity={0.15} />
                <rect width={2} height={6} fill={`var(--color-${s.key})`} />
              </pattern>
            </React.Fragment>
          ))}
        </defs>
        {showGrid ? <CartesianGrid vertical={false} /> : null}
        <XAxis
          dataKey={xKey}
          tickLine={false}
          axisLine={false}
          tickMargin={8}
          minTickGap={32}
          tickFormatter={xFormatter}
        />
        <YAxis
          yAxisId="left"
          domain={domain}
          hide={!showYAxis}
          tickLine={false}
          axisLine={false}
          tickMargin={8}
          width={44}
          tickFormatter={yFormatter}
        />
        {hasRightAxis ? (
          <YAxis
            yAxisId="right"
            orientation="right"
            domain={domain}
            hide={!showYAxis}
            tickLine={false}
            axisLine={false}
            tickMargin={8}
            width={44}
            tickFormatter={rightYFormatter ?? yFormatter}
          />
        ) : null}
        {showTooltip ? (
          <ChartTooltip
            cursor={false}
            content={
              <ChartTooltipContent
                indicator="dot"
                labelFormatter={(value) => xFormatter(value)}
                formatter={(value, name, item) => {
                  const s = series.find((entry) => entry.key === name)
                  const fmt = s?.axis === "right" ? (rightYFormatter ?? yFormatter) : yFormatter
                  return (
                    <div className="flex w-full items-center gap-2">
                      <span
                        className="size-2 shrink-0 rounded-[2px]"
                        style={{ backgroundColor: item.color }}
                      />
                      <span className="text-muted-foreground flex-1">
                        {config[name as string]?.label ?? name}
                      </span>
                      <span className="font-mono font-medium tabular-nums">
                        {fmt ? fmt(Number(value)) : String(value)}
                      </span>
                    </div>
                  )
                }}
              />
            }
          />
        ) : null}
        {showLegend ? <ChartLegend content={<ChartLegendContent />} /> : null}
        {series.map((s) => {
          const color = `var(--color-${s.key})`
          const common = {
            dataKey: s.key,
            yAxisId: s.axis ?? "left",
            stackId: s.stackId,
            isAnimationActive: false,
          }
          if (s.type === "bar") {
            return (
              <Bar
                key={s.key}
                {...common}
                fill={s.pattern === "hatched" ? `url(#${id}-hatch-${s.key})` : color}
                stroke={s.pattern === "hatched" ? color : undefined}
                strokeWidth={s.pattern === "hatched" ? 1 : 0}
                radius={s.stackId ? 0 : barRadius}
              />
            )
          }
          if (s.type === "line") {
            return (
              <Line
                key={s.key}
                {...common}
                type={s.curve ?? "monotone"}
                stroke={color}
                strokeWidth={2}
                strokeDasharray={s.dashed ? "4 4" : undefined}
                dot={s.dots ? { r: 3, fill: color, strokeWidth: 0 } : false}
                activeDot={{ r: 4 }}
              />
            )
          }
          return (
            <Area
              key={s.key}
              {...common}
              type={s.curve ?? "monotone"}
              stroke={color}
              strokeWidth={2}
              strokeDasharray={s.dashed ? "4 4" : undefined}
              fill={`url(#${id}-fill-${s.key})`}
              dot={false}
            />
          )
        })}
        {referenceLines.map((line, index) => (
          <ReferenceLine
            key={index}
            y={line.y}
            x={line.x}
            yAxisId={line.axis ?? "left"}
            stroke={line.color ?? "var(--muted-foreground)"}
            strokeDasharray={line.dashed === false ? undefined : "4 4"}
            label={
              line.label
                ? {
                    value: line.label,
                    position: line.y !== undefined ? "insideTopRight" : "insideTopLeft",
                    fill: line.color ?? "var(--muted-foreground)",
                    fontSize: 11,
                  }
                : undefined
            }
          />
        ))}
        {maxPoints.map((point) => (
          <ReferenceDot
            key={point.key}
            x={point.x as string | number}
            y={point.y}
            yAxisId={point.axis}
            r={4}
            fill={`var(--color-${point.key})`}
            stroke="var(--background)"
            strokeWidth={2}
          />
        ))}
      </RechartsComposedChart>
    </ChartContainer>
  )
}

export { ComposedChart }
```

### components/ui/delta-badge.tsx

```tsx
import * as React from "react"
import { Minus, TrendingDown, TrendingUp } from "lucide-react"

import { cn } from "@/lib/utils"
import { formatDelta } from "@/lib/format"

export type DeltaDirection = "up" | "down" | "flat"

export function getDeltaDirection(delta: number | undefined): DeltaDirection {
  if (delta === undefined || delta === 0 || !Number.isFinite(delta)) return "flat"
  return delta > 0 ? "up" : "down"
}

const directionIcon: Record<DeltaDirection, React.ElementType> = {
  up: TrendingUp,
  down: TrendingDown,
  flat: Minus,
}

export interface DeltaBadgeProps extends React.ComponentProps<"span"> {
  /** Fractional change, e.g. 0.124 for +12.4%. */
  delta: number
  /** Treat a decrease as good and an increase as bad (churn, latency, errors). */
  invert?: boolean
  variant?: "outline" | "soft" | "text"
  showIcon?: boolean
}

function DeltaBadge({
  delta,
  invert = false,
  variant = "outline",
  showIcon = true,
  className,
  children,
  ...props
}: DeltaBadgeProps) {
  const direction = getDeltaDirection(delta)
  const positive = direction === "flat" ? null : (direction === "up") !== invert
  const Icon = directionIcon[direction]

  return (
    <span
      data-slot="delta-badge"
      data-direction={direction}
      data-positive={positive}
      className={cn(
        "inline-flex items-center gap-1 text-xs font-medium tabular-nums",
        variant === "outline" && "rounded-md border px-1.5 py-0.5",
        variant === "soft" && "rounded-md px-1.5 py-0.5",
        variant === "soft" && positive === true && "bg-emerald-500/10",
        variant === "soft" && positive === false && "bg-red-500/10",
        variant === "soft" && positive === null && "bg-muted",
        positive === true && "text-emerald-600 dark:text-emerald-400",
        positive === false && "text-red-600 dark:text-red-400",
        positive === null && "text-muted-foreground",
        className
      )}
      {...props}
    >
      {showIcon ? <Icon className="size-3" aria-hidden="true" /> : null}
      {children ?? formatDelta(delta)}
    </span>
  )
}

export { DeltaBadge }
```

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Period Bar Chart Card

A card with a total for the selected period, a range switcher, and a bar chart that highlights that period. Click a bar to select its period.

A card with a total for the selected period, a range switcher, and a bar chart that highlights that period. Clicking a bar selects it, which makes it a small interactive report.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/period-bar-chart-card.json
```

Also installs `card`, `chart`, `tabs` from shadcn/ui if missing.

npm dependencies: `recharts`, `lucide-react`.

## Usage

```tsx
import { PeriodBarChartCard } from "@/components/period-bar-chart-card"

<PeriodBarChartCard
  title="Spending"
  data={data}
  xKey="week"
  yKey="spend"
  groupKey="month"
  valueLabel="spending"
  color="var(--color-orange-500)"
  ranges={[
    { value: "1y", label: "1Y", points: 48 },
    { value: "6m", label: "6M", points: 24 },
    { value: "3m", label: "3M", points: 12 },
  ]}
  defaultRange="6m"
/>
```

## Examples

### Default

```tsx
"use client"

import { PeriodBarChartCard } from "@/registry/dashboardcn/blocks/period-bar-chart-card"

const months = ["Jul", "Aug", "Sep", "Oct", "Nov", "Dec", "Jan", "Feb", "Mar", "Apr", "May", "Jun"]

const data = months.flatMap((month, m) =>
  Array.from({ length: 4 }, (_, w) => ({
    week: `${month} week ${w + 1}`,
    month,
    spend:
      month === "Mar"
        ? 1_900 + w * 470
        : 800 + Math.round(Math.abs(Math.sin(m * 4 + w)) * 600),
  }))
)

export default function PeriodBarChartCardDemo() {
  return (
    <PeriodBarChartCard
      className="w-full"
      title="Spending"
      data={data}
      xKey="week"
      yKey="spend"
      groupKey="month"
      valueLabel="spending"
      color="var(--color-orange-500)"
      grid="none"
      defaultSelected="Mar"
      ranges={[
        { value: "1y", label: "1Y", points: 48 },
        { value: "6m", label: "6M", points: 24 },
        { value: "3m", label: "3M", points: 12 },
        { value: "1m", label: "1M", points: 4 },
      ]}
      defaultRange="6m"
      tooltipLabel={(row) => String(row.week).replace(/^\w+ /, "")}
    />
  )
}
```

## Source

### components/period-bar-chart-card.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import {
  computeDelta,
  formatNumber,
  type NumberFormat,
} from "@/lib/format"
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@/components/ui/card"
import { BarChart, type BarChartProps, type BarRow } from "@/components/ui/bar-chart"
import { DeltaBadge } from "@/components/ui/delta-badge"
import { PeriodTabs } from "@/components/ui/period-tabs"

export interface RangeOption {
  value: string
  label: string
  /** How many trailing rows of data this range shows. */
  points: number
}

export interface PeriodBarChartCardProps extends React.ComponentProps<typeof Card> {
  title: string
  data: BarRow[]
  xKey: string
  yKey: string
  /** Key that groups bars into selectable periods, e.g. "month" for weekly rows. Defaults to xKey. */
  groupKey?: string
  /** Range options for the switcher. Omit to show every row and hide the switcher. */
  ranges?: RangeOption[]
  defaultRange?: string
  /** Group value drawn in color. Defaults to the last group in view. */
  selected?: string
  defaultSelected?: string
  onSelectedChange?: (group: string) => void
  /** Words after the period in the subtitle, e.g. "spending" renders "March spending". */
  valueLabel?: string
  format?: NumberFormat
  currency?: string
  variant?: BarChartProps["variant"]
  color?: string
  mutedColor?: string
  grid?: BarChartProps["grid"]
  xFormatter?: BarChartProps["xFormatter"]
  tooltipLabel?: BarChartProps["tooltipLabel"]
  chartClassName?: string
}

function sum(rows: BarRow[], key: string) {
  return rows.reduce((total, row) => total + (Number(row[key]) || 0), 0)
}

/** A card with a total for the selected period, a range switcher, and a bar chart. Click a bar to select its period. */
function PeriodBarChartCard({
  title,
  data,
  xKey,
  yKey,
  groupKey = xKey,
  ranges,
  defaultRange,
  selected: selectedProp,
  defaultSelected,
  onSelectedChange,
  valueLabel,
  format = "currency",
  currency,
  variant,
  color,
  mutedColor,
  grid,
  xFormatter,
  tooltipLabel,
  chartClassName,
  className,
  ...props
}: PeriodBarChartCardProps) {
  const [range, setRange] = React.useState(defaultRange ?? ranges?.[0]?.value)
  const points = ranges?.find((option) => option.value === range)?.points
  const rows = React.useMemo(
    () => (points ? data.slice(Math.max(0, data.length - points)) : data),
    [data, points]
  )

  const groups = React.useMemo(() => {
    const order: string[] = []
    for (const row of rows) {
      const group = String(row[groupKey])
      if (order[order.length - 1] !== group) order.push(group)
    }
    return order
  }, [rows, groupKey])

  const [selectedState, setSelectedState] = React.useState(defaultSelected)
  const selected =
    selectedProp ?? (selectedState && groups.includes(selectedState) ? selectedState : groups.at(-1))
  const setSelected = (group: string) => {
    setSelectedState(group)
    onSelectedChange?.(group)
  }

  const selectedRows = rows.filter((row) => String(row[groupKey]) === selected)
  const previousGroup = groups[groups.indexOf(selected ?? "") - 1]
  const previousRows = previousGroup
    ? rows.filter((row) => String(row[groupKey]) === previousGroup)
    : []
  const total = sum(selectedRows, yKey)
  const delta = previousRows.length ? computeDelta(total, sum(previousRows, yKey)) : undefined

  const yFormatter = React.useCallback(
    (value: number) => formatNumber(value, { format, currency }),
    [format, currency]
  )

  return (
    <Card data-slot="period-bar-chart-card" className={cn("gap-4", className)} {...props}>
      <CardHeader>
        <CardDescription>{title}</CardDescription>
        <CardTitle className="text-3xl font-semibold tabular-nums tracking-tight">
          {yFormatter(total)}
        </CardTitle>
        <div className="flex items-center gap-1.5 text-sm">
          {delta !== undefined ? <DeltaBadge delta={delta} variant="text" /> : null}
          <span className="text-muted-foreground">
            {selected}
            {valueLabel ? ` ${valueLabel}` : null}
            {previousGroup ? ` vs ${previousGroup}` : null}
          </span>
        </div>
        {ranges?.length ? (
          <CardAction>
            <PeriodTabs options={ranges} value={range} onValueChange={setRange} />
          </CardAction>
        ) : null}
      </CardHeader>
      <CardContent>
        <BarChart
          data={rows}
          xKey={xKey}
          yKey={yKey}
          groupKey={groupKey === xKey ? undefined : groupKey}
          variant={variant}
          color={color}
          mutedColor={mutedColor}
          grid={grid}
          highlight={(row) => String(row[groupKey]) === selected}
          yFormatter={yFormatter}
          xFormatter={xFormatter}
          tooltipLabel={tooltipLabel}
          onBarClick={(row) => setSelected(String(row[groupKey]))}
          className={cn("h-56", chartClassName)}
        />
      </CardContent>
    </Card>
  )
}

export { PeriodBarChartCard }
```

### components/ui/bar-chart.tsx

```tsx
"use client"

import * as React from "react"
import {
  Bar,
  BarChart as RechartsBarChart,
  CartesianGrid,
  Cell,
  Rectangle,
  ReferenceLine,
  XAxis,
  YAxis,
} from "recharts"

import { cn } from "@/lib/utils"
import { ChartContainer, ChartTooltip } from "@/components/ui/chart"

export type BarRow = Record<string, unknown>

export interface BarReferenceLine {
  /** Horizontal line at this y value. */
  y: number
  label?: string
  /** Any CSS color. Defaults to the muted foreground. */
  color?: string
  /** Defaults to dashed. */
  dashed?: boolean
}

export interface BarChartProps
  extends Omit<React.ComponentProps<typeof ChartContainer>, "config" | "children"> {
  data: BarRow[]
  /** Key of the x-axis value in each row. */
  xKey: string
  /** Key of the bar value in each row. */
  yKey: string
  /**
   * Key of a coarser label, e.g. "month" for weekly rows. When set, the x-axis
   * shows one tick per group centered under its bars instead of a tick per bar.
   */
  groupKey?: string
  /** "gradient" fades each bar toward the bottom; "striped" fills it with diagonal bands. */
  variant?: "gradient" | "striped" | "solid"
  /** Any CSS color for highlighted bars. Defaults to chart-1. */
  color?: string
  /** Any CSS color for bars that are not highlighted. Defaults to the muted foreground. */
  mutedColor?: string
  /** Return true for bars drawn in color. Every bar is highlighted when omitted. */
  highlight?: (row: BarRow, index: number) => boolean
  grid?: "dashed" | "solid" | "none"
  showYAxis?: boolean
  showTooltip?: boolean
  /** Draw a hollow ring on top of the hovered bar. */
  showActiveMarker?: boolean
  barRadius?: number
  /** Horizontal lines, e.g. a goal or an average. The y-axis extends to fit them. */
  referenceLines?: BarReferenceLine[]
  xFormatter?: (value: unknown) => string
  yFormatter?: (value: number) => string
  /** Secondary line of the tooltip. Defaults to the formatted x value. */
  tooltipLabel?: (row: BarRow, index: number) => React.ReactNode
  onBarClick?: (row: BarRow, index: number) => void
}

function defaultXFormatter(value: unknown) {
  if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}/.test(value)) {
    const [y, m, d] = value.split("-").map(Number)
    return new Date(y!, m! - 1, d).toLocaleDateString("en-US", {
      month: "short",
      day: "numeric",
    })
  }
  return String(value)
}

/** One tick per group, placed under the middle bar of the group. */
function groupTicks(data: BarRow[], groupKey: string) {
  const labels: string[] = Array.from({ length: data.length }, () => "")
  let start = 0
  for (let i = 1; i <= data.length; i++) {
    if (i === data.length || data[i]![groupKey] !== data[start]![groupKey]) {
      labels[Math.floor((start + i - 1) / 2)] = String(data[start]![groupKey] ?? "")
      start = i
    }
  }
  return labels
}

interface ShapeProps {
  x?: number
  y?: number
  width?: number
  height?: number
  index?: number
}

/** A single-series bar chart with gradient or striped fills, highlighted bars, and a hover marker. */
function BarChart({
  data,
  xKey,
  yKey,
  groupKey,
  variant = "gradient",
  color = "var(--chart-1)",
  mutedColor = "var(--muted-foreground)",
  highlight,
  grid = "dashed",
  showYAxis = false,
  showTooltip = true,
  showActiveMarker = true,
  barRadius = 6,
  referenceLines = [],
  xFormatter = defaultXFormatter,
  yFormatter,
  tooltipLabel,
  onBarClick,
  className,
  ...props
}: BarChartProps) {
  const id = React.useId()
  const isHighlighted = React.useCallback(
    (index: number) => (highlight ? highlight(data[index]!, index) : true),
    [data, highlight]
  )
  const tickLabels = React.useMemo(
    () => (groupKey ? groupTicks(data, groupKey) : null),
    [data, groupKey]
  )
  const fillFor = (index: number) =>
    `url(#${id}-${isHighlighted(index) ? "on" : "off"})`

  const activeBar = (shape: ShapeProps) => {
    const { x = 0, y = 0, width = 0, height = 0, index = 0 } = shape
    const on = isHighlighted(index)
    return (
      <g>
        <Rectangle {...shape} fill={fillFor(index)} />
        {showActiveMarker && height > 0 ? (
          <circle
            cx={x + width / 2}
            cy={y}
            r={4}
            fill="var(--background)"
            stroke={on ? color : mutedColor}
            strokeWidth={2}
          />
        ) : null}
      </g>
    )
  }

  return (
    <ChartContainer
      data-slot="bar-chart"
      config={{ [yKey]: { label: yKey, color } }}
      className={cn("aspect-auto h-64 w-full", className)}
      {...props}
    >
      <RechartsBarChart
        data={data}
        margin={{ top: 12, right: 8, bottom: 0, left: showYAxis ? 0 : 8 }}
        barCategoryGap="28%"
      >
        <defs>
          {variant === "gradient" ? (
            <>
              <linearGradient id={`${id}-on`} x1="0" y1="0" x2="0" y2="1">
                <stop offset="0%" stopColor={color} stopOpacity={1} />
                <stop offset="100%" stopColor={color} stopOpacity={0.6} />
              </linearGradient>
              <linearGradient id={`${id}-off`} x1="0" y1="0" x2="0" y2="1">
                <stop offset="0%" stopColor={mutedColor} stopOpacity={0.35} />
                <stop offset="100%" stopColor={mutedColor} stopOpacity={0.18} />
              </linearGradient>
            </>
          ) : variant === "striped" ? (
            <>
              {(["on", "off"] as const).map((state) => {
                const fill = state === "on" ? color : mutedColor
                const opacity = state === "on" ? 1 : 0.3
                return (
                  <pattern
                    key={state}
                    id={`${id}-${state}`}
                    patternUnits="userSpaceOnUse"
                    width={10}
                    height={10}
                    patternTransform="rotate(45)"
                  >
                    <rect width={10} height={10} fill={fill} fillOpacity={opacity} />
                    <rect
                      width={5}
                      height={10}
                      fill="var(--background)"
                      fillOpacity={0.25}
                    />
                  </pattern>
                )
              })}
            </>
          ) : (
            <>
              <linearGradient id={`${id}-on`}>
                <stop stopColor={color} />
              </linearGradient>
              <linearGradient id={`${id}-off`}>
                <stop stopColor={mutedColor} stopOpacity={0.3} />
              </linearGradient>
            </>
          )}
        </defs>
        {grid !== "none" ? (
          <CartesianGrid
            vertical={false}
            strokeDasharray={grid === "dashed" ? "6 6" : undefined}
          />
        ) : null}
        <XAxis
          dataKey={xKey}
          tickLine={false}
          axisLine={false}
          tickMargin={10}
          interval={tickLabels ? 0 : "preserveStartEnd"}
          minTickGap={tickLabels ? 0 : 24}
          tickFormatter={
            tickLabels ? (_, index) => tickLabels[index] ?? "" : (v) => xFormatter(v)
          }
        />
        <YAxis
          hide={!showYAxis}
          tickLine={false}
          axisLine={false}
          tickMargin={8}
          width={44}
          tickFormatter={yFormatter}
        />
        {showTooltip ? (
          <ChartTooltip
            cursor={false}
            isAnimationActive={false}
            content={({ active, payload }) => {
              const entry = payload?.[0]
              if (!active || !entry) return null
              const row = entry.payload as BarRow
              const index = data.indexOf(row)
              const value = Number(row[yKey])
              return (
                <div className="bg-background rounded-lg border px-3 py-2 text-xs shadow-md">
                  <div className="text-sm font-semibold tabular-nums">
                    {yFormatter ? yFormatter(value) : String(value)}
                  </div>
                  <div className="text-muted-foreground">
                    {tooltipLabel ? tooltipLabel(row, index) : xFormatter(row[xKey])}
                  </div>
                </div>
              )
            }}
          />
        ) : null}
        <Bar
          dataKey={yKey}
          radius={barRadius}
          isAnimationActive={false}
          activeBar={activeBar}
          onClick={
            onBarClick
              ? (_, index) => onBarClick(data[index]!, index)
              : undefined
          }
          className={onBarClick ? "cursor-pointer" : undefined}
        >
          {data.map((_, index) => (
            <Cell key={index} fill={fillFor(index)} />
          ))}
        </Bar>
        {referenceLines.map((line, index) => (
          <ReferenceLine
            key={index}
            y={line.y}
            ifOverflow="extendDomain"
            stroke={line.color ?? "var(--muted-foreground)"}
            strokeDasharray={line.dashed === false ? undefined : "4 4"}
            label={
              line.label
                ? {
                    value: line.label,
                    position: "insideTopRight",
                    fill: line.color ?? "var(--muted-foreground)",
                    fontSize: 11,
                  }
                : undefined
            }
          />
        ))}
      </RechartsBarChart>
    </ChartContainer>
  )
}

export { BarChart }
```

### components/ui/delta-badge.tsx

```tsx
import * as React from "react"
import { Minus, TrendingDown, TrendingUp } from "lucide-react"

import { cn } from "@/lib/utils"
import { formatDelta } from "@/lib/format"

export type DeltaDirection = "up" | "down" | "flat"

export function getDeltaDirection(delta: number | undefined): DeltaDirection {
  if (delta === undefined || delta === 0 || !Number.isFinite(delta)) return "flat"
  return delta > 0 ? "up" : "down"
}

const directionIcon: Record<DeltaDirection, React.ElementType> = {
  up: TrendingUp,
  down: TrendingDown,
  flat: Minus,
}

export interface DeltaBadgeProps extends React.ComponentProps<"span"> {
  /** Fractional change, e.g. 0.124 for +12.4%. */
  delta: number
  /** Treat a decrease as good and an increase as bad (churn, latency, errors). */
  invert?: boolean
  variant?: "outline" | "soft" | "text"
  showIcon?: boolean
}

function DeltaBadge({
  delta,
  invert = false,
  variant = "outline",
  showIcon = true,
  className,
  children,
  ...props
}: DeltaBadgeProps) {
  const direction = getDeltaDirection(delta)
  const positive = direction === "flat" ? null : (direction === "up") !== invert
  const Icon = directionIcon[direction]

  return (
    <span
      data-slot="delta-badge"
      data-direction={direction}
      data-positive={positive}
      className={cn(
        "inline-flex items-center gap-1 text-xs font-medium tabular-nums",
        variant === "outline" && "rounded-md border px-1.5 py-0.5",
        variant === "soft" && "rounded-md px-1.5 py-0.5",
        variant === "soft" && positive === true && "bg-emerald-500/10",
        variant === "soft" && positive === false && "bg-red-500/10",
        variant === "soft" && positive === null && "bg-muted",
        positive === true && "text-emerald-600 dark:text-emerald-400",
        positive === false && "text-red-600 dark:text-red-400",
        positive === null && "text-muted-foreground",
        className
      )}
      {...props}
    >
      {showIcon ? <Icon className="size-3" aria-hidden="true" /> : null}
      {children ?? formatDelta(delta)}
    </span>
  )
}

export { DeltaBadge }
```

### components/ui/period-tabs.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"

export interface PeriodOption {
  value: string
  label: string
}

export const defaultPeriods: PeriodOption[] = [
  { value: "week", label: "Week" },
  { value: "month", label: "Month" },
  { value: "year", label: "Year" },
]

export interface PeriodTabsProps
  extends Omit<React.ComponentProps<typeof Tabs>, "children"> {
  options?: PeriodOption[]
  size?: "sm" | "default"
  /** Slide a single pill between tabs instead of swapping backgrounds. */
  animated?: boolean
}

interface IndicatorRect {
  left: number
  top: number
  width: number
  height: number
}

/** Small segmented control for switching a chart's time range. */
function PeriodTabs({
  options = defaultPeriods,
  size = "sm",
  animated = false,
  className,
  value,
  defaultValue,
  onValueChange,
  ...props
}: PeriodTabsProps) {
  const listRef = React.useRef<HTMLDivElement>(null)
  const [internalValue, setInternalValue] = React.useState(
    defaultValue ?? options[0]?.value
  )
  const active = value ?? internalValue
  const [rect, setRect] = React.useState<IndicatorRect | null>(null)

  const measure = React.useCallback(() => {
    const list = listRef.current
    if (!list) return
    const trigger = list.querySelector<HTMLElement>('[data-state="active"]')
    if (!trigger) return
    setRect({
      left: trigger.offsetLeft,
      top: trigger.offsetTop,
      width: trigger.offsetWidth,
      height: trigger.offsetHeight,
    })
  }, [])

  React.useLayoutEffect(() => {
    if (!animated) return
    measure()
  }, [animated, active, options, size, measure])

  React.useEffect(() => {
    if (!animated || !listRef.current) return
    const observer = new ResizeObserver(measure)
    observer.observe(listRef.current)
    return () => observer.disconnect()
  }, [animated, measure])

  return (
    <Tabs
      data-slot="period-tabs"
      className={cn("w-fit", className)}
      value={value}
      defaultValue={defaultValue}
      onValueChange={(next) => {
        setInternalValue(next)
        onValueChange?.(next)
      }}
      {...props}
    >
      <TabsList
        ref={listRef}
        className={cn(
          "relative",
          size === "sm" && "group-data-[orientation=horizontal]/tabs:h-8 p-1"
        )}
      >
        {animated && rect ? (
          <span
            aria-hidden
            data-slot="period-tabs-indicator"
            className="pointer-events-none absolute rounded-md bg-background shadow-sm transition-[left,top,width,height] duration-300 ease-[cubic-bezier(0.25,1,0.5,1)] motion-reduce:transition-none dark:border dark:border-input dark:bg-input/30"
            style={rect}
          />
        ) : null}
        {options.map((option) => (
          <TabsTrigger
            key={option.value}
            value={option.value}
            className={cn(
              size === "sm" && "h-6 px-2.5 text-xs",
              animated &&
                "relative z-10 data-[state=active]:bg-transparent group-data-[variant=default]/tabs-list:data-[state=active]:shadow-none dark:data-[state=active]:border-transparent dark:data-[state=active]:bg-transparent"
            )}
          >
            {option.label}
          </TabsTrigger>
        ))}
      </TabsList>
    </Tabs>
  )
}

export { PeriodTabs }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Progress Card

A compact progress card with an icon title, a pill tick bar, and a count with a secondary stat.

A compact progress card with an icon title, a pill-style tick bar, and a count with a secondary stat. Good for onboarding steps, task completion, and quotas in a sidebar or grid.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/progress-card.json
```

Also installs `card`, `tooltip` from shadcn/ui if missing.

## Usage

```tsx
import { ProgressCard } from "@/components/progress-card"

<ProgressCard
  title="Compliance checks"
  icon={<ShieldCheck />}
  value={16}
  max={24}
  label="checks passing"
  detail="67% assigned"
/>
```

## Examples

### Default

```tsx
import { EllipsisVertical, ShieldCheck } from "lucide-react"

import { Button } from "@/components/ui/button"
import { ProgressCard } from "@/registry/dashboardcn/blocks/progress-card"

export default function ProgressCardDemo() {
  return (
    <ProgressCard
      className="w-full max-w-sm"
      title="Compliance checks"
      icon={<ShieldCheck />}
      action={
        <Button variant="ghost" size="icon-xs" className="text-muted-foreground -mr-1.5">
          <EllipsisVertical />
          <span className="sr-only">More</span>
        </Button>
      }
      value={16}
      max={24}
      label="checks passing"
      detail="67% assigned"
    />
  )
}
```

## Source

### components/progress-card.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import {
  Card,
  CardAction,
  CardContent,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card"
import { TickBar } from "@/components/ui/tick-bar"
import { MetricValue } from "@/components/ui/metric-value"

export interface ProgressCardProps extends React.ComponentProps<typeof Card> {
  title: string
  icon?: React.ReactNode
  /** Slot in the top-right corner, e.g. a menu button. */
  action?: React.ReactNode
  value: number
  max: number
  /** Noun after the count, e.g. "checks passing" renders "16/24 checks passing". */
  label?: string
  /** Secondary stat on the right of the footer, e.g. "67% assigned". */
  detail?: React.ReactNode
  /** Any CSS color for the filled ticks. Defaults to the foreground color. */
  color?: string
  /** Number of ticks in the bar. */
  segments?: number
  shape?: "tick" | "pill"
}

/** A compact progress card with an icon title, a pill tick bar, and a count with a secondary stat. */
function ProgressCard({
  title,
  icon,
  action,
  value,
  max,
  label,
  detail,
  color = "var(--foreground)",
  segments = 24,
  shape = "pill",
  className,
  ...props
}: ProgressCardProps) {
  return (
    <Card data-slot="progress-card" className={cn("gap-4", className)} {...props}>
      <CardHeader>
        <CardTitle className="flex items-center gap-2 text-sm [&>svg]:size-4">
          {icon}
          <span className="truncate">{title}</span>
        </CardTitle>
        {action ? <CardAction>{action}</CardAction> : null}
      </CardHeader>
      <CardContent>
        <TickBar value={value} max={max} segments={segments} shape={shape} color={color} />
      </CardContent>
      {label || detail ? (
        <CardFooter className="justify-between gap-4 text-sm">
          <span className="text-muted-foreground tabular-nums">
            <MetricValue value={value} />/<MetricValue value={max} />
            {label ? ` ${label}` : null}
          </span>
          {detail ? <span className="shrink-0 font-semibold">{detail}</span> : null}
        </CardFooter>
      ) : null}
    </Card>
  )
}

export { ProgressCard }
```

### components/ui/tick-bar.tsx

```tsx
import * as React from "react"

import { cn } from "@/lib/utils"

export interface TickBarProps extends React.ComponentProps<"div"> {
  /** Current value, from 0 to max. */
  value: number
  max?: number
  /** Number of ticks. */
  segments?: number
  /** Any CSS color for the filled ticks. Defaults to chart-1. */
  color?: string
  /** Any CSS color for the unfilled ticks. Defaults to muted. */
  trackColor?: string
  /** "tick" draws thin bars; "pill" draws wide rounded ones. */
  shape?: "tick" | "pill"
}

/** A progress bar drawn as a row of ticks, lit up to the current value. */
function TickBar({
  value,
  max = 100,
  segments = 40,
  color = "var(--chart-1)",
  trackColor,
  shape = "tick",
  className,
  ...props
}: TickBarProps) {
  const fraction = Math.min(1, Math.max(0, value / (max || 1)))
  // Any non-zero value lights at least one tick so small values still register.
  const filled = fraction === 0 ? 0 : Math.max(1, Math.round(fraction * segments))

  return (
    <div
      data-slot="tick-bar"
      data-shape={shape}
      role="progressbar"
      aria-valuemin={0}
      aria-valuemax={max}
      aria-valuenow={value}
      className={cn(
        "flex w-full",
        shape === "tick" ? "h-6 gap-[3px]" : "h-4 gap-1.5",
        className
      )}
      {...props}
    >
      {Array.from({ length: segments }, (_, index) => {
        const lit = index < filled
        return (
          <span
            key={index}
            data-filled={lit}
            className={cn(
              "bg-muted h-full min-w-0 flex-1 transition-colors",
              shape === "tick" ? "rounded-[1.5px]" : "rounded-full"
            )}
            style={{ backgroundColor: lit ? color : trackColor }}
          />
        )
      })}
    </div>
  )
}

export { TickBar }
```

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Ring KPI Card

A card with a row of KPI tiles, each with a segmented ring next to the value and a comparison to the previous value.

A row of KPI tiles where each value sits next to a small segmented ring showing progress or share, with a comparison to the previous value beneath. Good for targets and quotas.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/ring-kpi-card.json
```

Also installs `card`, `tooltip` from shadcn/ui if missing.

npm dependencies: `lucide-react`.

## Usage

```tsx
import { RingKpiCard } from "@/components/ring-kpi-card"

<RingKpiCard
  metrics={[
    { label: "API response time", value: 132, previous: 148, unit: "ms", max: 200, invertDelta: true },
    { label: "Error rate", value: 1.4, previous: 0.9, unit: "%", max: 5, invertDelta: true },
    { label: "Request throughput", value: 4300, previous: 3900, format: "compact", unit: "req/s", max: 5000 },
  ]}
/>
```

## Examples

### Default

```tsx
import { EllipsisVertical } from "lucide-react"

import { Button } from "@/components/ui/button"
import { RingKpiCard } from "@/registry/dashboardcn/blocks/ring-kpi-card"

const menu = (
  <Button variant="ghost" size="icon-xs" className="text-muted-foreground -mr-1.5">
    <EllipsisVertical />
    <span className="sr-only">More</span>
  </Button>
)

export default function RingKpiCardDemo() {
  return (
    <RingKpiCard
      className="w-full"
      metrics={[
        { label: "API response time", value: 132, previous: 148, unit: "ms", max: 200, invertDelta: true, action: menu },
        { label: "Error rate", value: 1.4, previous: 0.9, unit: "%", max: 5, invertDelta: true, action: menu },
        { label: "Request throughput", value: 4300, previous: 3900, format: "compact", unit: "req/s", max: 5000, action: menu },
      ]}
    />
  )
}
```

## Source

### components/ring-kpi-card.tsx

```tsx
"use client"

import * as React from "react"
import { TrendingDown, TrendingUp } from "lucide-react"

import { cn } from "@/lib/utils"
import { type NumberFormat } from "@/lib/format"
import { Card, CardContent } from "@/components/ui/card"
import { RadialGauge } from "@/components/ui/radial-gauge"
import { MetricValue } from "@/components/ui/metric-value"

export interface RingKpiMetric {
  label: string
  value: number
  /** Previous value, shown as "up from" or "down from". */
  previous?: number
  /** Ring fill from 0 to 100. Defaults to value as a share of max. */
  progress?: number
  /** Upper bound used to fill the ring when progress is not given. */
  max?: number
  format?: NumberFormat
  currency?: string
  /** Suffix after the number, e.g. "ms" or "req/s". */
  unit?: string
  /** Treat a decrease as good (latency, errors). */
  invertDelta?: boolean
  /** Slot in the top-right corner, e.g. a menu button. */
  action?: React.ReactNode
}

export interface RingKpiCardProps extends React.ComponentProps<typeof Card> {
  metrics: RingKpiMetric[]
}

function RingKpiValue({
  metric,
  value,
  className,
}: {
  metric: RingKpiMetric
  value: number
  className?: string
}) {
  return (
    <MetricValue
      value={value}
      format={metric.format}
      currency={metric.currency}
      maximumFractionDigits={metric.format ? undefined : 1}
      suffix={metric.unit ? ` ${metric.unit}` : undefined}
      className={className}
    />
  )
}

/** A card with a row of KPI tiles, each with a segmented ring next to the value and a comparison to the previous value. */
function RingKpiCard({ metrics, className, ...props }: RingKpiCardProps) {
  return (
    <Card
      data-slot="ring-kpi-card"
      className={cn("overflow-hidden py-0", className)}
      {...props}
    >
      <CardContent className="px-0">
        {/* Tiles wrap to fit and stretch to fill their row; the gap shows the border color as hairline dividers. */}
        <div className="bg-border flex flex-wrap gap-px">
          {metrics.map((metric) => {
            const direction =
              metric.previous === undefined || metric.previous === metric.value
                ? "flat"
                : metric.value > metric.previous
                  ? "up"
                  : "down"
            const positive =
              direction === "flat" ? null : (direction === "up") !== Boolean(metric.invertDelta)
            const color =
              positive === false ? "var(--color-red-500)" : "var(--color-emerald-500)"
            const progress =
              metric.progress ??
              (metric.max ? (metric.value / metric.max) * 100 : 0)
            const Icon = direction === "down" ? TrendingDown : TrendingUp
            return (
              <div
                key={metric.label}
                data-slot="ring-kpi-metric"
                className="bg-card flex min-w-0 flex-[1_1_13rem] flex-col gap-4 p-5"
              >
                <div className="flex items-center justify-between gap-2">
                  <span className="text-muted-foreground truncate text-sm">{metric.label}</span>
                  {metric.action ? <span className="shrink-0">{metric.action}</span> : null}
                </div>
                <div className="flex items-center gap-3">
                  <RadialGauge
                    value={progress}
                    sweep={360}
                    size={40}
                    thickness={4}
                    segments={14}
                    gap={7}
                    color={color}
                  />
                  <RingKpiValue
                    metric={metric}
                    value={metric.value}
                    className="truncate text-2xl font-semibold tracking-tight"
                  />
                </div>
                {metric.previous !== undefined ? (
                  <span
                    data-direction={direction}
                    data-positive={positive}
                    className={cn(
                      "text-muted-foreground flex flex-wrap items-center gap-x-1.5 gap-y-0.5 text-xs",
                      positive === true && "[&_[data-accent]]:text-emerald-600 dark:[&_[data-accent]]:text-emerald-400",
                      positive === false && "[&_[data-accent]]:text-red-600 dark:[&_[data-accent]]:text-red-400"
                    )}
                  >
                    {direction !== "flat" ? (
                      <Icon data-accent="" className="size-3.5" aria-hidden="true" />
                    ) : null}
                    {direction === "flat" ? "unchanged from" : direction === "up" ? "up from" : "down from"}{" "}
                    <RingKpiValue
                      metric={metric}
                      value={metric.previous}
                      data-accent=""
                      className="font-medium"
                    />
                  </span>
                ) : null}
              </div>
            )
          })}
        </div>
      </CardContent>
    </Card>
  )
}

export { RingKpiCard }
```

### components/ui/radial-gauge.tsx

```tsx
import * as React from "react"

import { cn } from "@/lib/utils"

export interface RadialGaugeProps extends React.ComponentProps<"div"> {
  value: number
  min?: number
  max?: number
  /** Diameter in pixels. */
  size?: number
  /** Stroke width in pixels. */
  thickness?: number
  /** Number of arc segments. 0 draws a continuous arc. */
  segments?: number
  /** Gap between segments in degrees. */
  gap?: number
  /** Angle where the arc starts, in degrees clockwise from 12 o'clock. */
  startAngle?: number
  /** Total sweep of the arc in degrees. 180 is a semicircle, 360 a ring. */
  sweep?: number
  /** Any CSS color. Defaults to chart-1. */
  color?: string
  trackColor?: string
  /** Content rendered in the middle of the gauge. */
  children?: React.ReactNode
}

// Round so server and client render identical path strings.
const round = (n: number) => Math.round(n * 1000) / 1000

function polar(cx: number, cy: number, r: number, angleDeg: number) {
  const rad = ((angleDeg - 90) * Math.PI) / 180
  return { x: round(cx + r * Math.cos(rad)), y: round(cy + r * Math.sin(rad)) }
}

function arcPath(cx: number, cy: number, r: number, from: number, to: number) {
  const start = polar(cx, cy, r, from)
  const end = polar(cx, cy, r, to)
  const largeArc = to - from > 180 ? 1 : 0
  return `M ${start.x} ${start.y} A ${r} ${r} 0 ${largeArc} 1 ${end.x} ${end.y}`
}

function RadialGauge({
  value,
  min = 0,
  max = 100,
  size = 160,
  thickness = 10,
  segments = 0,
  gap = 2,
  startAngle,
  sweep = 180,
  color = "var(--chart-1)",
  trackColor = "var(--muted)",
  className,
  children,
  ...props
}: RadialGaugeProps) {
  const fraction = Math.min(1, Math.max(0, (value - min) / (max - min || 1)))
  const start = startAngle ?? (sweep >= 360 ? 0 : -sweep / 2)
  const r = size / 2 - thickness / 2
  const cx = size / 2
  const cy = size / 2
  // Trim the box to the arc's vertical extent so a semicircle does not
  // reserve a full circle of space.
  const angles = Array.from({ length: 64 }, (_, i) => start + (sweep * i) / 63)
  const ys = angles.map((a) => polar(cx, cy, r, a).y)
  const top = Math.max(0, Math.min(...ys) - thickness / 2)
  const bottom = Math.min(size, Math.max(...ys) + thickness / 2)
  const height = bottom - top

  const arcs: { from: number; to: number; filled: boolean }[] = []
  if (segments > 0) {
    const step = sweep / segments
    for (let i = 0; i < segments; i++) {
      const from = start + i * step + gap / 2
      const to = start + (i + 1) * step - gap / 2
      const mid = (i + 0.5) / segments
      arcs.push({ from, to, filled: mid <= fraction })
    }
  }

  return (
    <div
      data-slot="radial-gauge"
      role="meter"
      aria-valuemin={min}
      aria-valuemax={max}
      aria-valuenow={value}
      className={cn("relative inline-flex shrink-0", className)}
      style={{ width: size, height }}
      {...props}
    >
      <svg
        width={size}
        height={height}
        viewBox={`0 ${top} ${size} ${height}`}
        className="absolute inset-0"
        aria-hidden="true"
      >
        {segments > 0 ? (
          arcs.map((arc, index) => (
            <path
              key={index}
              d={arcPath(cx, cy, r, arc.from, arc.to)}
              fill="none"
              stroke={arc.filled ? color : trackColor}
              strokeWidth={thickness}
              strokeLinecap="butt"
            />
          ))
        ) : (
          <>
            <path
              d={arcPath(cx, cy, r, start, start + sweep - (sweep >= 360 ? 0.01 : 0))}
              fill="none"
              stroke={trackColor}
              strokeWidth={thickness}
              strokeLinecap={sweep >= 360 ? "butt" : "round"}
            />
            {fraction > 0 ? (
              <path
                d={arcPath(cx, cy, r, start, start + sweep * fraction)}
                fill="none"
                stroke={color}
                strokeWidth={thickness}
                strokeLinecap="round"
                className="transition-[d] duration-500"
              />
            ) : null}
          </>
        )}
      </svg>
      {children ? (
        <div
          className={cn(
            "absolute inset-x-0 flex flex-col items-center justify-center text-center",
            sweep > 200 ? "inset-y-0" : "bottom-0"
          )}
        >
          {children}
        </div>
      ) : null}
    </div>
  )
}

export { RadialGauge }
```

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Score Gauge Card

A score card with a headline word, a radial gauge around the score, and a breakdown list of labelled bars.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/score-gauge-card.json
```

Also installs `card`, `tooltip` from shadcn/ui if missing.

## Usage

```tsx
import { ScoreGaugeCard } from "@/components/score-gauge-card"

<ScoreGaugeCard
  title="Sleep score"
  status="Excellent"
  caption="29 Jun - 5 Jul"
  score={98}
  color="var(--color-violet-500)"
  items={[
    { label: "Duration", detail: "7h 50m", value: 49, max: 50 },
    { label: "Bedtime", detail: "11:12 PM", value: 29, max: 30 },
    { label: "Interruptions", detail: "2 times", value: 20, max: 20 },
  ]}
/>
```

## Examples

### Default

```tsx
import { EllipsisVertical } from "lucide-react"

import { Button } from "@/components/ui/button"
import { ScoreGaugeCard } from "@/registry/dashboardcn/blocks/score-gauge-card"

export default function ScoreGaugeCardDemo() {
  return (
    <ScoreGaugeCard
      className="w-full max-w-md"
      title="Sleep score"
      caption="29 Jun - 5 Jul"
      score={98}
      color="var(--color-violet-500)"
      items={[
        { label: "Duration", detail: "7h 50m", value: 49, max: 50 },
        { label: "Bedtime", detail: "11:12 PM", value: 29, max: 30 },
        { label: "Interruptions", detail: "2 times", value: 20, max: 20 },
      ]}
      action={
        <Button variant="ghost" size="icon-xs" className="text-muted-foreground -mr-1.5">
          <EllipsisVertical />
          <span className="sr-only">More</span>
        </Button>
      }
    />
  )
}
```

## Source

### components/score-gauge-card.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@/components/ui/card"
import { RadialGauge } from "@/components/ui/radial-gauge"
import { TickBar } from "@/components/ui/tick-bar"
import { MetricValue } from "@/components/ui/metric-value"

export interface ScoreGaugeItem {
  label: string
  /** Text after the label, e.g. "7h 50m" renders "Duration: 7h 50m". */
  detail?: string
  value: number
  max: number
  /** Any CSS color for the bar. Defaults to the card color. */
  color?: string
}

export interface ScoreGaugeStatus {
  /** Lowest score that earns this label. */
  min: number
  label: string
}

/** Applied to the score as a share of max when neither status nor statuses is given. */
const defaultStatuses: ScoreGaugeStatus[] = [
  { min: 0, label: "Poor" },
  { min: 50, label: "Fair" },
  { min: 70, label: "Good" },
  { min: 85, label: "Excellent" },
]

export interface ScoreGaugeCardProps extends React.ComponentProps<typeof Card> {
  title: string
  /** Headline word, e.g. "Excellent". Derived from statuses when omitted. */
  status?: string
  /** Score thresholds used to derive the headline word, e.g. [{ min: 85, label: "Excellent" }]. */
  statuses?: ScoreGaugeStatus[]
  /** Period text under the headline, e.g. "29 Jun - 5 Jul". */
  caption?: string
  score: number
  max?: number
  /** Any CSS color for the gauge and bars. Defaults to chart-1. */
  color?: string
  /** Gauge diameter in pixels. */
  gaugeSize?: number
  /** Gauge stroke width in pixels. */
  thickness?: number
  /** Number of gauge segments. 0 draws a continuous arc. */
  segments?: number
  /** Gap between gauge segments in degrees. */
  segmentGap?: number
  /** Gauge sweep in degrees. 360 draws a ring, 180 a semicircle. */
  sweep?: number
  /** Ticks in each breakdown bar. 0 draws a solid bar. */
  barSegments?: number
  /** Breakdown rows, each with a bar filled to value/max. */
  items: ScoreGaugeItem[]
  /** Slot in the top-right corner, e.g. a menu button. */
  action?: React.ReactNode
}

function deriveStatus(score: number, statuses: ScoreGaugeStatus[]) {
  let match: ScoreGaugeStatus | undefined
  for (const status of statuses) {
    if (score >= status.min && (!match || status.min >= match.min)) match = status
  }
  return match?.label
}

/** A score card with a headline word, a radial gauge around the score, and a breakdown list of labelled bars. */
function ScoreGaugeCard({
  title,
  status,
  statuses,
  caption,
  score,
  max = 100,
  color = "var(--chart-1)",
  gaugeSize = 160,
  thickness = 12,
  segments = 0,
  segmentGap = 2,
  sweep = 360,
  barSegments = 0,
  items,
  action,
  className,
  ...props
}: ScoreGaugeCardProps) {
  const headline =
    status ??
    (statuses
      ? deriveStatus(score, statuses)
      : deriveStatus((score / (max || 1)) * 100, defaultStatuses))

  return (
    <Card
      data-slot="score-gauge-card"
      className={cn("@container/card gap-4", className)}
      {...props}
    >
      <CardHeader>
        <CardDescription>{title}</CardDescription>
        {headline ? (
          <CardTitle className="text-2xl font-semibold tracking-tight">{headline}</CardTitle>
        ) : null}
        {caption ? (
          <div className="text-muted-foreground text-sm tabular-nums">{caption}</div>
        ) : null}
        {action ? <CardAction>{action}</CardAction> : null}
      </CardHeader>
      <CardContent>
        <div className="flex flex-col items-center gap-6 @sm/card:flex-row @sm/card:items-center @sm/card:gap-8">
          <RadialGauge
            value={score}
            max={max}
            size={gaugeSize}
            thickness={thickness}
            segments={segments}
            gap={segmentGap}
            sweep={sweep}
            color={color}
            aria-label={`${title}: ${score} of ${max}`}
            className="shrink-0"
          >
            <MetricValue
              value={score}
              className="text-4xl font-semibold tracking-tight"
            />
          </RadialGauge>
          <ul className="flex w-full min-w-0 flex-1 flex-col gap-4">
            {items.map((item) => {
              const fraction = Math.min(1, Math.max(0, item.value / (item.max || 1)))
              const barColor = item.color ?? color
              return (
                <li key={item.label} className="flex flex-col gap-1.5">
                  <div className="flex items-baseline justify-between gap-3 text-sm">
                    <span className="min-w-0 truncate">
                      <span className="font-medium">{item.label}</span>
                      {item.detail ? (
                        <span className="text-muted-foreground">: {item.detail}</span>
                      ) : null}
                    </span>
                    <span className="text-muted-foreground shrink-0 tabular-nums">
                      <MetricValue value={item.value} className="text-foreground font-medium" />
                      /
                      <MetricValue value={item.max} />
                    </span>
                  </div>
                  {barSegments > 0 ? (
                    <TickBar
                      value={item.value}
                      max={item.max}
                      segments={barSegments}
                      shape="pill"
                      color={barColor}
                      className="h-2"
                    />
                  ) : (
                    <div
                      role="progressbar"
                      aria-label={item.label}
                      aria-valuemin={0}
                      aria-valuemax={item.max}
                      aria-valuenow={item.value}
                      className="bg-muted h-2 w-full overflow-hidden rounded-full"
                    >
                      <div
                        className="h-full rounded-full transition-[width] duration-500"
                        style={{
                          width: `${Math.round(fraction * 1000) / 10}%`,
                          backgroundColor: barColor,
                        }}
                      />
                    </div>
                  )}
                </li>
              )
            })}
          </ul>
        </div>
      </CardContent>
    </Card>
  )
}

export { ScoreGaugeCard }
```

### components/ui/radial-gauge.tsx

```tsx
import * as React from "react"

import { cn } from "@/lib/utils"

export interface RadialGaugeProps extends React.ComponentProps<"div"> {
  value: number
  min?: number
  max?: number
  /** Diameter in pixels. */
  size?: number
  /** Stroke width in pixels. */
  thickness?: number
  /** Number of arc segments. 0 draws a continuous arc. */
  segments?: number
  /** Gap between segments in degrees. */
  gap?: number
  /** Angle where the arc starts, in degrees clockwise from 12 o'clock. */
  startAngle?: number
  /** Total sweep of the arc in degrees. 180 is a semicircle, 360 a ring. */
  sweep?: number
  /** Any CSS color. Defaults to chart-1. */
  color?: string
  trackColor?: string
  /** Content rendered in the middle of the gauge. */
  children?: React.ReactNode
}

// Round so server and client render identical path strings.
const round = (n: number) => Math.round(n * 1000) / 1000

function polar(cx: number, cy: number, r: number, angleDeg: number) {
  const rad = ((angleDeg - 90) * Math.PI) / 180
  return { x: round(cx + r * Math.cos(rad)), y: round(cy + r * Math.sin(rad)) }
}

function arcPath(cx: number, cy: number, r: number, from: number, to: number) {
  const start = polar(cx, cy, r, from)
  const end = polar(cx, cy, r, to)
  const largeArc = to - from > 180 ? 1 : 0
  return `M ${start.x} ${start.y} A ${r} ${r} 0 ${largeArc} 1 ${end.x} ${end.y}`
}

function RadialGauge({
  value,
  min = 0,
  max = 100,
  size = 160,
  thickness = 10,
  segments = 0,
  gap = 2,
  startAngle,
  sweep = 180,
  color = "var(--chart-1)",
  trackColor = "var(--muted)",
  className,
  children,
  ...props
}: RadialGaugeProps) {
  const fraction = Math.min(1, Math.max(0, (value - min) / (max - min || 1)))
  const start = startAngle ?? (sweep >= 360 ? 0 : -sweep / 2)
  const r = size / 2 - thickness / 2
  const cx = size / 2
  const cy = size / 2
  // Trim the box to the arc's vertical extent so a semicircle does not
  // reserve a full circle of space.
  const angles = Array.from({ length: 64 }, (_, i) => start + (sweep * i) / 63)
  const ys = angles.map((a) => polar(cx, cy, r, a).y)
  const top = Math.max(0, Math.min(...ys) - thickness / 2)
  const bottom = Math.min(size, Math.max(...ys) + thickness / 2)
  const height = bottom - top

  const arcs: { from: number; to: number; filled: boolean }[] = []
  if (segments > 0) {
    const step = sweep / segments
    for (let i = 0; i < segments; i++) {
      const from = start + i * step + gap / 2
      const to = start + (i + 1) * step - gap / 2
      const mid = (i + 0.5) / segments
      arcs.push({ from, to, filled: mid <= fraction })
    }
  }

  return (
    <div
      data-slot="radial-gauge"
      role="meter"
      aria-valuemin={min}
      aria-valuemax={max}
      aria-valuenow={value}
      className={cn("relative inline-flex shrink-0", className)}
      style={{ width: size, height }}
      {...props}
    >
      <svg
        width={size}
        height={height}
        viewBox={`0 ${top} ${size} ${height}`}
        className="absolute inset-0"
        aria-hidden="true"
      >
        {segments > 0 ? (
          arcs.map((arc, index) => (
            <path
              key={index}
              d={arcPath(cx, cy, r, arc.from, arc.to)}
              fill="none"
              stroke={arc.filled ? color : trackColor}
              strokeWidth={thickness}
              strokeLinecap="butt"
            />
          ))
        ) : (
          <>
            <path
              d={arcPath(cx, cy, r, start, start + sweep - (sweep >= 360 ? 0.01 : 0))}
              fill="none"
              stroke={trackColor}
              strokeWidth={thickness}
              strokeLinecap={sweep >= 360 ? "butt" : "round"}
            />
            {fraction > 0 ? (
              <path
                d={arcPath(cx, cy, r, start, start + sweep * fraction)}
                fill="none"
                stroke={color}
                strokeWidth={thickness}
                strokeLinecap="round"
                className="transition-[d] duration-500"
              />
            ) : null}
          </>
        )}
      </svg>
      {children ? (
        <div
          className={cn(
            "absolute inset-x-0 flex flex-col items-center justify-center text-center",
            sweep > 200 ? "inset-y-0" : "bottom-0"
          )}
        >
          {children}
        </div>
      ) : null}
    </div>
  )
}

export { RadialGauge }
```

### components/ui/tick-bar.tsx

```tsx
import * as React from "react"

import { cn } from "@/lib/utils"

export interface TickBarProps extends React.ComponentProps<"div"> {
  /** Current value, from 0 to max. */
  value: number
  max?: number
  /** Number of ticks. */
  segments?: number
  /** Any CSS color for the filled ticks. Defaults to chart-1. */
  color?: string
  /** Any CSS color for the unfilled ticks. Defaults to muted. */
  trackColor?: string
  /** "tick" draws thin bars; "pill" draws wide rounded ones. */
  shape?: "tick" | "pill"
}

/** A progress bar drawn as a row of ticks, lit up to the current value. */
function TickBar({
  value,
  max = 100,
  segments = 40,
  color = "var(--chart-1)",
  trackColor,
  shape = "tick",
  className,
  ...props
}: TickBarProps) {
  const fraction = Math.min(1, Math.max(0, value / (max || 1)))
  // Any non-zero value lights at least one tick so small values still register.
  const filled = fraction === 0 ? 0 : Math.max(1, Math.round(fraction * segments))

  return (
    <div
      data-slot="tick-bar"
      data-shape={shape}
      role="progressbar"
      aria-valuemin={0}
      aria-valuemax={max}
      aria-valuenow={value}
      className={cn(
        "flex w-full",
        shape === "tick" ? "h-6 gap-[3px]" : "h-4 gap-1.5",
        className
      )}
      {...props}
    >
      {Array.from({ length: segments }, (_, index) => {
        const lit = index < filled
        return (
          <span
            key={index}
            data-filled={lit}
            className={cn(
              "bg-muted h-full min-w-0 flex-1 transition-colors",
              shape === "tick" ? "rounded-[1.5px]" : "rounded-full"
            )}
            style={{ backgroundColor: lit ? color : trackColor }}
          />
        )
      })}
    </div>
  )
}

export { TickBar }
```

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Stage Bars Card

The funnel as a list: a rounded bar per stage with its name, value, and share of the first stage, a range picker, and a tile per stage.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/stage-bars-card.json
```

Also installs `card`, `button`, `dropdown-menu`, `tooltip` from shadcn/ui if missing.

npm dependencies: `lucide-react`.

## Usage

```tsx
import { StageBarsCard } from "@/components/stage-bars-card"

<StageBarsCard
  title="Pipeline"
  caption="Last 30 days"
  delta={0.024}
  stages={[
    { name: "Visits", value: 4820, icon: <Eye /> },
    { name: "Sign-up", value: 3260, icon: <UserPlus /> },
    { name: "Active", value: 2010 },
    { name: "Pro", value: 1160 },
    { name: "Team", value: 540 },
    { name: "Enterprise", value: 180 },
  ]}
/>
```

## Examples

### Default

```tsx
import { Building2, Crown, Eye, UserPlus, Users, Zap } from "lucide-react"

import { StageBarsCard } from "@/registry/dashboardcn/blocks/stage-bars-card"

const icons = {
  visits: <Eye />,
  signup: <UserPlus />,
  active: <Zap />,
  pro: <Crown />,
  team: <Users />,
  enterprise: <Building2 />,
}

const colors = [
  "var(--color-lime-400)",
  "var(--color-blue-500)",
  "var(--color-violet-500)",
  "var(--color-pink-500)",
  "var(--color-amber-400)",
  "var(--color-emerald-500)",
]

function stages(values: number[]) {
  const names = ["Visits", "Sign-up", "Active", "Pro", "Team", "Enterprise"] as const
  const keys = ["visits", "signup", "active", "pro", "team", "enterprise"] as const
  return names.map((name, index) => ({
    name,
    value: values[index]!,
    color: colors[index],
    icon: icons[keys[index]!],
  }))
}

const ranges = [
  { value: "7d", label: "Last 7 days", delta: 0.024, stages: stages([1180, 790, 460, 250, 120, 40]) },
  { value: "30d", label: "Last 30 days", delta: 0.061, stages: stages([4820, 3260, 2010, 1160, 540, 180]) },
  { value: "90d", label: "Last 90 days", delta: -0.012, stages: stages([14200, 9410, 5630, 3120, 1480, 510]) },
]

export default function StageBarsCardDemo() {
  return (
    <StageBarsCard
      className="w-full max-w-lg"
      title="Pipeline"
      deltaLabel="vs previous period"
      ranges={ranges}
    />
  )
}
```

## Source

### components/stage-bars-card.tsx

```tsx
"use client"

import * as React from "react"
import { ChevronDown } from "lucide-react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import { Button } from "@/components/ui/button"
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@/components/ui/card"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
import { DeltaBadge } from "@/components/ui/delta-badge"
import { MetricValue } from "@/components/ui/metric-value"

export interface StageBarsStage {
  name: string
  value: number
  /** Any CSS color. Defaults to chart-1 through chart-5 in order. */
  color?: string
  /** Small icon drawn at the left end of the bar. */
  icon?: React.ReactNode
}

export interface StageBarsRange {
  value: string
  label: string
  /** Top of the funnel first. */
  stages: StageBarsStage[]
  /** Change in the first stage vs the previous range, as a fraction. */
  delta?: number
}

export interface StageBarsCardProps
  extends Omit<React.ComponentProps<typeof Card>, "children"> {
  title: string
  /** Top of the funnel first. Ignored when `ranges` is set. */
  stages?: StageBarsStage[]
  /** Change in the first stage, as a fraction. Ignored when `ranges` is set. */
  delta?: number
  /** Context for the delta, e.g. "vs last week". */
  deltaLabel?: string
  invertDelta?: boolean
  /** Static text in the header, e.g. "Last 30 days". Replaced by the picker when `ranges` is set. */
  caption?: string
  /** Ranges for the header picker. Each carries its own stages. */
  ranges?: StageBarsRange[]
  range?: string
  defaultRange?: string
  onRangeChange?: (value: string) => void
  format?: NumberFormat
  currency?: string
  /** Any CSS color. Paints every bar in it, in place of the per-stage palette. */
  color?: string
  /** Show a tile with the name and value for each stage under the bars. */
  showTiles?: boolean
  /** Show the icons inside the bars. */
  showIcons?: boolean
}

const defaultColors = [
  "var(--chart-1)",
  "var(--chart-2)",
  "var(--chart-3)",
  "var(--chart-4)",
  "var(--chart-5)",
]

/** The funnel as a list: a rounded bar per stage with its name, value, and share of the first stage. Hovering a stage swaps the headline. */
function StageBarsCard({
  title,
  stages: stagesProp = [],
  delta: deltaProp,
  deltaLabel,
  invertDelta,
  caption,
  ranges,
  range: rangeProp,
  defaultRange,
  onRangeChange,
  format = "number",
  currency,
  color,
  showTiles = true,
  showIcons = true,
  className,
  ...props
}: StageBarsCardProps) {
  const [rangeState, setRangeState] = React.useState(defaultRange ?? ranges?.[0]?.value)
  const range = rangeProp ?? rangeState
  const setRange = (value: string) => {
    setRangeState(value)
    onRangeChange?.(value)
  }
  const current = ranges?.find((option) => option.value === range) ?? ranges?.[0]
  const delta = current ? current.delta : deltaProp

  const first = (current?.stages ?? stagesProp)[0]
  const stages = (current?.stages ?? stagesProp).map((stage, index) => ({
    ...stage,
    share: first && first.value > 0 ? Math.min(1, Math.max(0, stage.value / first.value)) : 0,
    fill: stage.color ?? color ?? defaultColors[index % defaultColors.length],
    opacity: color && !stage.color ? 1 - index * (0.6 / Math.max(stagesProp.length - 1, 1)) : 1,
  }))

  const [active, setActive] = React.useState<number | null>(null)
  const hovered = active !== null ? stages[active] : undefined
  const headline = hovered ?? stages[0]
  const percent = (share: number) =>
    formatNumber(share, { format: "percent", maximumFractionDigits: 0 })

  return (
    <Card
      data-slot="stage-bars-card"
      className={cn("@container/card gap-4", className)}
      {...props}
    >
      <CardHeader>
        <CardDescription>{title}</CardDescription>
        <CardTitle className="text-3xl font-semibold tabular-nums tracking-tight">
          <MetricValue value={headline?.value ?? 0} format={format} currency={currency} />
        </CardTitle>
        <div className="flex h-5 items-center gap-1.5 text-sm">
          {hovered ? (
            <span className="text-muted-foreground truncate">
              {hovered.name}
              {hovered !== stages[0] ? (
                <>
                  {" · "}
                  <span className="text-foreground font-medium tabular-nums">
                    {percent(hovered.share)}
                  </span>{" "}
                  of {stages[0]?.name}
                </>
              ) : null}
            </span>
          ) : (
            <>
              {delta !== undefined ? (
                <DeltaBadge delta={delta} invert={invertDelta} variant="soft" />
              ) : null}
              {deltaLabel ? <span className="text-muted-foreground">{deltaLabel}</span> : null}
            </>
          )}
        </div>
        {ranges?.length ? (
          <CardAction>
            <DropdownMenu>
              <DropdownMenuTrigger asChild>
                <Button variant="outline" size="sm">
                  {current?.label}
                  <ChevronDown className="text-muted-foreground" />
                </Button>
              </DropdownMenuTrigger>
              <DropdownMenuContent align="end">
                <DropdownMenuRadioGroup value={range} onValueChange={setRange}>
                  {ranges.map((option) => (
                    <DropdownMenuRadioItem key={option.value} value={option.value}>
                      {option.label}
                    </DropdownMenuRadioItem>
                  ))}
                </DropdownMenuRadioGroup>
              </DropdownMenuContent>
            </DropdownMenu>
          </CardAction>
        ) : caption ? (
          <CardAction>
            <span className="text-muted-foreground text-sm">{caption}</span>
          </CardAction>
        ) : null}
      </CardHeader>
      <CardContent className="flex flex-col gap-5">
        {/* Subgrid keeps the label column as wide as the longest name across every row. */}
        <div
          data-slot="stage-bars"
          role="list"
          className="grid grid-cols-[auto_minmax(0,1fr)_auto] gap-y-1"
          onMouseLeave={() => setActive(null)}
        >
          {stages.map((stage, index) => (
            <div
              key={stage.name}
              role="listitem"
              data-active={active === index || undefined}
              onMouseEnter={() => setActive(index)}
              className={cn(
                "col-span-3 grid grid-cols-subgrid items-center gap-x-3 rounded-md px-1 py-1 transition-opacity duration-200 -mx-1",
                active !== null && active !== index && "opacity-40"
              )}
            >
              <span className="text-muted-foreground truncate text-right text-sm">
                {stage.name}
              </span>
              <div className="bg-muted relative h-4 overflow-hidden rounded-full">
                <div
                  className="relative h-full rounded-full transition-[width] duration-500 ease-out"
                  style={{
                    width: `${Math.round(stage.share * 1000) / 10}%`,
                    minWidth: stage.icon && showIcons ? 16 : 4,
                    backgroundColor: stage.fill,
                    opacity: stage.opacity,
                  }}
                >
                  {stage.icon && showIcons ? (
                    <span className="text-background absolute inset-y-0 left-0 flex w-4 items-center justify-center [&>svg]:size-3">
                      {stage.icon}
                    </span>
                  ) : null}
                </div>
              </div>
              <span className="flex items-baseline justify-end gap-2 text-sm tabular-nums">
                <span className="font-medium">
                  {formatNumber(stage.value, { format, currency })}
                </span>
                <span className="text-muted-foreground w-9 text-right text-xs">
                  {percent(stage.share)}
                </span>
              </span>
            </div>
          ))}
        </div>
        {showTiles ? (
          <div className="grid grid-cols-2 gap-2 @xs/card:grid-cols-3">
            {stages.map((stage, index) => (
              <div
                key={stage.name}
                data-active={active === index || undefined}
                onMouseEnter={() => setActive(index)}
                onMouseLeave={() => setActive(null)}
                className={cn(
                  "flex min-w-0 flex-col gap-0.5 rounded-lg border px-2.5 py-2 transition-[opacity,border-color] duration-200",
                  active !== null && active !== index && "opacity-50",
                  active === index && "border-foreground/20"
                )}
              >
                <span className="text-muted-foreground flex items-center gap-1.5 text-xs">
                  <span
                    aria-hidden="true"
                    className="size-2 shrink-0 rounded-full"
                    style={{ backgroundColor: stage.fill, opacity: stage.opacity }}
                  />
                  <span className="truncate">{stage.name}</span>
                </span>
                <span className="truncate text-sm font-semibold tabular-nums">
                  {formatNumber(stage.value, { format, currency })}
                </span>
              </div>
            ))}
          </div>
        ) : null}
      </CardContent>
    </Card>
  )
}

export { StageBarsCard }
```

### components/ui/delta-badge.tsx

```tsx
import * as React from "react"
import { Minus, TrendingDown, TrendingUp } from "lucide-react"

import { cn } from "@/lib/utils"
import { formatDelta } from "@/lib/format"

export type DeltaDirection = "up" | "down" | "flat"

export function getDeltaDirection(delta: number | undefined): DeltaDirection {
  if (delta === undefined || delta === 0 || !Number.isFinite(delta)) return "flat"
  return delta > 0 ? "up" : "down"
}

const directionIcon: Record<DeltaDirection, React.ElementType> = {
  up: TrendingUp,
  down: TrendingDown,
  flat: Minus,
}

export interface DeltaBadgeProps extends React.ComponentProps<"span"> {
  /** Fractional change, e.g. 0.124 for +12.4%. */
  delta: number
  /** Treat a decrease as good and an increase as bad (churn, latency, errors). */
  invert?: boolean
  variant?: "outline" | "soft" | "text"
  showIcon?: boolean
}

function DeltaBadge({
  delta,
  invert = false,
  variant = "outline",
  showIcon = true,
  className,
  children,
  ...props
}: DeltaBadgeProps) {
  const direction = getDeltaDirection(delta)
  const positive = direction === "flat" ? null : (direction === "up") !== invert
  const Icon = directionIcon[direction]

  return (
    <span
      data-slot="delta-badge"
      data-direction={direction}
      data-positive={positive}
      className={cn(
        "inline-flex items-center gap-1 text-xs font-medium tabular-nums",
        variant === "outline" && "rounded-md border px-1.5 py-0.5",
        variant === "soft" && "rounded-md px-1.5 py-0.5",
        variant === "soft" && positive === true && "bg-emerald-500/10",
        variant === "soft" && positive === false && "bg-red-500/10",
        variant === "soft" && positive === null && "bg-muted",
        positive === true && "text-emerald-600 dark:text-emerald-400",
        positive === false && "text-red-600 dark:text-red-400",
        positive === null && "text-muted-foreground",
        className
      )}
      {...props}
    >
      {showIcon ? <Icon className="size-3" aria-hidden="true" /> : null}
      {children ?? formatDelta(delta)}
    </span>
  )
}

export { DeltaBadge }
```

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Status Gauge Card

A status card with a headline word, a metric, an avatar stack, and a segmented semicircular gauge.

A status card with a headline word, a metric, an avatar stack, and a segmented semicircular gauge. Use it for system health, sleep scores, or any state that is best read as a word first and a number second.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/status-gauge-card.json
```

Also installs `card`, `button`, `tooltip` from shadcn/ui if missing.

## Usage

```tsx
import { StatusGaugeCard } from "@/components/status-gauge-card"

<StatusGaugeCard
  title="Performance metrics"
  status="Stable"
  metricLabel="Server uptime"
  value={0.997}
  color="var(--color-emerald-500)"
  segments={40}
  segmentGap={2.5}
  thickness={14}
  people={[
    { name: "shadcn", src: "https://github.com/shadcn.png" },
    { name: "Kai" },
  ]}
  peopleLabel="6 reviewers"
  action={{ label: "Details", href: "/uptime" }}
/>
```

## Examples

### Default

```tsx
import { StatusGaugeCard } from "@/registry/dashboardcn/blocks/status-gauge-card"

export default function StatusGaugeCardDemo() {
  return (
    <div className="@container w-full">
      <div className="grid gap-4 @2xl:grid-cols-2">
        <StatusGaugeCard
          title="Performance metrics"
          status="Stable"
          metricLabel="Server uptime"
          value={0.997}
          color="var(--color-emerald-500)"
          people={[
            { name: "shadcn", src: "https://github.com/shadcn.png" },
            { name: "Kai" },
            { name: "Max Leiter", src: "https://github.com/maxleiter.png" },
          ]}
          peopleLabel="6 reviewers"
          action={{ label: "Details", href: "#" }}
        />
        <StatusGaugeCard
          title="Quality metrics"
          status="In review"
          metricLabel="Code coverage"
          value={0.482}
          color="var(--color-amber-500)"
          people={[
            { name: "Evil Rabbit", src: "https://github.com/evilrabbit.png" },
            { name: "shadcn", src: "https://github.com/shadcn.png" },
            { name: "Kai" },
          ]}
          peopleLabel="9 testers"
          action={{ label: "Details", href: "#" }}
        />
      </div>
    </div>
  )
}
```

## Source

### components/status-gauge-card.tsx

```tsx
"use client"

import * as React from "react"
import { ArrowUpRight } from "lucide-react"

import { cn } from "@/lib/utils"
import { type NumberFormat } from "@/lib/format"
import { Button } from "@/components/ui/button"
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
import { RadialGauge } from "@/components/ui/radial-gauge"
import { MetricValue } from "@/components/ui/metric-value"

export interface StatusGaugePerson {
  name: string
  /** Avatar image. Falls back to the first letter of the name. */
  src?: string
}

export interface StatusGaugeCardProps extends React.ComponentProps<typeof Card> {
  title: string
  /** Short status word, e.g. "Stable" or "In review". */
  status: string
  /** Metric name shown before the value, e.g. "Server uptime". */
  metricLabel: string
  value: number | string
  format?: NumberFormat
  currency?: string
  /** Gauge fill from 0 to 100. Defaults to value when value is a number. */
  progress?: number
  /** Any CSS color for the gauge. */
  color?: string
  /** Number of ticks in the gauge. 0 draws a continuous arc. */
  segments?: number
  /** Space between ticks in degrees. Larger gaps make thinner ticks. */
  segmentGap?: number
  /** Length of each tick in pixels. */
  thickness?: number
  /** Gauge diameter in pixels. */
  gaugeSize?: number
  /** Avatars shown under the metric. */
  people?: StatusGaugePerson[]
  /** Text next to the avatars, e.g. "6 reviewers". */
  peopleLabel?: string
  /** Header button. On narrow cards only the icon shows. */
  action?: {
    label: string
    href?: string
    onClick?: () => void
    icon?: React.ReactNode
  }
}

/** A status card with a headline word, a metric, an avatar stack, and a segmented gauge. */
function StatusGaugeCard({
  title,
  status,
  metricLabel,
  value,
  format = "percent",
  currency,
  progress,
  color = "var(--color-emerald-500)",
  segments = 40,
  segmentGap = 2.5,
  thickness = 14,
  gaugeSize = 200,
  people = [],
  peopleLabel,
  action,
  className,
  ...props
}: StatusGaugeCardProps) {
  const numeric = typeof value === "number"
  const gauge =
    progress ?? (numeric ? (format === "percent" ? value * 100 : value) : 0)

  return (
    <Card
      data-slot="status-gauge-card"
      className={cn("@container/card gap-0 py-0", className)}
      {...props}
    >
      <CardHeader className="flex items-center justify-between gap-3 border-b py-3 [.border-b]:pb-3">
        <CardTitle className="truncate text-sm">{title}</CardTitle>
        {action ? (
          <Button
            variant="outline"
            size="sm"
            asChild={Boolean(action.href)}
            onClick={action.onClick}
            className="shrink-0"
          >
            {action.href ? (
              <a href={action.href}>
                <span className="@max-xs/card:sr-only">{action.label}</span>
                <span className="@xs/card:hidden [&>svg]:size-4">
                  {action.icon ?? <ArrowUpRight />}
                </span>
              </a>
            ) : (
              <>
                <span className="@max-xs/card:sr-only">{action.label}</span>
                <span className="@xs/card:hidden [&>svg]:size-4">
                  {action.icon ?? <ArrowUpRight />}
                </span>
              </>
            )}
          </Button>
        ) : null}
      </CardHeader>
      <CardContent className="py-5">
        <div className="flex flex-col gap-6 @sm/card:flex-row @sm/card:items-end @sm/card:justify-between">
          <div className="flex min-w-0 flex-col gap-1">
            <span className="text-lg font-semibold">{status}</span>
            <span className="text-muted-foreground text-sm">
              {metricLabel}:{" "}
              <MetricValue
                value={value}
                format={format}
                currency={currency}
                className="text-foreground font-semibold"
              />
            </span>
            {people.length || peopleLabel ? (
              <div className="mt-4 flex items-center gap-2">
                {people.length ? (
                  <div
                    className="flex -space-x-2"
                    aria-label={people.map((p) => p.name).join(", ")}
                  >
                    {people.map((person) => (
                      <span
                        key={person.name}
                        title={person.name}
                        className="bg-muted ring-card text-muted-foreground flex size-7 items-center justify-center overflow-hidden rounded-full text-xs font-medium ring-2"
                      >
                        {person.src ? (
                          // eslint-disable-next-line @next/next/no-img-element
                          <img
                            src={person.src}
                            alt={person.name}
                            className="size-full object-cover"
                          />
                        ) : (
                          person.name.charAt(0).toUpperCase()
                        )}
                      </span>
                    ))}
                  </div>
                ) : null}
                {peopleLabel ? (
                  <span className="text-muted-foreground text-sm whitespace-nowrap">
                    {peopleLabel}
                  </span>
                ) : null}
              </div>
            ) : null}
          </div>
          <RadialGauge
            value={gauge}
            segments={segments}
            gap={segmentGap}
            size={gaugeSize}
            thickness={thickness}
            color={color}
            className="self-center @sm/card:self-end"
          />
        </div>
      </CardContent>
    </Card>
  )
}

export { StatusGaugeCard }
```

### components/ui/radial-gauge.tsx

```tsx
import * as React from "react"

import { cn } from "@/lib/utils"

export interface RadialGaugeProps extends React.ComponentProps<"div"> {
  value: number
  min?: number
  max?: number
  /** Diameter in pixels. */
  size?: number
  /** Stroke width in pixels. */
  thickness?: number
  /** Number of arc segments. 0 draws a continuous arc. */
  segments?: number
  /** Gap between segments in degrees. */
  gap?: number
  /** Angle where the arc starts, in degrees clockwise from 12 o'clock. */
  startAngle?: number
  /** Total sweep of the arc in degrees. 180 is a semicircle, 360 a ring. */
  sweep?: number
  /** Any CSS color. Defaults to chart-1. */
  color?: string
  trackColor?: string
  /** Content rendered in the middle of the gauge. */
  children?: React.ReactNode
}

// Round so server and client render identical path strings.
const round = (n: number) => Math.round(n * 1000) / 1000

function polar(cx: number, cy: number, r: number, angleDeg: number) {
  const rad = ((angleDeg - 90) * Math.PI) / 180
  return { x: round(cx + r * Math.cos(rad)), y: round(cy + r * Math.sin(rad)) }
}

function arcPath(cx: number, cy: number, r: number, from: number, to: number) {
  const start = polar(cx, cy, r, from)
  const end = polar(cx, cy, r, to)
  const largeArc = to - from > 180 ? 1 : 0
  return `M ${start.x} ${start.y} A ${r} ${r} 0 ${largeArc} 1 ${end.x} ${end.y}`
}

function RadialGauge({
  value,
  min = 0,
  max = 100,
  size = 160,
  thickness = 10,
  segments = 0,
  gap = 2,
  startAngle,
  sweep = 180,
  color = "var(--chart-1)",
  trackColor = "var(--muted)",
  className,
  children,
  ...props
}: RadialGaugeProps) {
  const fraction = Math.min(1, Math.max(0, (value - min) / (max - min || 1)))
  const start = startAngle ?? (sweep >= 360 ? 0 : -sweep / 2)
  const r = size / 2 - thickness / 2
  const cx = size / 2
  const cy = size / 2
  // Trim the box to the arc's vertical extent so a semicircle does not
  // reserve a full circle of space.
  const angles = Array.from({ length: 64 }, (_, i) => start + (sweep * i) / 63)
  const ys = angles.map((a) => polar(cx, cy, r, a).y)
  const top = Math.max(0, Math.min(...ys) - thickness / 2)
  const bottom = Math.min(size, Math.max(...ys) + thickness / 2)
  const height = bottom - top

  const arcs: { from: number; to: number; filled: boolean }[] = []
  if (segments > 0) {
    const step = sweep / segments
    for (let i = 0; i < segments; i++) {
      const from = start + i * step + gap / 2
      const to = start + (i + 1) * step - gap / 2
      const mid = (i + 0.5) / segments
      arcs.push({ from, to, filled: mid <= fraction })
    }
  }

  return (
    <div
      data-slot="radial-gauge"
      role="meter"
      aria-valuemin={min}
      aria-valuemax={max}
      aria-valuenow={value}
      className={cn("relative inline-flex shrink-0", className)}
      style={{ width: size, height }}
      {...props}
    >
      <svg
        width={size}
        height={height}
        viewBox={`0 ${top} ${size} ${height}`}
        className="absolute inset-0"
        aria-hidden="true"
      >
        {segments > 0 ? (
          arcs.map((arc, index) => (
            <path
              key={index}
              d={arcPath(cx, cy, r, arc.from, arc.to)}
              fill="none"
              stroke={arc.filled ? color : trackColor}
              strokeWidth={thickness}
              strokeLinecap="butt"
            />
          ))
        ) : (
          <>
            <path
              d={arcPath(cx, cy, r, start, start + sweep - (sweep >= 360 ? 0.01 : 0))}
              fill="none"
              stroke={trackColor}
              strokeWidth={thickness}
              strokeLinecap={sweep >= 360 ? "butt" : "round"}
            />
            {fraction > 0 ? (
              <path
                d={arcPath(cx, cy, r, start, start + sweep * fraction)}
                fill="none"
                stroke={color}
                strokeWidth={thickness}
                strokeLinecap="round"
                className="transition-[d] duration-500"
              />
            ) : null}
          </>
        )}
      </svg>
      {children ? (
        <div
          className={cn(
            "absolute inset-x-0 flex flex-col items-center justify-center text-center",
            sweep > 200 ? "inset-y-0" : "bottom-0"
          )}
        >
          {children}
        </div>
      ) : null}
    </div>
  )
}

export { RadialGauge }
```

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```

# Tick KPI Card

A card with a row of KPI tiles, each with a value out of a whole and a tick bar showing how far along it is.

A row of KPI tiles, each with a value out of a whole and a tick bar showing how far along it is. Suits capacity, budget consumed, and goals with a known ceiling.

## Installation

```bash
npx shadcn@latest add https://dashboardcn.com/r/tick-kpi-card.json
```

Also installs `card`, `tooltip` from shadcn/ui if missing.

## Usage

```tsx
import { TickKpiCard } from "@/components/tick-kpi-card"

<TickKpiCard
  metrics={[
    { icon: <FileText />, label: "Open invoices", value: 512, max: 691, color: "var(--color-emerald-500)" },
    { icon: <Package />, label: "Stock replenished", value: 7420, max: 12300, unit: "units", color: "var(--color-violet-500)" },
    { icon: <Landmark />, label: "Budget utilized", value: 103000, max: 2600000, format: "compact", color: "var(--color-amber-500)" },
  ]}
/>
```

## Examples

### Default

```tsx
import { EllipsisVertical, FileText, Landmark, Package } from "lucide-react"

import { Button } from "@/components/ui/button"
import { TickKpiCard } from "@/registry/dashboardcn/blocks/tick-kpi-card"

const menu = (
  <Button variant="ghost" size="icon-xs" className="text-muted-foreground -mr-1.5">
    <EllipsisVertical />
    <span className="sr-only">More</span>
  </Button>
)

export default function TickKpiCardDemo() {
  return (
    <TickKpiCard
      className="w-full"
      metrics={[
        { icon: <FileText />, label: "Open invoices", value: 512, max: 691, color: "var(--color-emerald-500)", action: menu },
        { icon: <Package />, label: "Stock replenished", value: 7_420, max: 12_300, unit: "units", color: "var(--color-violet-500)", action: menu },
        { icon: <Landmark />, label: "Budget utilized", value: 103_000, max: 2_600_000, format: "compact", color: "var(--color-amber-500)", action: menu },
      ]}
    />
  )
}
```

## Source

### components/tick-kpi-card.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { type NumberFormat } from "@/lib/format"
import { Card, CardContent } from "@/components/ui/card"
import { TickBar } from "@/components/ui/tick-bar"
import { MetricValue } from "@/components/ui/metric-value"

export interface TickKpiMetric {
  label: string
  value: number
  /** The whole the value is measured against, shown as "of 691". */
  max: number
  format?: NumberFormat
  currency?: string
  /** Suffix after the max, e.g. "units". */
  unit?: string
  /** Any CSS color. Defaults to chart-1 through chart-5 in order. */
  color?: string
  icon?: React.ReactNode
  /** Slot in the top-right corner, e.g. a menu button. */
  action?: React.ReactNode
}

export interface TickKpiCardProps extends React.ComponentProps<typeof Card> {
  metrics: TickKpiMetric[]
  /** Number of ticks in each bar. */
  segments?: number
}

const defaultColors = [
  "var(--chart-1)",
  "var(--chart-2)",
  "var(--chart-3)",
  "var(--chart-4)",
  "var(--chart-5)",
]

/** A card with a row of KPI tiles, each with a value out of a whole and a tick bar showing how far along it is. */
function TickKpiCard({ metrics, segments = 40, className, ...props }: TickKpiCardProps) {
  return (
    <Card
      data-slot="tick-kpi-card"
      className={cn("overflow-hidden py-0", className)}
      {...props}
    >
      <CardContent className="px-0">
        {/* Tiles wrap to fit and stretch to fill their row; the gap shows the border color as hairline dividers. */}
        <div className="bg-border flex flex-wrap gap-px">
          {metrics.map((metric, index) => {
            const color = metric.color ?? defaultColors[index % defaultColors.length]
            const options = { format: metric.format, currency: metric.currency }
            return (
              <div
                key={metric.label}
                data-slot="tick-kpi-metric"
                className="bg-card flex min-w-0 flex-[1_1_14rem] flex-col gap-4 p-5"
              >
                <div className="flex items-center gap-3">
                  {metric.icon ? (
                    <span className="bg-muted/50 flex size-9 shrink-0 items-center justify-center rounded-lg border [&>svg]:size-4">
                      {metric.icon}
                    </span>
                  ) : null}
                  <span className="min-w-0 flex-1 truncate text-sm font-medium">
                    {metric.label}
                  </span>
                  {metric.action ? <span className="shrink-0">{metric.action}</span> : null}
                </div>
                <div className="flex flex-wrap items-baseline gap-x-1.5">
                  <MetricValue
                    value={metric.value}
                    {...options}
                    className="text-2xl font-semibold tracking-tight"
                  />
                  <span className="text-muted-foreground text-sm tabular-nums">
                    of{" "}
                    <MetricValue
                      value={metric.max}
                      {...options}
                      suffix={metric.unit ? ` ${metric.unit}` : undefined}
                    />
                  </span>
                </div>
                <TickBar
                  value={metric.value}
                  max={metric.max}
                  segments={segments}
                  color={color}
                  className="h-5"
                />
              </div>
            )
          })}
        </div>
      </CardContent>
    </Card>
  )
}

export { TickKpiCard }
```

### components/ui/tick-bar.tsx

```tsx
import * as React from "react"

import { cn } from "@/lib/utils"

export interface TickBarProps extends React.ComponentProps<"div"> {
  /** Current value, from 0 to max. */
  value: number
  max?: number
  /** Number of ticks. */
  segments?: number
  /** Any CSS color for the filled ticks. Defaults to chart-1. */
  color?: string
  /** Any CSS color for the unfilled ticks. Defaults to muted. */
  trackColor?: string
  /** "tick" draws thin bars; "pill" draws wide rounded ones. */
  shape?: "tick" | "pill"
}

/** A progress bar drawn as a row of ticks, lit up to the current value. */
function TickBar({
  value,
  max = 100,
  segments = 40,
  color = "var(--chart-1)",
  trackColor,
  shape = "tick",
  className,
  ...props
}: TickBarProps) {
  const fraction = Math.min(1, Math.max(0, value / (max || 1)))
  // Any non-zero value lights at least one tick so small values still register.
  const filled = fraction === 0 ? 0 : Math.max(1, Math.round(fraction * segments))

  return (
    <div
      data-slot="tick-bar"
      data-shape={shape}
      role="progressbar"
      aria-valuemin={0}
      aria-valuemax={max}
      aria-valuenow={value}
      className={cn(
        "flex w-full",
        shape === "tick" ? "h-6 gap-[3px]" : "h-4 gap-1.5",
        className
      )}
      {...props}
    >
      {Array.from({ length: segments }, (_, index) => {
        const lit = index < filled
        return (
          <span
            key={index}
            data-filled={lit}
            className={cn(
              "bg-muted h-full min-w-0 flex-1 transition-colors",
              shape === "tick" ? "rounded-[1.5px]" : "rounded-full"
            )}
            style={{ backgroundColor: lit ? color : trackColor }}
          />
        )
      })}
    </div>
  )
}

export { TickBar }
```

### components/ui/metric-value.tsx

```tsx
"use client"

import * as React from "react"

import { cn } from "@/lib/utils"
import { formatNumber, type NumberFormat } from "@/lib/format"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

/** Values at or above this are abbreviated by default. */
export const DEFAULT_COMPACT_FROM = 100_000

export interface MetricValueProps extends Omit<React.ComponentProps<"span">, "children"> {
  /** Strings render as-is. */
  value: number | string
  format?: NumberFormat
  currency?: string
  maximumFractionDigits?: number
  /** Values at or above this are abbreviated (e.g. $158K) with the full value in a tooltip. Set to Infinity to always show the full value. */
  compactFrom?: number
  /** Text after the number, e.g. a unit. */
  suffix?: React.ReactNode
}

/** A formatted number. Large values are abbreviated and reveal the full value on hover. */
function MetricValue({
  value,
  format,
  currency,
  maximumFractionDigits,
  compactFrom = DEFAULT_COMPACT_FROM,
  suffix,
  className,
  ...props
}: MetricValueProps) {
  const classes = cn("tabular-nums", className)

  if (typeof value !== "number") {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {value}
        {suffix}
      </span>
    )
  }

  const full = formatNumber(value, { format, currency, maximumFractionDigits })
  const abbreviate = format !== "percent" && Math.abs(value) >= compactFrom
  if (!abbreviate) {
    return (
      <span data-slot="metric-value" className={classes} {...props}>
        {full}
        {suffix}
      </span>
    )
  }

  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span
            data-slot="metric-value"
            data-compact=""
            className={cn(classes, "cursor-default")}
            {...props}
          >
            {formatNumber(value, { format, currency, compact: true })}
            {suffix}
          </span>
        </TooltipTrigger>
        <TooltipContent className="tabular-nums">
          {full}
          {suffix}
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

export { MetricValue }
```

### lib/format.ts

```ts
export type NumberFormat = "number" | "compact" | "currency" | "percent"

export interface FormatNumberOptions {
  format?: NumberFormat
  /** ISO 4217 code, used when format is "currency". Defaults to USD. */
  currency?: string
  locale?: string
  maximumFractionDigits?: number
  /** Abbreviate large values, e.g. "$158K" instead of "$158,143". */
  compact?: boolean
}

const formatterCache = new Map<string, Intl.NumberFormat>()

function getFormatter(locale: string, options: Intl.NumberFormatOptions) {
  const key = locale + JSON.stringify(options)
  let formatter = formatterCache.get(key)
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options)
    formatterCache.set(key, formatter)
  }
  return formatter
}

/**
 * Format a metric value for display.
 *
 * formatNumber(1234567)                          -> "1,234,567"
 * formatNumber(1234567, { format: "compact" })   -> "1.2M"
 * formatNumber(48.2, { format: "currency" })     -> "$48.20"
 * formatNumber(158143, { format: "currency", compact: true }) -> "$158K"
 * formatNumber(0.124, { format: "percent" })     -> "12.4%"
 */
export function formatNumber(
  value: number,
  {
    format = "number",
    currency = "USD",
    locale = "en-US",
    maximumFractionDigits,
    compact = false,
  }: FormatNumberOptions = {}
): string {
  if (!Number.isFinite(value)) return "—"

  // Compact values keep three significant digits: $158K, $1.23M, 41.2K.
  const compactOptions: Intl.NumberFormatOptions = compact
    ? maximumFractionDigits === undefined
      ? { notation: "compact", maximumSignificantDigits: 3 }
      : { notation: "compact", maximumFractionDigits }
    : {}
  switch (format) {
    case "compact":
      return getFormatter(locale, {
        notation: "compact",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    case "currency":
      return getFormatter(locale, {
        style: "currency",
        currency,
        maximumFractionDigits: maximumFractionDigits ?? 2,
        ...compactOptions,
      }).format(value)
    case "percent":
      return getFormatter(locale, {
        style: "percent",
        maximumFractionDigits: maximumFractionDigits ?? 1,
      }).format(value)
    default:
      return getFormatter(locale, {
        maximumFractionDigits: maximumFractionDigits ?? 0,
        ...compactOptions,
      }).format(value)
  }
}

/**
 * Format a fractional change as a signed percentage.
 *
 * formatDelta(0.124)  -> "+12.4%"
 * formatDelta(-0.03)  -> "-3.0%"
 * formatDelta(0)      -> "0.0%"
 */
export function formatDelta(delta: number, locale = "en-US"): string {
  if (!Number.isFinite(delta)) return "—"
  return getFormatter(locale, {
    style: "percent",
    signDisplay: "exceptZero",
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
  }).format(delta)
}

/**
 * Fractional change between two values. Returns 0 when there is no baseline.
 */
export function computeDelta(current: number, previous: number): number {
  if (!previous) return 0
  return (current - previous) / Math.abs(previous)
}
```