Summary Stats

1.0.0

El patrón Summary Stats permite visualizar métricas y datos clave de rendimiento de forma rápida y estructurada. Está diseñado para ofrecer al usuario una visión general de su negocio, facilitando la toma de decisiones basada en datos mediante el uso de números, porcentajes de variación, etiquetas descriptivas y opcionalmente gráficos embebidos.

Horizontal

Grid

Expandable

With tooltip

import React from "react";
import { SummaryStats } from "@nimbus-ds/patterns";

const Example: React.FC = () => (
  <SummaryStats layout="horizontal">
    <SummaryStats.Item
      value="$12,500"
      description="Total sales"
      trend="up"
      trendText="15%"
    />
    <SummaryStats.Item
      value="1240"
      description="Clicks"
      trend="up"
      trendText="48%"
    />
    <SummaryStats.Item
      value="130"
      description="Products"
      trend="down"
      trendText="12%"
    />
    <SummaryStats.Item
      value="340"
      description="Orders"
      trend="up"
      trendText="8%"
    />
    <SummaryStats.Item
      value="$36.76"
      description="Avg. ticket"
      trend="down"
      trendText="3%"
    />
    <SummaryStats.Item
      value="1,250"
      description="Visits"
      trend="down"
      trendText="2%"
    />
  </SummaryStats>
);

export default Example;

Ver en Github

Reportar un bug

Ver en Storybook

Implementación

Instalá el componente via terminal.

npm install @nimbus-ds/summary-stats

Cuándo usar

Para mostrar KPIs principales en dashboards o pantallas de inicio.
Cuando el usuario necesita comparar el rendimiento actual contra un periodo anterior mediante indicadores porcentuales.
Como puntos de entrada interactivos que despliegan información detallada, como gráficos de tendencias o tablas.
Para agrupar métricas relacionadas que comparten un mismo contexto temporal.

Cuándo no usar

Para mostrar datos que no son cuantitativos o que no requieren comparación.
En flujos donde el espacio es extremadamente reducido y la métrica no aporta valor para la tarea actual.
Si se pretende mostrar más de 6 métricas en una sola línea horizontal, ya que compromete la legibilidad y el escaneo visual.

Criterios de usabilidad y productividad

Jerarquía visual clara: El dato numérico debe ser el elemento más destacado para permitir un escaneo rápido.
Feedback de variación: El uso de colores y flechas para indicar subidas o bajadas ayuda al usuario a interpretar el éxito o fracaso sin leer detalles.
Interacción opcional: La variante desplegable permite profundizar en los datos sin cambiar de contexto, manteniendo al usuario enfocado en su análisis.

Buenas prácticas de accesibilidad

Contraste y color: No dependas únicamente del color para indicar tendencias; incluí siempre íconos de flecha (arriba/abajo) y texto descriptivo.
Navegación por teclado: Si el item es interactivo (desplegable), debe ser alcanzable mediante Tab y activable con Enter o Space.
Labels descriptivos: Utilizá atributos aria-label para explicar la tendencia, por ejemplo: "Aumento del 8% respecto al mes anterior".

Anatomía

General Container: Estructura de nivel superior que agrupa todo el conjunto de métricas y el área de contenido expandible.
Item Container: Marco individual que agrupa los datos de una sola métrica. Gestiona los estados de interacción (hover, seleccionado) y el padding interno.
Value: Dato numérico principal.
Percentage/Trend: ícono de flecha y porcentaje de cambio (opcional).
Description: Texto breve que identifica la métrica.
Info Icon: Trigger para tooltip si se necesita explicar el origen del dato (opcional).
Chevron: Solo aplica para indicar si el componente es desplegable para mostrar más contenido.

Dependencias

Box
Text
Icon
Tooltip
ScrollPane

Variantes

Según comportamiento:

Estático: Solo lectura, ideal para resúmenes rápidos.
Interactivo (Desplegable): Al hacer clic, expande un contenedor inferior que puede incluir gráficos de líneas o detalles adicionales.

Según Layout:

Grid: Módulos de 2 o 4 ítems, común en pantallas de inicio.
Horizontal: Agrupación de 2 a 6 métricas en una sola línea.

Según dispositivo:

Desktop: El layout es flexible; los ítems pueden tener un ancho fijo en resoluciones grandes para evitar la dispersión visual, o adaptarse de forma fluida al contenido en pantallas más pequeñas.
Mobile: Las variantes horizontales de más de 3 ítems se transforman en un scroll horizontal (ScrollPane) para mantener la legibilidad, permitiendo al usuario deslizar lateralmente sin comprometer el tamaño de los datos ni romper el diseño de la pantalla.

Do and Don'ts

✅ Do

Utilizar labels breves, entre 1 y 2 palabras, para garantizar la legibilidad en layouts compactos o móviles.
Escribir labels orientados a la acción o al concepto (ej. "Ventas netas" en lugar de "Lo que se vendió").
Mantener consistencia en el orden de las métricas si el usuario navega entre diferentes vistas.
Asegurar la accesibilidad del indicador de tendencia incluyendo siempre un ícono de flecha junto al color.
Alinear el componente al contexto: variante Grid para resúmenes generales y Horizontal/Expandible para análisis profundo.
Proveer contexto con tooltips cuando la métrica se basa en un cálculo complejo o un periodo de tiempo específico.

❌ Don't

Sobrecargar con demasiados ítems: no exceder las 6 métricas en una fila horizontal.
Utilizar ilustraciones decorativas: el foco debe ser el dato cuantitativo.
Mostrar tendencias sin datos reales: ocultar el indicador de porcentaje si no existe un periodo previo válido para comparar.
Mezclar comportamientos en un mismo grupo: evitar combinar ítems estáticos con ítems expandibles dentro del mismo contenedor.
Forzar filas horizontales estáticas en pantallas pequeñas; implementar siempre scroll horizontal para proteger la integridad de los datos.
Sumar tooltip innecesariamente: evitar el ícono informativo si el concepto de la métrica es autoexplicativo.

Props

Las propiedades adicionales se pasan al elemento <SummaryStats>. Consultá la documentación para ver la lista de atributos aceptados por el elemento <SummaryStats>.

SummaryStats

Name	Type	Default	Description
children*	React.ReactNode		Content to be rendered inside the SummaryStats component. Composed of SummaryStats.Item subcomponents.
layout	'grid' 'horizontal'	'horizontal'	Layout variant for the stats container. - "horizontal": Items in a single row (2-6 items recommended). - "grid": Items in a 2-column grid layout (2 or 4 items recommended).
expandable	boolean	'false'	Enables expandable mode where stats can be clicked to show additional content.
activeStatId	'null' 'string'		The id of the currently active stat (controlled mode). When provided, the component becomes controlled and `onActiveStatIdChange` should be used to handle state changes. Pass `null` for no active stat.
onActiveStatIdChange	object		Callback fired when the active stat changes (controlled mode). Receives the new active stat id, or `null` when the active stat is deselected.

SummaryStats.Item

Name	Type	Description
value*	string	The main value to display (e.g., "$0.00", "156").
description*	string	Brief text that identifies the metric.
trend	'down' 'neutral' 'up'	Trend indicator showing the change direction.
trendText	string	Text describing the trend or change (e.g., "+15%", "-5%", "0%").
infoTooltip	string	Tooltip content for the info icon. If provided, displays an info icon.
children	React.ReactNode	Content to display when this stat is active (for expandable variant). This content will be rendered in the expandable area below the stats row.