KPI Dashboard Grid React component
A dashboard overview grid: a large featured chart and KPI cards with counting numbers, change against the previous period (inverse for metrics like churn), hoverable sparklines or goal bars, a period switch, a compare toggle with dashed previous lines, and a Customize menu to show or hide metrics.
About the KPI Dashboard Grid component
KPI Dashboard Grid is the first screen of an analytics or admin dashboard. One featured metric gets a large chart, and the others sit around it as compact cards, each with its number, how much it changed since the previous period and either a small trend line or progress towards a goal.
Switch between 7 days, 30 days, 90 days and 12 months and every number counts to its new value while the charts reshape. Turn on Compare to draw the previous period as a dashed line, hover any chart for exact values, and use Customize to hide the metrics you do not care about.
When to use it
Use it at the top of a SaaS, e-commerce or marketing dashboard, an internal reporting page or a client portal.
Pick one metric that matters most as the featured chart and keep the grid to six metrics or fewer.
Installation
Add the KPI Dashboard Grid component to your project with the shadcn CLI. It lands in components/kpi-dashboard-grid.tsx as plain React + Tailwind CSS source you own and can edit.
npx shadcn@latest add @reactframe/kpi-dashboard-gridOr copy the source by hand and install its dependencies:
npm install motion clsx tailwind-mergeProps
<KpiDashboardGrid /> accepts 7 props, all optional.
| Prop | Type | Default |
|---|---|---|
| title | string | "Overview" |
| kpis | Kpi[] | DEFAULT_KPIS |
| periods | { id: string; label: string; points: number; step: "day" | "week" | "month" }[] | DEFAULT_PERIODS |
| endDate Last day of the data as YYYY-MM-DD. | string | "2026-11-01" |
| currency | string | "$" |
| theme | "dark" | "light" | "dark" |
| className | string | — |
- titlestringDefault: "Overview"
- kpisKpi[]Default: DEFAULT_KPIS
- periods{ id: string; label: string; points: number; step: "day" | "week" | "month" }[]Default: DEFAULT_PERIODS
- endDate
Last day of the data as YYYY-MM-DD.
stringDefault: "2026-11-01" - currencystringDefault: "$"
- theme"dark" | "light"Default: "dark"
- classNamestring
npm dependencies
Installed for you by the shadcn CLI.
KPI Dashboard Grid FAQ
- What shape does the data need?
- Each KPI has series keyed by period id, with values from oldest to newest. Add previous with the same shape to get the change percentage and the dashed comparison line.
- How is the headline number worked out?
- Currency and count metrics add up the period's values; percentage metrics use the latest value. The change compares that number with the same calculation on the previous period.
- Why is churn green when it goes down?
- Set inverse: true on metrics where lower is better, such as churn, refunds or response time. The arrow still shows the direction, but the colour shows whether it is good.
- When does a card show a goal bar instead of a chart?
- When the KPI has a target. The bar shows the latest value against the target with 'x% of goal' underneath.
- Is it accessible?
- Charts have a text summary from first to last value, change pills say up or down in screen-reader text, goal bars are progressbars, the period switch is a radiogroup, Compare is a switch and the Customize menu uses real checkboxes.
