Stat Grid

A responsive grid of KPI cards. Drop-in dashboard hero.

Active users

12,480

+8.2%

Revenue

$48.2k

vs $44.1k last month

Churn

1.4%

−0.3%

import { StatGrid } from '@/foundations/blocks/stat-grid';

export default function StatGridPreview() {
  return (
    <StatGrid
      columns={3}
      items={[
        {
          label: 'Active users',
          value: '12,480',
          trend: { direction: 'up', children: '+8.2%' },
        },
        {
          label: 'Revenue',
          value: '$48.2k',
          description: 'vs $44.1k last month',
        },
        {
          label: 'Churn',
          value: '1.4%',
          trend: { direction: 'down', children: '−0.3%' },
        },
      ]}
    />
  );
}

export const meta = {
  layout: 'padded',
};

Dependencies

Stat

Surface

@untitledui-pro/icons

Source Code

import { TrendDown01, TrendUp01 } from '@untitledui-pro/icons/solid';

import { Stat } from '@/components/stat';
import { Surface } from '@/components/surface';
import { cn } from '@/lib/utils/classnames';

interface StatGridItem {
  label: React.ReactNode;
  value: React.ReactNode;
  description?: React.ReactNode;
  trend?: {
    direction: 'up' | 'down' | 'flat';
    children: React.ReactNode;
  };
}

interface StatGridProps extends React.ComponentPropsWithRef<'div'> {
  items: StatGridItem[];
  columns?: 2 | 3 | 4;
}

const columnsClass = {
  2: 'sm:grid-cols-2',
  3: 'sm:grid-cols-2 lg:grid-cols-3',
  4: 'sm:grid-cols-2 lg:grid-cols-4',
} as const;

const StatGrid = ({
  ref,
  className,
  items,
  columns = 3,
  ...rest
}: StatGridProps) => (
  <div
    ref={ref}
    className={cn(
      'grid w-full grid-cols-1 gap-4',
      columnsClass[columns],
      className
    )}
    {...rest}
  >
    {items.map((item, i) => (
      <Surface key={i}>
        <Stat>
          <Stat.Label>{item.label}</Stat.Label>
          <Stat.Value>{item.value}</Stat.Value>
          {item.trend ? (
            <Stat.Trend direction={item.trend.direction}>
              {item.trend.direction === 'up' ? <TrendUp01 /> : null}
              {item.trend.direction === 'down' ? <TrendDown01 /> : null}
              {item.trend.children}
            </Stat.Trend>
          ) : null}
          {item.description ? (
            <Stat.Description>{item.description}</Stat.Description>
          ) : null}
        </Stat>
      </Surface>
    ))}
  </div>
);

export type { StatGridItem, StatGridProps };
export { StatGrid };

StatGrid is a composed block — a responsive grid of Surface-wrapped Stat cards driven by a single items array. Use it as the top section of a dashboard when you want a no-fuss KPI row.

Anatomy


          <StatGrid
  columns={3}
  items={[
    { label, value, trend: { direction: 'up', children: '+8.2%' } },
    { label, value, description },
  ]}
/>

API Reference

StatGrid

Extends the div element.

Prop	Default	Type
`items *`	-	`StatGridItem[]`
`columns`	`3`	`234`

StatGridItem


          interface StatGridItem {
  label: React.ReactNode;
  value: React.ReactNode;
  description?: React.ReactNode;
  trend?: {
    direction: 'up' | 'down' | 'flat';
    children: React.ReactNode;
  };
}

Examples

Default