Summary Stats

1.0.0

O padrão Summary Stats permite visualizar métricas e dados chave de desempenho de forma rápida e estruturada. Foi projetado para oferecer ao usuário uma visão geral do seu negócio, facilitando a tomada de decisões baseada em dados mediante o uso de números, porcentagens de variação, rótulos descritivos e opcionalmente gráficos embutidos.

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 no Github

Reportar um bug

Ver no Storybook

Implementação

Instale o componente via terminal.

npm install @nimbus-ds/summary-stats

Quando usar

Para mostrar KPIs principais em dashboards ou telas de início.
Quando o usuário precisa comparar o desempenho atual contra um período anterior mediante indicadores percentuais.
Como pontos de entrada interativos que exibem informações detalhadas, como gráficos de tendências ou tabelas.
Para agrupar métricas relacionadas que compartilham um mesmo contexto temporal.

Quando não usar

Para mostrar dados que não são quantitativos ou que não requerem comparação.
Em fluxos onde o espaço é extremamente reduzido e a métrica não agrega valor para a tarefa atual.
Se pretende mostrar mais de 6 métricas em uma única linha horizontal, pois compromete a legibilidade e a leitura visual.

Critérios de usabilidade e produtividade

Hierarquia visual clara: O dado numérico deve ser o elemento mais destacado para permitir uma leitura rápida.
Feedback de variação: O uso de cores e setas para indicar subidas, ou quedas, ajuda o usuário a interpretar o sucesso ou fracasso sem ler detalhes.
Interação opcional: A variante expansível permite aprofundar nos dados sem mudar de contexto, mantendo o usuário focado em sua análise.

Boas práticas de acessibilidade

Contraste e cor: Não dependa unicamente da cor para indicar tendências; inclua sempre ícones de seta (cima/baixo) e texto descritivo.
Navegação por teclado: Se o item é interativo (expansível), deve ser alcançável mediante Tab e ativável com Enter ou Space.
Labels descritivos: Utilize atributos aria-label para explicar a tendência, por exemplo: "Aumento de 8% em relação ao mês anterior".

Anatomia

General Container: Estrutura de nível superior que agrupa todo o conjunto de métricas e a área de conteúdo expansível.
Item Container: Quadro individual que agrupa os dados de uma única métrica. Gerencia os estados de interação (hover, selecionado) e o padding interno.
Value: Dado numérico principal.
Percentage/Trend: Ícone de seta e porcentagem de mudança (opcional).
Description: Texto breve que identifica a métrica.
Info Icon: Trigger para tooltip se necessário explicar a origem do dado (opcional).
Chevron: Aplica apenas para indicar se o componente é expansível para mostrar mais conteúdo.

Dependências

Box
Text
Icon
Tooltip
ScrollPane

Variantes

Segundo comportamento:

Estático: Somente leitura, ideal para resumos rápidos.
Interativo (Expansível): Ao clicar, expande um contêiner inferior que pode incluir gráficos de linhas ou detalhes adicionais.

Segundo Layout:

Grid: Módulos de 2 ou 4 itens, comum em telas de início.
Horizontal: Agrupamento de 2 a 6 métricas em uma única linha.

Segundo dispositivo:

Desktop: O layout é flexível; os itens podem ter uma largura fixa em resoluções grandes para evitar a dispersão visual, ou adaptar-se de forma fluida ao conteúdo em telas menores.
Mobile: As variantes horizontais de mais de 3 itens se transformam em scroll horizontal (ScrollPane) para manter a legibilidade, permitindo ao usuário deslizar lateralmente sem comprometer o tamanho dos dados nem quebrar o design da tela.

Do and Don'ts

✅ Do

Utilizar labels breves, entre 1 e 2 palavras, para garantir a legibilidade em layouts compactos ou móveis.
Escrever labels orientados à ação ou ao conceito (ex. "Vendas líquidas" em vez de "O que foi vendido").
Manter consistência na ordem das métricas se o usuário navega entre diferentes vistas.
Assegurar a acessibilidade do indicador de tendência incluindo sempre um ícone de seta junto à cor.
Alinhar o componente ao contexto: variante Grid para resumos gerais e Horizontal/Expansível para análise profunda.
Prover contexto com tooltips quando a métrica se baseia em um cálculo complexo ou um período específico.

❌ Don't

Sobrecarregar com muitos itens: não exceder 6 métricas em uma fila horizontal.
Utilizar ilustrações decorativas: o foco deve ser o dado quantitativo.
Mostrar tendências sem dados reais: ocultar o indicador de porcentagem se não existe um período anterior válido para comparar.
Misturar comportamentos no mesmo grupo: evitar combinar itens estáticos com itens expansíveis dentro do mesmo contêiner.
Forçar filas horizontais estáticas em telas pequenas; implementar sempre scroll horizontal para proteger a integridade dos dados.
Adicionar tooltip desnecessariamente: evitar o ícone informativo se o conceito da métrica é autoexplicativo.

Props

Propriedades adicionais são repassadas ao elemento <SummaryStats>. Consulte a documentação do elemento div para ver a lista de atributos aceitos pelo 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.