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"),
)

Usage Scenarios

Inline in a Row

Row(
    Col(
        MetricCard(
            "Users",
            "2,847",
            delta="+18.2%",
            delta_type="up",
            variant="success",
            inverse=True,
        ),
        cols=12, cols_md=6, cols_lg=3,
    ),
    Col(
        MetricCard(
            "Bounce Rate",
            "24.3%",
            delta="-2.1%",
            delta_type="down",
            variant="danger",
        ),
        cols=12, cols_md=6, cols_lg=3,
    ),
    g=3,
)

Without Icon

MetricCard(
    "Orders",
    "384",
    delta="+5.1%",
    delta_type="up",
)

Theming

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

Accessibility

• Ensure delta color differences are also visible via text or icon for color-blind users.
• Use variant and inverse consistently with your theme palette to maintain contrast ratios.

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.

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)