statsgroup

StatsGroup component provides a container for displaying grouped statistics. Uses a composite component API for flexible composition.
children
Required
node
ariaLabel
Not required
string

Stats Group Component

Category: Data Display

The StatsGroup component is used to display grouped statistics in a consistent, accessible layout. It provides a flexible composite component API that allows for customizable stat items with labels, values, and optional secondary stats.

When to Use

  • Dashboard metrics: Display key performance indicators, statistics, or analytics
  • Summary statistics: Show aggregated data in a scannable format
  • Comparison views: Display multiple related metrics side-by-side

General Structure

The component follows this structure:

  1. StatsGroup - Main container with grid layout
  2. StatsGroup.Item - Individual stat item container
  3. StatsGroup.Label - Label text with optional tooltip
  4. StatsGroup.Value - Main metric value with variable font sizes
  5. StatsGroup.ValueNumeric - Numeric value with automatic formatting and tooltips for large numbers
  6. StatsGroup.ValuePercentage - Percentage value with automatic formatting (always 2 decimal places)
  7. StatsGroup.SecondaryStat - Optional secondary stat below the main metric

Layout Props (Opinionated)

  • StatsGroup uses a responsive grid that stacks vertically on mobile and horizontally on larger screens
  • StatsGroup.Item provides consistent padding and layout
  • Subcomponents have opinionated layout classes that cannot be overridden

Styling Props (Flexible)

  • StatsGroup.Value accepts a size prop ("sm", "md", "lg", "xl", "2xl", "3xl") for font size control
  • StatsGroup.Label accepts tooltip prop for additional context

Usage

Basic Stats Group

With Tooltips

Long Tooltips with Wrapping

Tooltips automatically wrap to multiple lines when the text exceeds 400px width:

Custom Font Sizes

Custom Styling

Apply custom styling to the elements passed as children:

With Secondary Stat

Numeric Values with Automatic Formatting

Use StatsGroup.ValueNumeric for numeric values that should be automatically formatted with abbreviations for large numbers. Numbers under 100,000 display with comma separators (e.g., 99,999), while larger numbers are abbreviated (e.g., 123.5K, 1.2M, 1.2B). Large abbreviated numbers show the full value in a tooltip on hover.

ValueNumeric Props

PropTypeRequiredDescription
valuenumberYesThe numeric value to display
isLoadingbooleanNoShows a loading animation when true

Formatting Rules

  • Under 100,000: Displayed with comma separators (e.g., 1,000, 99,999)
  • 100,000+: Abbreviated with K/M/B suffix and one decimal place (e.g., 123.5K, 1.2M)
  • Null/undefined: Displays as -
  • Large numbers: Show full formatted value in tooltip on hover

Percentage Values with Automatic Formatting

Use StatsGroup.ValuePercentage for percentage values that should always display with exactly 2 decimal places. Accepts both numeric values and string values with % suffix.

ValuePercentage Props

PropTypeRequiredDescription
valuenumber or stringYesThe percentage value to display (e.g., 24.5 or "24.5%")
isLoadingbooleanNoShows a loading animation when true

Formatting Rules

  • Numeric input: Formatted with 2 decimal places and % suffix (e.g., 24.5 → 24.50%)
  • String input: Normalized to 2 decimal places (e.g., "7.9%" → 7.90%, "12%" → 12.00%)
  • Null/undefined: Displays as -

Complete Example

Complete Example with ValueNumeric and ValuePercentage