Badge

Small, circular or pill-shaped indicators for status, counts, or labels. Badges scale to match the size of the immediate parent element by using relative font sizing and em units.

Bootstrap Reference

Bootstrap 5 Badges

---

Quick Start

Live Preview

New

Badge("New", variant="primary")

---

Visual Examples & Use Cases

1. Variants

Like buttons, badges use semantic variants for meaning.

Code & Output

Live Preview

Success Danger Warning Light

Badge("Success", variant="success")
Badge("Danger", variant="danger")
Badge("Warning", variant="warning", pill=True)
Badge("Light", variant="light", cls="text-dark")

2. Contextual Badges

Badges are often placed inside other components like Buttons or Headings.

Live Preview

Notifications 99+

Documentation Beta

# Notification count in a button
Button(
    "Notifications ", 
    Badge("99+", variant="light", pill=True), 
    variant="primary"
)

# Status in a heading
H1("Documentation ", Badge("Beta", variant="info"))

---

Practical Functionality

1. Indicators (Dot Style)

You can create "status dots" by using a Badge with no text and specific width/height.

# A small 'Online' green dot
Badge(variant="success", rounded=True, style={"width": "10px", "height": "10px", "padding": "0"})

---

Advanced Customization

1. CSS Variables

Customize standard badge colors.

CSS Variable	Description	Default
--bs-badge-padding-x	Horizontal padding.	.65em
--bs-badge-padding-y	Vertical padding.	.35em
--bs-badge-font-size	Text size.	.75em
--bs-badge-font-weight	Boldness.	700
--bs-badge-border-radius	Corner roundness.	var(--bs-border-radius)

---

Parameter Reference

FastStrap Param	Type	Bootstrap Class	Description
variant	str	.text-bg-{variant}	Color theme.
pill	bool	.rounded-pill	Fully rounded edges.
rounded	bool	.rounded-circle	Perfect circle (if width=height).

faststrap.components.display.badge.Badge(*children, variant=None, pill=None, **kwargs)

Bootstrap Badge component for status indicators and labels.

Parameters:

Name	Type	Description	Default
*children	Any	Badge content (text, numbers, icons)	()
variant	VariantType | None	Bootstrap color variant	None
pill	bool | None	Use rounded pill style	None
**kwargs	Any	Additional HTML attributes (cls, id, hx-, data-, etc.)	{}

Returns:

Type	Description
Span	FastHTML Span element with badge classes

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

@register(category="display")
@stable
def Badge(
    *children: Any,
    variant: VariantType | None = None,
    pill: bool | None = None,
    **kwargs: Any,
) -> Span:
    """Bootstrap Badge component for status indicators and labels.

    Args:
        *children: Badge content (text, numbers, icons)
        variant: Bootstrap color variant
        pill: Use rounded pill style
        **kwargs: Additional HTML attributes (cls, id, hx-*, data-*, etc.)

    Returns:
        FastHTML Span element with badge classes
    """
    # Resolve API defaults
    cfg = resolve_defaults(
        "Badge",
        variant=variant,
        pill=pill,
    )

    c_variant = cfg.get("variant", "primary")
    c_pill = cfg.get("pill", False)

    # Build base classes
    classes = ["badge"]

    # Add variant background
    classes.append(f"text-bg-{c_variant}")

    # Add pill style if requested
    if c_pill:
        classes.append("rounded-pill")

    # Merge with user classes
    user_cls = kwargs.pop("cls", "")
    all_classes = merge_classes(" ".join(classes), user_cls)

    # Build attributes
    attrs: dict[str, Any] = {"cls": all_classes}

    # Convert remaining kwargs
    attrs.update(convert_attrs(kwargs))

    return Span(*children, **attrs)