Application UIAnalytic

Metrics Card

A composable metrics card component for displaying analytics data with charts, values, and trends.

Features

Radix component architecture for maximum composability
Multiple aggregation methods (sum, average, last, first, min, max)
Advanced value formatting (number, currency, percentage, compact)
Built-in chart visualization with Recharts
Automatic trend calculation with visual indicators
Two layout variants (default and wide-chart)
Locale-aware number formatting
Fully customizable styling

Installation

Install the following dependencies:


pnpm add recharts class-variance-authority

Make sure that the following shadcn/ui components are present in your project:

Copy and paste the following code into your project.

Update the import paths to match your project setup.

Usage

Anatomy

import {
  MetricsCard,
  MetricsCardHeader,
  MetricsCardTitle,
  MetricsCardDescription,
  MetricsCardAction,
  MetricsCardContent,
  MetricsCardValue,
  MetricsCardChart,
  MetricsCardChange,
} from '@kit/content-type/analytics/metrics-card';

Basic Example


<MetricsCard
  data={[
    { date: '2024-01', revenue: 1200 },
    { date: '2024-02', revenue: 1800 },
    { date: '2024-03', revenue: 2400 },
  ]}
  dataKey="revenue"
>
  <MetricsCardHeader icon={Icon.dollarSign}>
    <MetricsCardTitle>Total Revenue</MetricsCardTitle>
  </MetricsCardHeader>
  <MetricsCardContent>
    <div className="text-3xl font-bold">
      <MetricsCardValue format="currency" currency="USD" decimals={2} />
    </div>
    <MetricsCardChange />
  </MetricsCardContent>
</MetricsCard>

With Chart


<MetricsCard
  data={[
    { date: '2024-01', users: 150 },
    { date: '2024-02', users: 230 },
    { date: '2024-03', users: 340 },
    { date: '2024-04', users: 420 },
  ]}
  dataKey="users"
>
  <MetricsCardHeader icon={Icon.users}>
    <MetricsCardTitle>Active Users</MetricsCardTitle>
    <MetricsCardAction tooltipInfo="Total number of active users" />
  </MetricsCardHeader>
  <MetricsCardContent>
    <div className="text-3xl font-bold">
      <MetricsCardValue method="last" />
    </div>
    <div className="flex items-center justify-between">
      <MetricsCardChange />
      <MetricsCardChart
        height={39}
        color="#3b82f6"
        config={{
          users: { label: 'Users', color: '#3b82f6' },
        }}
      />
    </div>
  </MetricsCardContent>
</MetricsCard>

Wide Chart Variant


<MetricsCard
  data={data}
  dataKey="sales"
  variant="wide-chart"
>
  <MetricsCardHeader icon={Icon.trendingUp}>
    <MetricsCardTitle>Sales Overview</MetricsCardTitle>
  </MetricsCardHeader>
  <MetricsCardContent>
    <div className="flex items-center justify-between mb-4">
      <div className="text-3xl font-bold">
        <MetricsCardValue format="currency" currency="EUR" />
      </div>
      <MetricsCardChange />
    </div>
    <MetricsCardChart
      height={120}
      color="#10b981"
      config={{
        sales: { label: 'Sales', color: '#10b981' },
      }}
    />
  </MetricsCardContent>
</MetricsCard>

Component Architecture

The MetricsCard follows the Radix component pattern, providing a composable API through context:

MetricsCard: Root component that provides context (data, dataKey, variant)
MetricsCardHeader: Container for title and actions
MetricsCardTitle: Display the metric title
MetricsCardDescription: Optional description text
MetricsCardAction: Info tooltip icon
MetricsCardContent: Main content container with variant-based styling
MetricsCardValue: Displays aggregated and formatted values
MetricsCardChart: Renders a line chart visualization
MetricsCardChange: Shows percentage change with trend indicators

Aggregation Methods

The MetricsCardValue component supports multiple aggregation methods via the method prop:

Method	Description	Use Case
`sum`	Sum of all values	Total revenue, total orders
`average`	Average of all values	Average order value, avg. rating
`last`	Last value in dataset	Current active users, latest price
`first`	First value in dataset	Starting value, baseline
`min`	Minimum value	Lowest price, min. stock
`max`	Maximum value	Peak traffic, max. capacity

// Sum all values (default)
<MetricsCardValue method="sum" />
 
// Show average
<MetricsCardValue method="average" decimals={2} />
 
// Display last value
<MetricsCardValue method="last" />

Value Formatting

The MetricsCardValue component provides comprehensive formatting options:

Format Types

Format	Description	Example Output
`number`	Standard number with separators	`1 234 567`
`currency`	Locale-aware currency	`$1,234.56`
`percentage`	Percentage format	`45.67%`
`compact`	Compact notation	`1.2M`, `3.4K`
`custom`	Simple decimal	`1234.56`

Number Format

// Default: space separator
<MetricsCardValue format="number" />
// Output: 1 234 567
 
// Comma separator
<MetricsCardValue format="number" separator="," />
// Output: 1,234,567
 
// With decimals
<MetricsCardValue format="number" decimals={2} />
// Output: 1 234 567.89

Currency Format


// USD (default)
<MetricsCardValue format="currency" currency="USD" decimals={2} />
// Output: $1,234.56
 
// Euro with French locale
<MetricsCardValue
  format="currency"
  currency="EUR"
  locale="fr-FR"
  decimals={2}
/>
// Output: 1 234,56 €
 
// British Pound
<MetricsCardValue format="currency" currency="GBP" decimals={2} />
// Output: £1,234.56

Percentage Format

// Assumes data contains decimal values (0.4567 becomes 45.67%)
<MetricsCardValue format="percentage" decimals={2} />
// Output: 45.67%

Compact Format

// Ideal for large numbers
<MetricsCardValue format="compact" decimals={1} />
// 1234567 → 1.2M
// 1234 → 1.2K
// 1234567890 → 1.2B

Custom Formatting

// Prefix and suffix
<MetricsCardValue prefix="~" suffix=" units" />
// Output: ~1234 units
 
// Custom formatter function
<MetricsCardValue
  formatter={(value) => `${value.toLocaleString()} items sold`}
/>
// Output: 1,234 items sold
 
// Custom value override
<MetricsCardValue customValue={42} format="number" />
// Output: 42

Chart Configuration

The MetricsCardChart component uses Recharts and shadcn/ui Chart:

<MetricsCardChart
  height={39}              // Chart height in pixels
  color="#3b82f6"          // Line color
  config={{                // Chart configuration
    revenue: {
      label: 'Revenue',
      color: '#3b82f6',
    },
  }}
/>

Chart Features

Automatic scaling with 10% padding
Hidden axes for clean appearance
Linear interpolation
Responsive width
Gradient support (built-in)
Accessibility layer enabled

Trend Indicators

The MetricsCardChange component automatically calculates percentage change between the last two data points:

<MetricsCardChange />

Features:

Automatic color coding (green for increase, red for decrease)
Trend icons (↑ for increase, ↓ for decrease)
Percentage calculation
Handles edge cases (division by zero, insufficient data)
Variant-aware text sizing

Variants

Default Variant

Optimized for compact metric displays with optional small charts:

<MetricsCard data={data} dataKey="value" variant="default">
  {/* Content uses flexbox layout with vertical justification */}
</MetricsCard>

Wide Chart Variant

Better for prominent chart visualizations:

<MetricsCard data={data} dataKey="value" variant="wide-chart">
  {/* Content uses standard layout for larger charts */}
</MetricsCard>

Examples

E-commerce Revenue Card


<MetricsCard
  data={revenueData}
  dataKey="revenue"
>
  <MetricsCardHeader icon={Icon.dollarSign}>
    <MetricsCardTitle>Monthly Revenue</MetricsCardTitle>
    <MetricsCardAction tooltipInfo="Total revenue for the current month" />
  </MetricsCardHeader>
  <MetricsCardContent>
    <div className="text-3xl font-bold">
      <MetricsCardValue
        method="sum"
        format="currency"
        currency="USD"
        decimals={2}
      />
    </div>
    <div className="flex items-center justify-between">
      <MetricsCardChange />
      <MetricsCardChart
        height={39}
        color="#10b981"
        config={{
          revenue: { label: 'Revenue', color: '#10b981' },
        }}
      />
    </div>
  </MetricsCardContent>
</MetricsCard>

User Growth Percentage


<MetricsCard
  data={growthData}
  dataKey="growthRate"
>
  <MetricsCardHeader icon={Icon.trendingUp}>
    <MetricsCardTitle>Growth Rate</MetricsCardTitle>
  </MetricsCardHeader>
  <MetricsCardContent>
    <div className="text-3xl font-bold text-emerald-600">
      <MetricsCardValue
        method="average"
        format="percentage"
        decimals={1}
      />
    </div>
    <MetricsCardChange />
  </MetricsCardContent>
</MetricsCard>

Conversion Rate with Description


<MetricsCard
  data={conversionData}
  dataKey="rate"
>
  <MetricsCardHeader icon={Icon.target}>
    <div>
      <MetricsCardTitle>Conversion Rate</MetricsCardTitle>
      <MetricsCardDescription>
        Last 30 days
      </MetricsCardDescription>
    </div>
  </MetricsCardHeader>
  <MetricsCardContent>
    <div className="text-3xl font-bold">
      <MetricsCardValue
        method="average"
        format="percentage"
        decimals={2}
      />
    </div>
    <MetricsCardChange />
  </MetricsCardContent>
</MetricsCard>

API Reference

Prop	Type	Default
`className`	`string`
`data*`	`Record<string, any>[]`
`dataKey*`	`string`
`variant`	`"default" \| "wide-chart"`
`children`	`React.ReactNode`

Prop	Type	Default
`className`	`string`
`children`	`React.ReactNode`

Prop	Type	Default
`className`	`string`
`icon`	`React.ComponentType<React.SVGAttributes<SVGSVGElement>...`
`children*`	`React.ReactNode`

Prop	Type	Default
`className`	`string`
`children*`	`React.ReactNode`

Prop	Type	Default
`tooltipInfo*`	`string`
`className`	`string`

Prop	Type	Default
`className`	`string`
`children`	`React.ReactNode`

Prop	Type	Default
`method`	`ProjectionMethod`
`customValue`	`number`
`className`	`string`
`decimals`	`number`
`format`	`FormatType`
`locale`	`string`
`currency`	`string`
`showCurrency`	`boolean`
`separator`	`string`
`prefix`	`string`
`suffix`	`string`
`formatter`	`function`

Prop	Type	Default
`height`	`number`
`className`	`string`
`config*`	`ChartConfig`
`color`	`string`

Prop	Type	Default
`className`	`string`

Deployment

Implement your own documentation website with Fumadocs.

Content Table

A content table component to display a table of content.

How is this guide?

Last updated on 11/7/2025