Skip to content

Breadcrumb

The Breadcrumb component creates navigation trails that show users their current location in your site hierarchy. Essential for deep navigation structures and improving user orientation.

Goal

Master creating breadcrumb navigation, understand Bootstrap breadcrumb classes, and build intuitive navigation trails that help users never get lost.

Bootstrap Reference

Bootstrap 5 Breadcrumb Documentation

Quick Start

Live Preview
from faststrap import Breadcrumb

Breadcrumb(
    ("Home", "/"),
    ("Products", "/products"),
    ("Laptops", None)  # None = active/current page
)

Visual Examples & Use Cases

1. With Icons - Enhanced Visual Hierarchy

Add icons to breadcrumb items for better visual recognition.

Live Preview
from faststrap import Breadcrumb, Icon

Breadcrumb(
    (Div(Icon("house-fill"), " Home"), "/"),
    (Div(Icon("folder"), " Documents"), "/documents"),
    (Div(Icon("file-earmark"), " Report.pdf"), None)
)

2. Styled Breadcrumbs - Custom Appearance

Customize breadcrumb styling with Bootstrap utility classes.

Live Preview
# Light background with padding
Breadcrumb(
    ("Home", "/"),
    ("Library", "/library"),
    ("Data", None),
    cls="bg-light p-3 rounded"
)

# Primary themed breadcrumb
Breadcrumb(
    ("Dashboard", "/dashboard"),
    ("Analytics", "/analytics"),
    ("Reports", None),
    cls="bg-primary bg-opacity-10 p-3 rounded border border-primary"
)

3. Responsive Breadcrumbs - Mobile-Friendly

Show abbreviated breadcrumbs on mobile devices.

from faststrap import Breadcrumb
from fasthtml.common import Div

def ResponsiveBreadcrumb(*items):
    # Full breadcrumb for desktop
    full_breadcrumb = Breadcrumb(*items, cls="d-none d-md-flex")

    # Abbreviated for mobile (only show last 2 items)
    mobile_items = items[-2:] if len(items) > 2 else items
    mobile_breadcrumb = Breadcrumb(*mobile_items, cls="d-md-none")

    return Div(full_breadcrumb, mobile_breadcrumb)

# Usage
ResponsiveBreadcrumb(
    ("Home", "/"),
    ("Products", "/products"),
    ("Electronics", "/products/electronics"),
    ("Laptops", "/products/electronics/laptops"),
    ("Gaming", None)
)

Practical Functionality

Dynamic Breadcrumbs from URL Path

Automatically generate breadcrumbs from the current URL.

from faststrap import Breadcrumb
from fasthtml.common import Request

def auto_breadcrumb(request: Request):
    path = request.url.path
    parts = [p for p in path.split('/') if p]

    items = [("Home", "/")]
    current_path = ""

    for i, part in enumerate(parts):
        current_path += f"/{part}"
        label = part.replace('-', ' ').title()

        # Last item is active (no href)
        if i == len(parts) - 1:
            items.append((label, None))
        else:
            items.append((label, current_path))

    return Breadcrumb(*items)

# Usage in route
@app.get("/products/electronics/laptops")
def laptops_page(request: Request):
    return Div(
        auto_breadcrumb(request),  # Generates: Home > Products > Electronics > Laptops
        # Page content...
    )

Add dropdown menus to breadcrumb items for quick navigation to siblings.

from faststrap import Breadcrumb, Dropdown, DropdownItem
from fasthtml.common import Div, A

def BreadcrumbWithDropdown():
    return Div(
        Div(
            A("Home", href="/", cls="breadcrumb-item"),
            " / ",
            Dropdown(
                DropdownItem("Electronics", href="/products/electronics"),
                DropdownItem("Clothing", href="/products/clothing"),
                DropdownItem("Books", href="/products/books"),
                label="Products",
                variant="link",
                size="sm",
                toggle_cls="breadcrumb-item text-decoration-none p-0"
            ),
            " / ",
            Span("Laptops", cls="breadcrumb-item active"),
            cls="d-flex align-items-center"
        ),
        cls="breadcrumb"
    )

Bootstrap CSS Classes Explained

Core Breadcrumb Classes

Class Purpose Applied To
.breadcrumb Container - Styles the ordered list <ol> element
.breadcrumb-item Item - Styles each breadcrumb link <li> elements
.breadcrumb-item.active Active state - Current page indicator Last <li> element

Separator Customization

Bootstrap uses CSS ::before pseudo-element for separators. Customize via CSS variables:

/* Change separator */
.breadcrumb {
  --bs-breadcrumb-divider: '>';
}

/* Use icon as separator */
.breadcrumb {
  --bs-breadcrumb-divider: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='8' height='8'%3E%3Cpath d='M2.5 0L1 1.5 3.5 4 1 6.5 2.5 8l4-4-4-4z' fill='currentColor'/%3E%3C/svg%3E");
}

/* Remove separator */
.breadcrumb {
  --bs-breadcrumb-divider: '';
}

Styling Classes

Class Purpose Effect
.bg-light Background - Light gray background Visual container
.p-3 Padding - Adds spacing More prominent
.rounded Corners - Rounded borders Softer appearance
.border Border - Adds border Defined container
.text-decoration-none No underline - Removes link underline Cleaner look

Responsive Breadcrumb Patterns

Collapsible Breadcrumbs

Show only essential items on mobile, expand on desktop.

from faststrap import Breadcrumb, Dropdown

def CollapsibleBreadcrumb(*items):
    if len(items) <= 3:
        return Breadcrumb(*items)

    # On mobile: Home > ... > Current
    # On desktop: Full path
    first = items[0]
    last = items[-1]
    middle = items[1:-1]

    return Div(
        # Mobile version
        Breadcrumb(
            first,
            ("...", None),  # Ellipsis
            last,
            cls="d-md-none"
        ),
        # Desktop version
        Breadcrumb(*items, cls="d-none d-md-flex")
    )

Core Faststrap Features

Using with Layouts

Breadcrumbs work great in page headers and dashboard layouts.

from faststrap import DashboardLayout, Breadcrumb, Card

@app.get("/dashboard/analytics/reports")
def reports_page():
    breadcrumb = Breadcrumb(
        ("Dashboard", "/dashboard"),
        ("Analytics", "/dashboard/analytics"),
        ("Reports", None)
    )

    return DashboardLayout(
        breadcrumb,
        Card("Report content here..."),
        title="Reports"
    )

Common Recipes

The "Back Button" Alternative

Use breadcrumbs instead of generic "Back" buttons for better context.

# ❌ Generic back button - where does it go?
Button("← Back", variant="link")

# ✅ Breadcrumb - shows exact path
Breadcrumb(
    ("Products", "/products"),
    ("Laptops", "/products/laptops"),
    ("Dell XPS 15", None)
)

E-commerce Product Navigation

def ProductBreadcrumb(category: str, subcategory: str, product: str):
    return Breadcrumb(
        (Icon("house-fill"), "/"),
        (category, f"/category/{category.lower()}"),
        (subcategory, f"/category/{category.lower()}/{subcategory.lower()}"),
        (product, None),
        cls="mb-4"
    )

# Usage
ProductBreadcrumb("Electronics", "Laptops", "Dell XPS 15")

Documentation Site Navigation

def DocsBreadcrumb(section: str, page: str):
    return Breadcrumb(
        ("Docs", "/docs"),
        (section, f"/docs/{section.lower()}"),
        (page, None),
        cls="bg-light p-2 rounded mb-4"
    )

# Usage
DocsBreadcrumb("Components", "Button")

Accessibility Best Practices

Faststrap automatically handles accessibility:

✅ Automatic Features: - aria-label="breadcrumb" on <nav> element - aria-current="page" on active item - Semantic <nav> and <ol> structure - Proper link hierarchy

Manual Enhancements:

# Custom aria-label for context
Breadcrumb(
    ("Home", "/"),
    ("Products", "/products"),
    ("Laptops", None),
    aria_label="Product category navigation"
)

Parameter Reference

Parameter Type Description
*items tuple Breadcrumb items as (label, href) or (label, href, active)
**kwargs Any Additional HTML attributes (cls, id, aria-*, style)

Item Format: - (label, href) - Link item (href can be string or None for active) - (label, href, active) - Explicitly set active state (True/False) - Last item is automatically marked as active if not specified

faststrap.components.navigation.breadcrumb.Breadcrumb(*items, **kwargs)

Bootstrap Breadcrumb component for navigation trail.

Parameters:

Name Type Description Default
*items tuple[Any, str | None] | tuple[Any, str | None, bool]

Breadcrumb items as (label, href) or (label, href, active)

 ()
**kwargs Any

Additional HTML attributes

 {}
Source code in src/faststrap/components/navigation/breadcrumb.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
@register(category="navigation")
def Breadcrumb(
    *items: tuple[Any, str | None] | tuple[Any, str | None, bool],
    **kwargs: Any,
) -> Nav:
    """Bootstrap Breadcrumb component for navigation trail.

    Args:
        *items: Breadcrumb items as (label, href) or (label, href, active)
        **kwargs: Additional HTML attributes
    """
    crumbs: list[Any] = []
    last_idx = len(items) - 1

    for idx, item in enumerate(items):
        if len(item) == 3:
            label, href, active = item
        elif len(item) == 2:
            label, href = item
            active = idx == last_idx
        else:
            raise ValueError(
                f"Breadcrumb item must be (label, href) or (label, href, active), got {item}"
            )

        item_cls = "breadcrumb-item" + (" active" if active else "")

        if active or href is None:
            crumbs.append(Li(label, cls=item_cls, aria_current="page"))
        else:
            crumbs.append(Li(A(label, href=href), cls=item_cls))

    # Build breadcrumb
    user_cls = kwargs.pop("cls", "")
    ol_cls = merge_classes("breadcrumb", user_cls)

    nav_attrs: dict[str, Any] = {"aria_label": "breadcrumb"}
    nav_attrs.update(convert_attrs(kwargs))

    return Nav(Ol(*crumbs, cls=ol_cls), **nav_attrs)