Docs›Componentes (Admin)›mad-metric-card
Componentes (Admin)

mad-metric-card

KPI estático (valor pronto via prop).

Componente indicador estatico — recebe o valor pronto via prop. Para queries automaticas no banco, use <mad-db-metric-card> (ver db-metric-card-rules.md).

Diferenca para <mad-db-metric-card>

<mad-metric-card> <mad-db-metric-card>
Origem do valor Prop value (string/numero pronto) Query automatica via model/query (Eloquent) + total
Faz query no banco Nao Sim (Eloquent Model::query() ou :query injetado)
Quando usar Valor ja calculado, KPI manual, agregacao customizada Contagem/soma direta de uma tabela
Formatacao Manual (passar ja formatado) Automatica via prop format

Props

Prop Tipo Default Descricao
label string '' Texto do card
value string '' Valor a exibir (ja formatado)
icon string null Nome do icone Lucide
variant string 'default' default, success, warning, error, info
icon-color string null Sobrescreve a cor do icone (qualquer CSS) — tem prioridade sobre variant
icon-bg string null Sobrescreve o fundo do badge do icone — tem prioridade sobre variant
trend string null Ex: '+12%' ou '-5'. Sem trend-direction, o sinal (+ / - / −) e que define cor e icone
trend-label string null Ex: 'vs mes anterior'
trend-direction string null up, down ou flat — define a direcao explicitamente e dispensa o sniff do sinal. Prefira este prop quando o valor de trend for localizado ou formatado (o sniff quebra sem o +/- no inicio)
trend-invert bool false Metrica onde subir e ruim (custo, churn, tempo de resposta): inverte apenas a COR, mantendo o icone coerente com a direcao real
class string '' Classes CSS extras
style string '' Estilos inline

Uso basico

<mad-metric-card label="Clientes Ativos" value="1.247" icon="users" />

Com variant e trend

<mad-metric-card label="Receita Total" value="R$ 84.500"
    icon="dollar-sign" variant="success"
    trend="+12%" trend-label="este mes" />

<mad-metric-card label="Pedidos Abertos" value="34"
    icon="shopping-cart" variant="warning"
    trend="-5" trend-label="hoje" />

Valor calculado em PHP

@php
    $totalReceita = 'R$ ' . number_format($receita, 2, ',', '.');
@endphp
<mad-metric-card label="Receita" :value="$totalReceita"
    icon="circle-dollar-sign" variant="success" />

Valor agregado customizado (multi-tabela, calculo complexo)

@php
    // Eloquent puro — sem necessidade de abrir/fechar transacao so pra ler.
    $vendas    = \App\Models\PedidoVenda::where('estado_id', '=', 8)->sum('valor_total');
    $custos    = \App\Models\MovEstoque::where('tipo', '=', 'S')->sum('valor_total');
    $margem    = $vendas - $custos;
    $margemFmt = 'R$ ' . number_format($margem, 2, ',', '.');
@endphp
<mad-metric-card label="Margem" :value="$margemFmt"
    icon="trending-up" variant="success" />

Grid de indicadores

<mad-form-grid :cols="3">
    <mad-metric-card label="Receita Total" value="R$ 84.500" icon="dollar-sign"
        trend="+12%" trend-label="este mes" variant="success" />
    <mad-metric-card label="Pedidos Abertos" value="34" icon="shopping-cart"
        trend="-5" trend-label="hoje" variant="warning" />
    <mad-metric-card label="Clientes Ativos" value="1.247" icon="users" />
</mad-form-grid>

Variants

Variant Cor do icone
default Primary (azul)
success Verde
warning Laranja
error Vermelho
info Azul info

Trend — sinal define visual

  • Comeca com + → seta para cima, cor verde
  • Comeca com - → seta para baixo, cor vermelha
  • Outro → icone neutro

Quando usar <mad-metric-card> vs <mad-db-metric-card>

Cenario Usar
Contagem/soma direta de UMA tabela <mad-db-metric-card model="..." total="...">
Valor ja calculado em variavel PHP <mad-metric-card :value="$var">
Calculo envolvendo multiplas tabelas/joins <mad-metric-card :value="$resultado">
Valor vindo de API externa, cache, sessao <mad-metric-card :value="$cached">
KPI fixo/hardcoded para demonstracao <mad-metric-card value="1.247">

NUNCA fazer

{{-- ERRADO: montar card de KPI manualmente com HTML --}}
<div class="card">
    <p>Receita</p>
    <p style="font-size:24px;">R$ 84.500</p>
    <span style="color:green;">+12%</span>
</div>

{{-- CERTO --}}
<mad-metric-card label="Receita" value="R$ 84.500"
    trend="+12%" variant="success" />

{{-- ERRADO: usar mad-metric-card quando da pra usar mad-db-metric-card --}}
@php
    $total = \App\Models\PedidoVenda::count();
@endphp
<mad-metric-card label="Pedidos" :value="$total" />

{{-- CERTO: deixar o componente fazer a query --}}
<mad-db-metric-card model="PedidoVenda" total="count"
    label="Pedidos" format="integer" />

{{-- ERRADO: passar valor numerico cru sem formatar --}}
<mad-metric-card label="Receita" :value="$receita" />
{{-- exibe: 84500.5 --}}

{{-- CERTO: formatar antes --}}
@php $fmt = 'R$ ' . number_format($receita, 2, ',', '.'); @endphp
<mad-metric-card label="Receita" :value="$fmt" />