---
name: kpi_card
kind: component
lang: cpp
domain: viz
version: "1.3.0"
purity: pure
signature: "void kpi_card(const char* label, float value, float delta_percent, const float* history = nullptr, int history_count = 0, const char* format = \"%.1f\", const char* icon = nullptr)"
description: "Card de KPI con icono opcional + label, valor grande, delta porcentual con TI_TRENDING_UP/DOWN y sparkline historico. Contenedor con surface bg, borde y radius via tokens (Mantine Paper equivalente)."
tags: [imgui, kpi, card, dashboard, metrics, sparkline, tokens, tabler]
uses_functions: ["sparkline_cpp_viz", "tokens_cpp_core"]
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: [imgui]
tested: false
tests: []
test_file_path: ""
file_path: "cpp/functions/viz/kpi_card.cpp"
framework: imgui
params:
  - name: label
    desc: "Nombre del KPI mostrado como header muted (ej: \"Revenue\", \"Users\")"
  - name: value
    desc: "Valor numerico actual del KPI"
  - name: delta_percent
    desc: "Cambio porcentual respecto al periodo anterior (positivo = mejora, negativo = deterioro)"
  - name: history
    desc: "Array de valores historicos para el sparkline. Nullable — si es nullptr no se renderiza sparkline"
  - name: history_count
    desc: "Numero de valores en el array history"
  - name: format
    desc: "Formato printf para el valor principal (ej: \"$%.0f\", \"%.1f%%\", \"%.2f\")"
  - name: icon
    desc: "Glyph Tabler opcional (TI_* de core/icons_tabler.h) renderizado antes del label. Nullable — si es nullptr solo muestra label"
output: "Renderiza la card KPI completa en el frame ImGui actual: top row con icono opcional + label muted, valor grande, badge delta verde/rojo con TI_TRENDING_UP/DOWN, y sparkline de 120x24px"
---

# kpi_card

Card compacta para dashboards ImGui que muestra un KPI con contexto de tendencia. Combina label, valor escalado, badge de delta colorizado y sparkline historico en un grupo coherente de ~150px de ancho.

Usa `sparkline` del registry para el historico, con el mismo color que el badge (verde si delta >= 0, rojo si delta < 0).

Debe llamarse dentro del render callback de `fn::run_app` (o cualquier contexto con un frame ImGui activo).

## Ejemplo

```cpp
float history[] = {10.0f, 12.0f, 11.0f, 15.0f, 18.0f, 17.0f, 20.0f};
kpi_card("Revenue", 20000.0f, 12.5f, history, 7, "$%.0f");

// Sin sparkline
kpi_card("Error Rate", 0.3f, -15.2f, nullptr, 0, "%.2f%%");

// Grid de KPIs
ImGui::Columns(3, "kpis", false);
kpi_card("MAU",     1250000.0f,  3.4f, mau_history, 30);
ImGui::NextColumn();
kpi_card("Revenue", 89400.0f,   -1.2f, rev_history, 30, "$%.0f");
ImGui::NextColumn();
kpi_card("Churn",   2.1f,       -0.3f, churn_history, 30, "%.1f%%");
ImGui::Columns(1);
```

## Notas

- **v1.1**: la card se renderiza dentro de un `BeginChild` con `surface` bg, `border` y `radius::md` de `fn_tokens` — replica el `<Paper withBorder radius="md" p="sm">` del frontend.
- **v1.2**: altura fija 78px (antes 108px) + font scale `1.4x` (antes `1.8x`) + padding `spacing::sm` (antes `md`). Mas compacta para densidades altas de KPIs. `NoScrollbar|NoScrollWithMouse` ademas de altura fija para evitar lag al redimensionar.
- **v1.3** (sesion 2026-04-25): nuevo parametro opcional `icon` (Tabler `TI_*` glyph) renderizado antes del label en la top row. Triangulos de delta migrados a `TI_TRENDING_UP` / `TI_TRENDING_DOWN` (los UTF-8 hex anteriores no estan en el atlas Karla/DroidSans → cuadritos). Em dash placeholder migrado a `TI_MINUS`. Altura subida 78→86 px para acomodar el row icono+label sin apretar. `uses_functions` ahora incluye implicitamente `icons_tabler` (header puro, no funcion).
- El ancho se adapta al contenedor padre via `GetContentRegionAvail().x`. Para que ocupe exactamente una celda usar `ImGui::BeginTable` — `BeginGroup` / `dashboard_grid` no propagan ancho constrained y la card desbordaria la celda.
- La linea de trend siempre se reserva (delta, sparkline o em dash placeholder en `text_dim`) para que un grid de KPIs quede alineado vertical.
- ~~Los caracteres UTF-8 del triangulo (`▲` U+25B2 y `▼` U+25BC) y del em dash (`—` U+2014) requieren que la fuente ImGui tenga el rango de simbolos geometricos / puntuacion general cargado.~~ → Obsoleto en v1.3: ahora se usan glyphs Tabler que estan en el atlas mergeado por `icon_font_cpp_core`.
- Colores: delta usa `fn_tokens::colors::{success, error}`, placeholder `TI_MINUS` usa `text_dim`, label + icono usan `text_muted`.