PixelStatGroup

Surface-aware container that groups PixelStatCard tiles in a row with dividers or a responsive grid, with shared tone and accessible group labeling.

  • Row layout with vertical dividers or grid layout with configurable columns (1–6).
  • Tone-driven border color shared by the container and inter-cell dividers.
  • Surface-aware: pixel chamfered border + pixel radius, or linear rounded corners.
  • Adopts role="group" automatically when aria-label or aria-labelledby is provided.
Status
stable
Category
data
Since
v1.9.0

API

import { PixelStatGroup } from '@pxlkit/ui-kit';
PropTypeDefaultDescription
layout'row' | 'grid''row'A divided row, or a grid.
columnsnumber3Grid columns, 1 to 6.
gap0 | 1 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | 12 | 16—Gap between grid cells (stackGap scale). Only applies to layout="grid"; omit for flush cells.
tone'neutral' | 'green' | 'cyan' | 'gold' | 'red' | 'purple' | 'pink''neutral'Tone of the frame and the row's dividers.
surface'pixel' | 'linear'—Surface override; defaults to the nearest provider.
borderedbooleantrueRender with surface-aware border + radius chrome. Defaults to true — group needs visible chrome.
aria-labelstring—Accessible name for the group landmark. Without it, role=group is dropped.
aria-labelledbystring—Id of the element that names the group, in place of aria-label.
children (required)React.ReactNode—The stat tiles.

Also takes the native attributes and event handlers of <div> (HTMLAttributes<HTMLDivElement>).

ref points to <div>.

Accessibility

WCAG target: 2.1 AA

  • group

Renders as a plain <div> by default. When aria-label or aria-labelledby is provided, the root gains role="group" to expose the collection as a named landmark to assistive tech. Without an accessible name the role is intentionally dropped to avoid an unlabeled group node. The inner stat tiles (PixelStatCard) carry their own label/value semantics.

Usage

import { PixelStatGroup, PixelStatCard } from '@pxlkit/ui-kit';

export function Default() {
  return (
    <PixelStatGroup aria-label="Key metrics">
      <PixelStatCard label="Users" value="1,284" />
      <PixelStatCard label="Revenue" value="$12.4k" />
      <PixelStatCard label="Active" value="312" />
    </PixelStatGroup>
  );
}

Examples

Default

import { PixelStatGroup, PixelStatCard } from '@pxlkit/ui-kit';

export function Default() {
  return (
    <PixelStatGroup aria-label="Key metrics">
      <PixelStatCard label="Users" value="1,284" />
      <PixelStatCard label="Revenue" value="$12.4k" />
      <PixelStatCard label="Active" value="312" />
    </PixelStatGroup>
  );
}

Row layout

import { PixelStatGroup, PixelStatCard } from '@pxlkit/ui-kit';

export function RowLayout() {
  return (
    <PixelStatGroup layout="row" aria-label="Row metrics">
      <PixelStatCard label="Sessions" value="842" />
      <PixelStatCard label="Conversions" value="56" />
      <PixelStatCard label="Bounce" value="24%" />
    </PixelStatGroup>
  );
}

Grid layout

import { PixelStatGroup, PixelStatCard } from '@pxlkit/ui-kit';

export function GridLayout() {
  return (
    <PixelStatGroup layout="grid" columns={4} aria-label="Grid metrics">
      <PixelStatCard label="A" value="10" />
      <PixelStatCard label="B" value="20" />
      <PixelStatCard label="C" value="30" />
      <PixelStatCard label="D" value="40" />
    </PixelStatGroup>
  );
}

Grid with gap

import { PixelStatGroup, PixelStatCard } from '@pxlkit/ui-kit';

export function GridWithGap() {
  return (
    <PixelStatGroup layout="grid" columns={3} gap={3} aria-label="Spaced grid metrics">
      <PixelStatCard label="Users" value="1,284" />
      <PixelStatCard label="Revenue" value="$12.4k" />
      <PixelStatCard label="Active" value="312" />
    </PixelStatGroup>
  );
}

Tones

import { PixelStatGroup, PixelStatCard } from '@pxlkit/ui-kit';

export function Tones() {
  return (
    <div className="flex flex-col gap-3">
      <PixelStatGroup tone="cyan" aria-label="Cyan group">
        <PixelStatCard label="Cyan" value="1" tone="cyan" />
        <PixelStatCard label="Cyan" value="2" tone="cyan" />
      </PixelStatGroup>
      <PixelStatGroup tone="green" aria-label="Green group">
        <PixelStatCard label="Green" value="1" tone="green" />
        <PixelStatCard label="Green" value="2" tone="green" />
      </PixelStatGroup>
    </div>
  );
}

Surfaces

import { PixelStatGroup, PixelStatCard } from '@pxlkit/ui-kit';

export function Surfaces() {
  return (
    <div className="flex flex-col gap-3">
      <PixelStatGroup surface="pixel" aria-label="Pixel surface">
        <PixelStatCard label="Pixel" value="42" />
        <PixelStatCard label="Pixel" value="84" />
      </PixelStatGroup>
      <PixelStatGroup surface="linear" aria-label="Linear surface">
        <PixelStatCard label="Linear" value="42" />
        <PixelStatCard label="Linear" value="84" />
      </PixelStatGroup>
    </div>
  );
}

Related