Data Display

StatisticGroup

Grid container that arranges a set of statistic tiles into a responsive multi-column layout with shared labelling.

import { StatisticGroup } from '@lostgradient/cinder/statistic-group';
data-displaydashboard
01

Overview

Grid container that lays out multiple stat tiles with consistent spacing and alignment.

Usage

StatisticGroup is a compound component. Import the parent and compose StatisticGroup.Statistic via the namespace API.

svelte 
<script lang="ts">
  import { StatisticGroup } from '@lostgradient/cinder/statistic-group';
</script>

<StatisticGroup label="This quarter" columns={3}>
  <StatisticGroup.Statistic label="Monthly revenue" value="$48,250" />
  <StatisticGroup.Statistic label="Active users" value={1289} />
  <StatisticGroup.Statistic label="Churn" value="2.1%" />
</StatisticGroup>

The leaf remains importable individually for à-la-carte builds — see @lostgradient/cinder/statistic.

Rendering and customization

The root .cinder-statistic-group receives class, style, and every other prop, carries data-cinder-variant and data-cinder-columns, and is the container that the column-collapse queries measure — so sizing the root (style="inline-size: 20rem", a max-inline-size class) is what makes a fixed column count collapse. The cells render inside an inner .cinder-statistic-group__grid, which owns display: grid, the column template, and the gap. Target that element for layout overrides such as grid-template-columns; a gap override on the root does not reach it, but --cinder-statistic-group-gap set on the root does. Cells are .cinder-statistic inside the grid, so a direct-child selector reads .cinder-statistic-group > .cinder-statistic-group__grid > .cinder-statistic.

Live preview
Projects 42
Members 18
Storage 64 GB
API calls 128K
02

When to use

Use when
  • Showing a row of related statistic tiles such as the top metrics of a dashboard.
  • Giving a cluster of statistic entries a single accessible group label.
Avoid when
  • Rendering exactly one metric — use statistic on its own.
  • Building a freeform card grid unrelated to numeric metrics — compose surface or grid-list directly.
03

Examples

Responsive auto columns

Setting `columns` to `auto` switches the grid to CSS auto-fit with minmax, so tiles reflow to fit the available width instead of locking to a fixed column count.

Basic stat group

A row of summary metrics. Uses the StatisticGroup namespace API: StatisticGroup.Statistic renders each metric inside the parent StatisticGroup grid.

Cards variant

The `cards` variant renders each metric as a discrete bordered card, separating the tiles instead of laying them out edge-to-edge in a shared grid.

Compact summary strip

Dense summaries can tune StatisticGroup spacing and Statistic typography through public CSS variables.

Marketing metrics

A landing-page KPI band recipe: Container frames heading copy above StatisticGroup in the cards variant, with fully-worded change labels.

Multi-row group

More metrics than columns, so the grid wraps. The default variant draws a vertical divider between neighbours and suppresses it at the end of each row, and a fixed column count collapses as the group itself narrows.

Shared-borders variant

The `shared-borders` variant wraps the whole set in a single outer border and divides the tiles with 1px gap rules, keeping the grid visually unified.

04

Props

Props for statistic-group
Name
Type
Default
Description
columns 1234'auto' 'auto' Grid column count. 'auto' uses auto-fit with minmax for responsive layout.
variant 'default' | 'cards' | 'shared-borders' 'default' Visual variant; surfaced as data-cinder-variant for CSS styling. - 'default' — a bordered resting surface, with dividers between stats when columns is a fixed count. columns='auto' has no dividers: an auto-fit grid's column count is unbounded, so CSS cannot tell which cells end a row. - 'cards' — each stat gets a card-style border and shadow. - 'shared-borders' — single outer border with 1px gap dividers between stats.
children required snippet Statistic children, typically one or more <Statistic> components.
label text Optional accessible label for the whole stat set. When provided, the container becomes role="group" and uses this value as its accessible name.
role AriaRole | undefined | null