Skip to content

Status Badge

StatusBadge builds on Badge with semantic status names, optional icons, and optional dot indicators.

Use it anywhere a status label should read consistently across dashboards, tables, cards, and activity feeds.

Import

from faststrap import StatusBadge, BadgeGroup

Basic Usage

StatusBadge("Live", status="success")
StatusBadge("Pending", status="pending")
StatusBadge("Failed", status="error")

Dot Style

StatusBadge("Pending", status="pending", show_dot=True)

Badge Groups

BadgeGroup(
    StatusBadge("Live", status="success"),
    StatusBadge("Beta", status="info"),
)

Status Mapping

Status Default Variant Default Icon
success success check-circle-fill
error danger x-circle-fill
warning warning exclamation-triangle-fill
info info info-circle-fill
pending warning clock-fill
neutral secondary none

Parameters

Param Type Description
label str Badge text.
status success | error | warning | info | pending | neutral Semantic status name.
variant str | None Bootstrap variant override.
icon str | None Bootstrap icon override. Set "" to suppress the default icon.
show_dot bool Show a dot before the label.
pill bool Use rounded pill styling.

faststrap.components.display.status_badge.StatusBadge(label, *, status='neutral', variant=None, icon=None, show_dot=False, pill=True, **kwargs)

Render a semantic status badge.

Source code in src/faststrap/components/display/status_badge.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
@register(category="display")
@beta
def StatusBadge(
    label: str,
    *,
    status: StatusType = "neutral",
    variant: VariantType | None = None,
    icon: str | None = None,
    show_dot: bool = False,
    pill: bool = True,
    **kwargs: Any,
) -> Span:
    """Render a semantic status badge."""
    resolved_variant = variant or STATUS_VARIANTS.get(status, "secondary")
    resolved_icon = icon if icon is not None else STATUS_ICONS.get(status)
    user_cls = kwargs.pop("cls", "")
    content: list[Any] = []

    if show_dot:
        content.append(
            Span(
                cls="rounded-circle d-inline-block",
                style={"width": "0.45rem", "height": "0.45rem", "background": "currentColor"},
                aria_hidden="true",
            )
        )
    elif resolved_icon:
        content.append(Icon(resolved_icon, cls="me-1", aria_hidden="true"))

    content.append(label)
    return Badge(
        *content,
        variant=resolved_variant,
        pill=pill,
        cls=merge_classes(
            "faststrap-status-badge d-inline-flex align-items-center gap-1", user_cls
        ),
        data_status=status,
        **kwargs,
    )

faststrap.components.display.status_badge.BadgeGroup(*badges, gap=2, align='center', **kwargs)

Render a wrapping group of badges or chips.

Source code in src/faststrap/components/display/status_badge.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
@register(category="display")
@beta
def BadgeGroup(
    *badges: Any,
    gap: int = 2,
    align: str = "center",
    **kwargs: Any,
) -> Span:
    """Render a wrapping group of badges or chips."""
    user_cls = kwargs.pop("cls", "")
    attrs: dict[str, Any] = {
        "cls": merge_classes(
            f"faststrap-badge-group d-inline-flex flex-wrap align-items-{align} gap-{gap}",
            user_cls,
        ),
    }
    attrs.update(convert_attrs(kwargs))
    return Span(*badges, **attrs)