KPI Card

Overview

The KPI Card component provides a standardized way to display metrics and KPIs across ActiveCampaign's applications. It supports multiple metric formats, comparison indicators, secondary metrics, and interactive states to create comprehensive data visualization experiences.

Resources

Changelog

Source code

Storybook

Figma

Install

yarn add @camp/kpi-card

Props

Prop	Type	Default	Description
`metric` *	`number`	—	Primary metric
`metricFormat` *	`"currency" \| "integer" \| "percent" \| "float"`	—	How to format the primary metric number
`actionable`	`boolean`	—	When true, `children` will be rendered within the card (for use when including a clickable CTA)
`children`	`ReactNode`	—	Children can be rendered when `actionable=true` (for use when including a clickable CTA)
`compareMetric`	`number`	—	The metric that is being compared with the primary metric
`currency`	`string`	—	Possible values are the [ISO 4217 currency codes](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)
`customSecondaryMetric`	`ReactNode`	—	Provide a custom secondary metric row (will override any values passed for `secondaryMetric` and `variant`)
`hideCompare`	`boolean`	—	When true, the compare metric row is hidden
`isLoading`	`boolean`	—
`locale`	`string`	`en`	Unicode locale identifier string
`secondaryMetric`	`number`	—	Secondary metric number, displayed below the primary metric (must also include a value for `variant`)
`sentimentIsInverted`	`boolean`	`false`	When true, the sentiment color is reversed from the default behavior (By default, `compareMetric > metric` has a positive sentiment and `compareMetric < metric` has a negative sentiment) (does not affect direction of delta)
`size`	`"small" \| "medium"`	`medium`	Size of the KPI card
`themed`	`boolean`	—	When true, the component responds to the ambient theme context (light/dark)
`titleTooltip`	`string`	—	Adds a simple text tooltip to appear when the user hovers the card title (content heavy not available)
`variant`	`string`	—	Used to display the type of secondary metric; this currently maps to a partial translation key from our translations package: `reports:campaigns:[VARIANT]-count`

Generated from @camp/kpi-card@1.9.0 source, ordered by production usage. * required. † standard HTML attribute — all native attributes are supported; only those with production usage are listed.

Variations

Size

The KPI Card comes in two sizes to accommodate different layout needs and information density.

Medium size (Default)

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard title="Total Revenue" metric={12345} metricFormat="integer" />;

Small size

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard title="Total Revenue" metric={12345} metricFormat="integer" size="small" />;

Metric formatting

The component supports various metric formats to display different types of data appropriately.

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard title="Total Users" metric={1234567} metricFormat="integer" />;

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard title="Average Score" metric={95.67} metricFormat="float" />;

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard title="Conversion Rate" metric={15.5} metricFormat="percent" />;

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard title="Total Revenue" metric={12345.67} metricFormat="currency" currency="USD" />;

Comparison metric

Display trend indicators by comparing current metrics with previous values.

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard
  title="Monthly Revenue"
  metric={15000}
  compareMetric={12000}
  metricFormat="currency"
  currency="USD"
/>;

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard
  title="Monthly Revenue"
  metric={10000}
  compareMetric={12000}
  metricFormat="currency"
  currency="USD"
/>;

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard
  title="Monthly Revenue"
  metric={12000}
  compareMetric={12000}
  metricFormat="currency"
  currency="USD"
/>;

Secondary metric

Add contextual information with secondary metrics that provide additional context to the primary metric.

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard
  title="Campaign Performance"
  metric={15000}
  metricFormat="currency"
  currency="USD"
  secondaryMetric={25}
  variant="contact"
  locale="en"
/>;

Loading state

Show loading indicators while data is being fetched or processed.

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard title="Loading Metric" metric={12345} metricFormat="integer" isLoading={true} />;

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard
  title="Loading Metric"
  metric={12345}
  compareMetric={10000}
  metricFormat="integer"
  isLoading={true}
/>;

Provide additional context and information through tooltips on the title.

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard
  title="Hover for details"
  metric={12345}
  metricFormat="integer"
  titleTooltip="This metric shows the total number of active users in the system"
/>;

Display full formatted values in tooltips when metrics are abbreviated for display.

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard title="Large Number Metric" metric={123456789} metricFormat="integer" />;

Locale

Support different locales for proper number and currency formatting.

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard
  title="Deutsche Metrik"
  metric={12345.67}
  metricFormat="currency"
  currency="EUR"
  locale="de-DE"
/>;

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard
  title="Métrique Française"
  metric={12345.67}
  metricFormat="currency"
  currency="EUR"
  locale="fr-FR"
/>;

Container width

The KpiContainer adapts to different container widths and can be used within responsive layouts.

import { KpiCard, KpiContainer } from '@camp/kpi-card';
 
<div style={{ width: '450px' }}>
  <KpiContainer count={3}>
    <KpiCard title="Total Revenue" metric={12345} metricFormat="integer" />
    <KpiCard title="Total Users" metric={5678} metricFormat="integer" />
    <KpiCard title="Conversion Rate" metric={15.5} metricFormat="percent" />
  </KpiContainer>
</div>;

import { KpiCard, KpiContainer } from '@camp/kpi-card';
 
<div style={{ width: '1000px' }}>
  <KpiContainer count={6}>
    <KpiCard title="Total Revenue" metric={12345} metricFormat="integer" />
    <KpiCard title="Total Users" metric={5678} metricFormat="integer" />
    <KpiCard title="Conversion Rate" metric={15.5} metricFormat="percent" />
    <KpiCard title="Average Score" metric={95.67} metricFormat="float" />
    <KpiCard title="Monthly Revenue" metric={15000} metricFormat="currency" currency="USD" />
    <KpiCard title="Error Rate" metric={5} metricFormat="percent" />
  </KpiContainer>
</div>;

Production Examples

More states from @camp/kpi-card's visual test stories, ranked by production usage. Variations already documented above are not repeated here.

Metric Format Currency EUR

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard
  title="Total Revenue"
  metric={12345.67}
  metricFormat="currency"
  currency="EUR"
/>

Comparison Metric Hidden

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard
  title="Monthly Revenue"
  metric={15000}
  compareMetric={12000}
  metricFormat="currency"
  currency="USD"
  hideCompare
/>

Sentiment Inverted Positive

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard
  title="Error Rate"
  metric={5}
  compareMetric={10}
  metricFormat="percent"
  sentimentIsInverted
/>

Sentiment Inverted Negative

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard
  title="Error Rate"
  metric={15}
  compareMetric={10}
  metricFormat="percent"
  sentimentIsInverted
/>

Secondary Metric Zero

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard
  title="Campaign Performance"
  metric={15000}
  metricFormat="currency"
  currency="USD"
  secondaryMetric={0}
  variant="email"
/>

Custom Secondary Metric

import { KpiCard } from '@camp/kpi-card';
 
<KpiCard
  title="Custom Metric"
  metric={12345}
  metricFormat="integer"
  customSecondaryMetric={(
      <div
        style={{
          padding: '8px',
          backgroundColor: '#ffc653',
          borderRadius: '4px',
          fontSize: '12px',
          color: '#fff',
        }}
      >
        Custom secondary content
      </div>
    )}
/>

7 more variations in Storybook

Usage

Best practices

Use clear, descriptive titles that explain what the metric represents
Choose appropriate metric formats that match your data type
Include comparison metrics when trend information is valuable
Use secondary metrics to provide additional context
Implement loading states for better user experience during data fetching
Add tooltips for complex metrics or when space is limited
Consider locale-specific formatting for international applications

Content guidelines

✅ DO

Use clear, concise titles that describe the metric
Choose appropriate metric formats (integer, float, percent, currency)
Include comparison metrics when showing trends
Use secondary metrics to provide additional context
Implement loading states for better UX
Add tooltips for complex or abbreviated metrics

🚫 DON’T

Use vague or unclear metric titles
Mix different metric formats inappropriately
Show comparison metrics without clear context
Overload cards with too much information
Forget to handle loading and error states
Use tooltips for obvious information

Accessibility

The KPI Card component includes comprehensive accessibility features:

Keyboard navigation: All interactive elements are keyboard accessible
Screen reader support: Proper ARIA labels and semantic markup
Tooltip accessibility: Tooltips are properly announced to screen readers
Color contrast: Meets WCAG guidelines for text and background contrast
Focus management: Clear focus indicators for interactive elements