# Semicircular Metric Needle Dial Gauge

> Arc dial gauge featuring colored risk zones and animated needle pointer.

A shadcn/ui block from the [@pacekit](https://ui.pacekit.dev/?utm_source=shadcn.exchange) registry, listed on [shadcn.exchange](https://shadcn.exchange/r/pacekit/tanstack-charts-needle-gauge).

- Page, with a live preview: https://shadcn.exchange/r/pacekit/tanstack-charts-needle-gauge
- Screenshot: https://abzjhwgwpdpz7ua5.public.blob.vercel-storage.com/shots/pacekit/tanstack-charts-needle-gauge-light-bcd3d3d7ef497b73.png
- Registry item: https://ui.pacekit.dev/r/tanstack-charts-needle-gauge.json
- Listed: 2026-10-21, source last changed 2026-10-21

## Install

```bash
npx shadcn@latest add https://shadcn.exchange/r/pacekit/tanstack-charts-needle-gauge.json
```

Run it in a project that has shadcn/ui set up. It adds the files below and installs what they depend on.

## Dependencies

- npm packages: `@tanstack/charts`, `@tanstack/react-charts`, `d3-scale`
- Registry items: `card`

## Files

### `components/tanstack-charts/pie/needle-gauge.tsx`

```tsx
import { type ChartPoint, defineChart } from "@tanstack/charts";
import { motion } from "@tanstack/charts/motion";
import { pie, polar, radialArc, radialDot, radialRule, radialText } from "@tanstack/charts/polar";
import { tooltip } from "@tanstack/charts/tooltip";
import { Chart } from "@tanstack/react-charts/core";
import { useMemo } from "react";

import { scaleLinear } from "d3-scale";
import { Gauge } from "lucide-react";

import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "@/components/ui/card";

interface GaugeBand {
    id: string;
    label: string;
    value: number;
}

const motionRenderer = motion({
    initial: "always",
    transition: { type: "spring", stiffness: 170, damping: 18, mass: 1 },
});

const startAngle = -Math.PI / 2;
const endAngle = Math.PI / 2;
const gaugeMaximum = 100;

const gaugeBands: GaugeBand[] = [
    { id: "low", label: "Normal (0-50%)", value: 50 },
    { id: "elevated", label: "Warning (50-80%)", value: 30 },
    { id: "high", label: "Critical (80-100%)", value: 20 },
];

const bandIds = ["low", "elevated", "high"];
const bandColors = ["var(--chart-1)", "var(--chart-2)", "var(--chart-3)"];

function shadcnTooltipContent<TDatum>(points: readonly ChartPoint<TDatum>[]) {
    if (points.length === 0) return { title: "", rows: [] };
    const d = points[0].datum as { label?: string; rate?: number };
    if (!d) return { title: "", rows: [] };
    return {
        title: d.label || "System Performance Load",
        rows: [
            {
                label: "Gauge Value",
                value: d.rate !== undefined ? `${d.rate}%` : "Zone Range",
                color: "var(--chart-1)",
            },
        ],
    };
}

export function NeedleGauge() {
    const currentReading = useMemo(() => ({ id: "reading", rate: 68, label: "Server CPU Load" }), []);

    const definition = useMemo(() => {
        const angleScale = scaleLinear().domain([0, gaugeMaximum]);
        const radiusScale = scaleLinear().domain([0, 1]);

        const arcs = pie(gaugeBands, {
            value: "value",
            startAngle,
            endAngle,
        });

        const ticks = [
            { id: "t1", value: 25 },
            { id: "t2", value: 50 },
            { id: "t3", value: 75 },
        ];

        return defineChart(
            {
                renderer: motionRenderer,
                scales: {
                    x: null,
                    y: null,
                },
                marks: [
                    polar({
                        scales: {
                            angle: { scale: angleScale },
                            radius: { scale: radiusScale },
                        },
                        startAngle,
                        endAngle,
                        radiusRatio: 0.85,
                        marks: [
                            radialArc(arcs, {
                                id: "gauge-bands",
                                key: "id",
                                innerRadius: ({ radius }) => radius * 0.72,
                                color: "id",
                            }),
                            radialRule(ticks, {
                                id: "gauge-ticks",
                                key: "id",
                                angle: "value",
                                radius1: 0.74,
                                radius2: 0.94,
                                stroke: "var(--background)",
                                strokeOpacity: 0.85,
                                strokeWidth: 2,
                            }),
                            radialRule([currentReading], {
                                id: "gauge-needle",
                                key: "id",
                                angle: "rate",
                                radius1: 0,
                                radius2: 0.64,
                                stroke: "var(--foreground)",
                                strokeWidth: 3.5,
                            }),
                            radialDot([currentReading], {
                                id: "gauge-hub",
                                key: "id",
                                angle: "rate",
                                radius: 0,
                                r: 7,
                                fill: "var(--foreground)",
                            }),
                            radialText([currentReading], {
                                id: "gauge-value",
                                key: "id",
                                angle: "rate",
                                radius: 0,
                                text: (row) => `${row.rate}%`,
                                dy: 32,
                                anchor: "middle",
                                baseline: "middle",
                                fill: "var(--foreground)",
                                fontSize: 20,
                                fontWeight: 700,
                            }),
                        ],
                    }),
                ],
                color: { domain: bandIds, range: bandColors },
                margin: { top: 20, right: 20, bottom: 20, left: 20 },
                theme: {
                    foreground: "var(--muted-foreground)",
                    grid: "var(--border)",
                    background: "transparent",
                },
            },
            {
                keyboard: true,
                tooltip: {
                    use: tooltip,
                    className: "font-sans shadow-none rounded-md bg-popover text-popover-foreground border p-2 text-xs",
                    anchor: "pointer",
                    placement: "auto",
                    content: (points) => shadcnTooltipContent(points),
                },
            },
        );
    }, [currentReading]);

    return (
        <Card className="w-full max-w-xl">
            <CardHeader>
                <CardTitle>Semicircular Metric Needle Dial Gauge</CardTitle>
                <CardDescription>
                    Arc dial gauge featuring colored risk thresholds, center hub, and rotating needle pointer
                </CardDescription>
            </CardHeader>
            <CardContent>
                <div className="h-[220px] w-full">
                    <Chart
                        definition={definition}
                        renderer={motionRenderer}
                        height={220}
                        ariaLabel="Semicircular Metric Needle Dial Gauge Chart"
                    />
                </div>
            </CardContent>
            <CardFooter className="flex-col items-start gap-2 text-sm">
                <div className="flex items-center gap-2 leading-none font-medium">
                    Current CPU Load reading pinned at {currentReading.rate}%{" "}
                    <Gauge className="h-4 w-4 text-emerald-500" />
                </div>
                <div className="text-muted-foreground leading-none">
                    `radialRule` combined with `radialDot` renders centered angular needle arms
                </div>
            </CardFooter>
        </Card>
    );
}

export default NeedleGauge;
```