MetricCard

MetricCard displays one important value with an optional delta and icon. Use it for dashboard KPIs, analytics summaries, and operational health cards.

Quick Start

from faststrap import Icon, MetricCard

MetricCard(
    "Revenue",
    "$42.8k",
    delta="+12.4%",
    delta_type="up",
    icon=Icon("graph-up"),
)

Parameters

Parameter	Type	Default	Description
title	str	required	Metric label.
value	str \| int \| float	required	Primary metric value.
delta	str \| int \| float \| None	None	Change text such as +12%.
delta_type	"up" \| "down" \| "neutral"	"neutral"	Delta color treatment.
icon	Any \| None	None	Optional icon or custom element.
variant	Bootstrap variant	UNSET	Card background variant.
inverse	bool	False	Use inverted text colors.
icon_bg	str \| None	UNSET	Icon wrapper background class.
**kwargs	Any		Extra HTML attributes.

Theming

MetricCard adds the faststrap-metric-card class, so you can style it with normal CSS or theme_variant_css().

API Reference

faststrap.components.display.stat_card.MetricCard(title, value, delta=None, delta_type='neutral', icon=None, variant=UNSET, inverse=False, icon_bg=UNSET, **kwargs)

Metric card with value and delta indicator.

Source code in src/faststrap/components/display/stat_card.py

@register(category="display")
@beta
def MetricCard(
    title: str,
    value: str | int | float,
    delta: str | int | float | None = None,
    delta_type: Literal["up", "down", "neutral"] = "neutral",
    icon: Any | None = None,
    variant: VariantType | None = UNSET,
    inverse: bool = False,
    icon_bg: str | None = UNSET,
    **kwargs: Any,
) -> Div:
    """Metric card with value and delta indicator."""
    user_cls = kwargs.pop("cls", "")
    kwargs["cls"] = merge_classes("faststrap-metric-card", user_cls)

    cfg = resolve_defaults(
        "MetricCard",
        delta_type=delta_type,
        variant=variant,
        inverse=inverse,
        icon_bg=icon_bg,
    )
    c_delta_type = cfg.get("delta_type", delta_type)
    c_variant = cfg.get("variant", variant)
    c_inverse = cfg.get("inverse", inverse)
    c_icon_bg = cfg.get("icon_bg", icon_bg)

    delta_el = _trend_badge(delta, delta_type=c_delta_type)
    value_el = H3(value, cls="mb-0 fw-bold")
    title_cls = "text-muted small text-uppercase fw-semibold"
    if c_inverse:
        title_cls = "text-white-50 small text-uppercase fw-semibold"

    title_el = P(title, cls=title_cls)

    icon_el = None
    if icon:
        icon_wrapper_cls = "d-flex align-items-center justify-content-center rounded p-3"
        if c_icon_bg:
            icon_wrapper_cls = f"{icon_wrapper_cls} {c_icon_bg}"
        else:
            icon_wrapper_cls = f"{icon_wrapper_cls} bg-body-tertiary"
        icon_el = Div(icon, cls=icon_wrapper_cls)

    if icon_el:
        body_content = Div(
            Div(title_el, value_el, delta_el, cls="flex-grow-1"),
            icon_el,
            cls="d-flex align-items-center justify-content-between gap-3",
        )
    else:
        body_content = Div(title_el, value_el, delta_el)

    return Card(body_content, variant=c_variant, inverse=c_inverse, **kwargs)