KPI Dashboard React block for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

KPI Dashboard is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import KpiDashboard from @/components/ui/kpi-dashboard.

import { useState } from "react"
import { KpiDashboard, KPI_DASHBOARD_SAMPLE } from "@/components/ui/kpi-dashboard"
import type { DateRange } from "@/lib/date-utils"

export function SalesDashboard() {
  const [period, setPeriod] = useState<DateRange>({ from: new Date(2026, 8, 1), to: new Date(2026, 8, 30) })
  return (
    <KpiDashboard
      title="Dashboard"
      description="Northwind Software Inc. · Portland"
      data={KPI_DASHBOARD_SAMPLE}
      period={period}
      onPeriodChange={setPeriod}
      onRefresh={() => fetch("/api/dashboard")}
      onExport={(format) => window.open(`/api/dashboard/export?format=${format}`)}
      widgetLinks={{ invoices: "/invoices", activity: "/activity" }}
      locale="en-US"
      labels={{ invoices: "Recent invoices", viewAll: "See all" }}
    />
  )
}

Props

• datadefault "KPI_DASHBOARD_SAMPLE"
  KpiDashboardData

  { kpis: KpiItem[]; revenue?: { date, value, previous? }[]; revenueBy?: { label, value }[]; sources?: { label, value, color? }[]; funnel?: { label, value }[]; leaderboard?: { id, name, avatar?, value, change? }[]; invoices?: { id, number, client, amount, issuedAt, dueAt, status, href? }[]; activity?: TimelineItemData[] }. KpiItem: { id, label, value (null shows a dash), format?, delta?, deltaFormat? (percent, number, currency, points), invertTrend?, sparkline?, sparklineType?, icon?, iconTone? (the icon tile tint), href?, goal?, info? }. A widget whose data is missing is hidden; an empty array shows its empty state. The sample (Northwind CRM, September 2026) is pinned to 2026-09-24 4:40 PM.

• titledefault "Dashboard"
  ReactNode

  The page's one <h1>: 22px on phones, 24px from 768px.

• descriptiondefault ""
  ReactNode

  A line under the title (the company, the team, a greeting).

• revenueByLabeldefault ""
  string

  The bar chart's title. Empty uses labels.revenueBy ("Revenue by month"); set "Revenue by city" when the bars are cities.

• layoutdefault "comfortable"
  "comfortable" | "compact"

  comfortable: 24px gaps (16px on phones), md KPI cards and 280px charts. compact: 16px gaps, one joined panel of sm KPI tiles and 240px charts.

• kpiColumnsdefault 0
  number

  KPI tiles per row on wide dashboards (at most 2 on phones and 3 from 576px). 0 is auto: 2, then 3, then every tile in one row (up to 5) from 1024px. The last row always fills its width.

• revenueByOrientationdefault "vertical"
  "vertical" | "horizontal"

  vertical columns with the latest one highlighted (months), or horizontal bars for long labels (cities, products).

• activityLimitdefault 5
  number

  Activity items shown before View all. 0 shows every item.

• variantdefault "surface"
  "surface" | "card" | "outline"

  The surface of every widget and KPI tile: raised panels (surface), flat gray tiles (card) or hairline outlines on the page (outline).

• radiusdefault "md"
  "none" | "sm" | "md" | "lg"

  Corners of the widgets and KPI tiles: 0, 12, 16 or 24px.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The accent of the single-series marks: the revenue line and its area, the bars, the funnel, the salespeople's bars, the KPI icons and sparklines. Status colors (paid, overdue, deltas) keep their meaning.

• colordefault ""
  string

  Any CSS color for the same marks; replaces the tone.

• currencydefault "USD"
  string

  ISO 4217 code for every amount. The block formats, it never converts: USD data with EUR prints euros.

• localedefault ""
  string

  Intl locale for numbers, money and dates (en-US: $248,300, 10/24/2026). Empty uses the UIProvider's, then the browser's.

• defaultComparePreviousdefault true
  boolean

  Starts with the previous period on: the dashed series, the KPI deltas and the salespeople's changes. comparePrevious / onComparePreviousChange control it.

• loadingdefault false
  boolean

  Every KPI tile and widget in its skeleton (charts, rows, table, feed); the period picker and the switch stay usable.

• animateddefault true
  boolean

  Values count up and charts draw in once, on first view. Reduced motion turns both off on its own.

• animateIndefault false
  boolean

  Widgets stagger in (40ms apart) when the dashboard mounts on the client. Server HTML and hydration show the final state.

• refreshShortcutdefault ""
  string

  A key combo for refresh ("shift+r", "mod+shift+r"), shown in the button's tooltip and the ⋯ menu. Empty binds nothing.

• period
  DateRange

  The period on screen, { from, to } (controlled). The data is the app's job: the block shows the period and hands changes back.

• defaultPeriod
  DateRange

  The starting period while uncontrolled. Default: this month of now.

• onPeriodChange
  (period: DateRange) => void

  A preset or a range was applied.

• comparePrevious
  boolean

  Controlled compare switch.

• onComparePreviousChange
  (compare: boolean) => void

  The compare switch changed.

• widgets
  ("revenue" | "revenueBy" | "sources" | "funnel" | "leaderboard" | "invoices" | "activity")[]

  Which widgets show and in what order (DOM order is the phone order). Default: all, in this order, each hidden when its data is missing; a widget listed here shows its empty state instead.

• onRefresh
  () => (void | Promise<unknown>)

  Shows the refresh button. A returned promise spins it, shows a bar under the header and announces the time when it settles (or labels.refreshError when it rejects).

• onExport
  (format: "csv" | "pdf") => void

  Shows the Export menu. Exporting is the app's job (the block does not import spreadsheet).

• widgetErrors
  Partial<Record<KpiDashboardWidgetId, ReactNode>>

  An error state with a Try again button in place of a widget's content (true uses the default message).

• onWidgetRetry
  (widget: KpiDashboardWidgetId) => (void | Promise<unknown>)

  Try again in a widget's error state; a returned promise spins the button.

• widgetLinks
  Partial<Record<KpiDashboardWidgetId, string>>

  A View all link at the end of a widget's header (the invoices page, the activity log).

• widgetDescriptions
  Partial<Record<KpiDashboardWidgetId, ReactNode>>

  A line under a widget's title.

• widgetActions
  (widget: KpiDashboardWidgetId) => (MenuEntry[] | undefined)

  Menu entries for a widget's ⋯ button, labelled "More actions for <title>"; a bottom sheet on phones.

• linkComponent
  (props: LinkComponentProps) => ReactNode

  Renders View all links and invoice links through your router (default: the LinkProvider's, else <a>).

• now
  Date | number

  The moment the default period and the relative activity times are measured from. Default: the current time (useNow), or 24.09.2026 16:40 for the sample.

• labels
  Partial<KpiDashboardLabels>

  Every string: period, presets { today, last7Days, thisMonth, lastMonth, thisQuarter, thisYear }, compare, refresh, refreshing, updated(time), refreshError, export, exportCsv, exportPdf, more, moreFor(title), kpis, vsPrevious, points(value), revenue, current, previous, revenueBy, sources, total, funnel, leaderboard, invoices, activity, viewAll, statuses { paid, unpaid, overdue, draft }, number, client, status, amount, due, empty, error, retry. English defaults in DEFAULT_KPI_DASHBOARD_LABELS.

• classNames
  Partial<Record<"content" | "header" | "title" | "description" | "status" | "controls" | "period" | "compare" | "actions" | "progress" | "kpis" | "kpi" | "grid" | "widget" | KpiDashboardWidgetId, string>>

  Extra classes for the parts. Each widget's content wrapper takes its id's key.

Parts

FAQ

More React blocks