KPI Cards Premium

Beautiful, accessible dashboard cards for displaying key performance indicators

Quick Start

KPI Cards are RSL's flagship dashboard component. Create stunning metric displays with a single element and data attributes.

Basic Usage

Basic KPI Card • HTML

Pro Tip

Include both kpi-cards.css and kpi-cards.js in your project. The JavaScript auto-initializes any element with data-rsl-kpi attribute.

Data Attributes API

KPI Cards are fully configurable via data attributes - no JavaScript required for basic usage.

Core Attributes

Attribute Type Description
data-rsl-kpi Boolean Initialize as KPI card (required for auto-build)
data-value String Main metric value (e.g., "$124,500", "2,847", "3.2%")
data-label String Label/title for the metric
data-icon String FontAwesome icon class (e.g., "fa-dollar-sign")
data-color-scheme String Color theme: primary, success, warning, danger, info

Trend Attributes

Attribute Type Description
data-trend String Trend direction: up, down, neutral
data-trend-value String Trend percentage (e.g., "+12.5%", "-3.2%")
data-comparison String Comparison text (e.g., "vs last month")

Animation Attributes

Attribute Type Description
data-animate Boolean Enable count-up animation for numeric values
data-animation-duration Number Animation duration in milliseconds (default: 1000)
data-decimal-places Number Decimal places for animated numbers (default: 0)

Advanced Attributes

Attribute Type Description
data-sparkline JSON Array Data points for inline sparkline (e.g., "[80,85,90,88,95]")
data-progress Number Progress bar value (0-100 or custom max)
data-progress-max Number Progress bar maximum value (default: 100)
data-progress-label String Progress bar label text
data-secondary-value String Secondary metric value
data-secondary-label String Secondary metric label
data-size String Card size: compact, large, hero
data-glow Boolean Enable glow effect on card
data-accent String Accent style: gradient, left
data-clickable Boolean Make card clickable
data-href String URL to navigate on click (requires data-clickable)
data-loading Boolean Show loading/skeleton state

FilterBus Integration Attributes

Attribute Type Description
data-filter-subscribe String FilterBus key to subscribe to (e.g., "region", "status")
data-filter-value String Filter value(s) this card matches. Card shows when filter equals this value. Supports comma-separated values for multi-match (e.g., "North,South"). Cards without this attribute always show.

FilterBus Integration

KPI Cards can subscribe to RSL's FilterBus for visibility filtering based on external filter controls. This is ideal for dashboard scenarios where filter buttons control which KPI cards are displayed.

How It Works

  • Add data-filter-subscribe="key" to listen to a FilterBus channel
  • Add data-filter-value="value" to specify which filter value this card matches
  • Cards without data-filter-value always show (great for "Total" metrics)
  • "All" filter value shows all cards (case-insensitive)

Example: Region-Filtered KPIs

FilterBus KPI Cards • HTML
<!-- Filter publishes to FilterBus -->
<div data-rsl-filter data-filter-key="region">
    <button data-filter-value="All">All</button>
    <button data-filter-value="North">North</button>
    <button data-filter-value="South">South</button>
</div>

<!-- Total KPI - Always shows (no filter-value) -->
<div data-rsl-kpi
     data-filter-subscribe="region"
     data-label="Total Revenue"
     data-value="$500,000">
</div>

<!-- North KPI - Only shows when region="North" -->
<div data-rsl-kpi
     data-filter-subscribe="region"
     data-filter-value="North"
     data-label="North Region"
     data-value="$200,000">
</div>

<!-- South KPI - Only shows when region="South" -->
<div data-rsl-kpi
     data-filter-subscribe="region"
     data-filter-value="South"
     data-label="South Region"
     data-value="$150,000">
</div>

Events

Event Detail Description
rsl-kpi-card:filterbus-update { state, meta, visible } Fired when card visibility changes due to FilterBus update

Date Range Filtering

KPI Cards can filter by date range when connected to a Date Picker via FilterBus. Use data-filterbus-date-field on the container and data-date on each card to enable date filtering.

How It Works

  • Add data-filterbus-date-field="date" to the container (e.g., slot-layout)
  • Add data-date="YYYY-MM-DD" to each KPI card element
  • Connect a Date Picker that publishes to FilterBus
  • Cards automatically show/hide based on selected date range

Example: Date-Filtered KPIs

Date Range Filter Setup • HTML
<!-- Date Picker publishes to FilterBus -->
<input type="text"
       data-rsl-date-picker
       data-mode="range"
       data-filterbus-publish="dateFilter">

<!-- Container with date field attribute -->
<div class="slot-layout" data-filterbus-date-field="date">

    <!-- KPI cards with date attributes -->
    <div data-rsl-kpi
         data-date="2025-12-01"
         data-label="Q4 Revenue"
         data-value="$340,800">
    </div>

    <div data-rsl-kpi
         data-date="2025-12-15"
         data-label="Holiday Sales"
         data-value="$125,000">
    </div>

    <div data-rsl-kpi
         data-date="2025-12-28"
         data-label="Year End"
         data-value="$89,600">
    </div>

</div>

Date Filter Attributes

Attribute Applied To Description
data-filterbus-date-field Container Specifies the data attribute on cards containing dates (e.g., "date" looks for data-date)
data-date KPI Card The date value for this card. Supports ISO (YYYY-MM-DD), US (MM/DD/YYYY), and European (DD.MM.YYYY) formats.

JavaScript API

For programmatic control, use the RSL.KPICards namespace.

Method Parameters Description
RSL.KPICards.init() None Initialize all KPI cards on the page
RSL.KPICards.create(element) HTMLElement Initialize a single KPI card
RSL.KPICards.update(element, config) HTMLElement, Object Update card with new configuration
RSL.KPICards.setLoading(element, isLoading) HTMLElement, Boolean Toggle loading state
RSL.KPICards.destroy(element) HTMLElement Destroy a KPI card instance
RSL.KPICards.getConfig(element) HTMLElement Get current configuration object
Programmatic Usage • JavaScript
// Update a KPI card dynamically
const card = document.querySelector('.rsl-kpi-card');

RSL.KPICards.update(card, {
    value: '$156,200',
    trendValue: '+25.5%',
    trend: 'up'
});

// Toggle loading state
RSL.KPICards.setLoading(card, true);
// ... fetch new data ...
RSL.KPICards.setLoading(card, false);

Accessibility

KPI Cards are built with accessibility as a core feature, not an afterthought.

Next Steps

See Examples

View examples.html for comprehensive demos

Try the Playground

Test features in playground.html

Explore Components

Browse all RSL components