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

Usage Scenarios

Data Table Row

DataTable(
    data=[
        {"name": "Alice", "status": "active"},
        {"name": "Bob", "status": "pending"},
    ],
    columns=["name", "status"],
    render_status=lambda row: StatusBadge(
        row["status"].title(),
        status=row["status"],
    ),
)

Card Footer

Card(
    Card.Body("Project deployment completed."),
    Card.Footer(
        StatusBadge("Deployed", status="success"),
        StatusBadge("Reviewed", status="info"),
    ),
)

Custom Icons

StatusBadge(
    "Custom",
    status="warning",
    icon="lightning-fill",
    show_dot=True,
)

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

Accessibility

• StatusBadge uses semantic color/status mapping; ensure sufficient contrast for dot indicators.
• The pill option increases the touch target size for mobile UIs.

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

@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

@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)