Skip to content

SidebarNavbar

SidebarNavbar renders vertical navigation for dashboards, admin panels, and internal tools.

Quick Start

from faststrap import SidebarNavbar

SidebarNavbar(
    ("Dashboard", "/dashboard", "house"),
    ("Users", "/users", "people"),
    ("Settings", "/settings", "gear"),
    brand="Ops Console",
    theme="dark",
)

Tuple items use (label, href) or (label, href, icon). Icons use Bootstrap Icons names without the bi- prefix.

Parameters

Parameter Type Default Description
*items Any Tuple items or SidebarNavItem components.
brand str \| None None Brand label.
brand_href str "/" Brand link target.
position str \| None UNSET "left" or "right".
width str \| None UNSET CSS width value, defaulting to 250px.
collapsible bool \| None UNSET Adds a sidebar ID for mobile collapse patterns.
theme str \| None UNSET "dark" or "light".
sticky bool \| None UNSET Adds sticky-top.
**kwargs Any Extra root attributes.

Individual Items

from faststrap import SidebarNavItem

SidebarNavItem("Dashboard", href="/dashboard", icon="speedometer2", active=True)

Notes

  • For full dashboard page composition, pair this with DashboardLayout.
  • The component sets min-height: 100vh and the configured width inline.
  • collapsible=True adds id="sidebarNav"; avoid multiple collapsible sidebars with the same ID on one page.

API Reference

faststrap.components.navigation.sidebar_navbar.SidebarNavbar(*items, brand=None, brand_href='/', position=UNSET, width=UNSET, collapsible=UNSET, theme=UNSET, sticky=UNSET, **kwargs)

Premium vertical sidebar navbar with icon support.

A modern sidebar navigation component perfect for dashboards and admin panels. Fully theme-aware and responsive with mobile collapse support.

Parameters:

Name Type Description Default
*items Any

Navigation items (tuples of (label, href, icon) or SidebarNavItem components)

 ()
brand str | None

Brand name/logo text

 None
brand_href str

Brand link URL

 '/'
position str | None

Sidebar position ("left" or "right")

 UNSET
width str | None

Sidebar width (CSS value, default: "250px")

 UNSET
collapsible bool | None

Enable mobile collapse

 UNSET
theme str | None

Theme variant ("light" or "dark")

 UNSET
sticky bool | None

Make sidebar sticky

 UNSET
**kwargs Any

Additional HTML attributes

 {}

Returns:

Type Description
Div

FastHTML Div element with sidebar structure

Examples:

Basic sidebar:

>>> SidebarNavbar(
...     ("Dashboard", "/dashboard", "house"),
...     ("Users", "/users", "people"),
...     ("Settings", "/settings", "gear"),
...     brand="My App",
...     theme="dark"
... )

With custom width:

>>> SidebarNavbar(
...     ("Home", "/", "house"),
...     ("About", "/about", "info-circle"),
...     width="300px",
...     position="right"
... )
Note

Items can be tuples (label, href, icon) or SidebarNavItem components. Icons use Bootstrap Icons names (without "bi-" prefix).

See Also
  • Icon component for icon names
  • DashboardLayout for full dashboard setup
Source code in src/faststrap/components/navigation/sidebar_navbar.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
 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
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
@register(category="navigation")
def SidebarNavbar(
    *items: Any,
    brand: str | None = None,
    brand_href: str = "/",
    position: str | None = UNSET,
    width: str | None = UNSET,
    collapsible: bool | None = UNSET,
    theme: str | None = UNSET,
    sticky: bool | None = UNSET,
    **kwargs: Any,
) -> Div:
    """Premium vertical sidebar navbar with icon support.

    A modern sidebar navigation component perfect for dashboards and admin panels.
    Fully theme-aware and responsive with mobile collapse support.

    Args:
        *items: Navigation items (tuples of (label, href, icon) or SidebarNavItem components)
        brand: Brand name/logo text
        brand_href: Brand link URL
        position: Sidebar position ("left" or "right")
        width: Sidebar width (CSS value, default: "250px")
        collapsible: Enable mobile collapse
        theme: Theme variant ("light" or "dark")
        sticky: Make sidebar sticky
        **kwargs: Additional HTML attributes

    Returns:
        FastHTML Div element with sidebar structure

    Examples:
        Basic sidebar:
        >>> SidebarNavbar(
        ...     ("Dashboard", "/dashboard", "house"),
        ...     ("Users", "/users", "people"),
        ...     ("Settings", "/settings", "gear"),
        ...     brand="My App",
        ...     theme="dark"
        ... )

        With custom width:
        >>> SidebarNavbar(
        ...     ("Home", "/", "house"),
        ...     ("About", "/about", "info-circle"),
        ...     width="300px",
        ...     position="right"
        ... )

    Note:
        Items can be tuples (label, href, icon) or SidebarNavItem components.
        Icons use Bootstrap Icons names (without "bi-" prefix).

    See Also:
        - Icon component for icon names
        - DashboardLayout for full dashboard setup
    """
    # Resolve defaults
    cfg = resolve_defaults(
        "SidebarNavbar",
        position=position,
        width=width,
        collapsible=collapsible,
        theme=theme,
        sticky=sticky,
    )

    c_position = cfg.get("position", "left")
    c_width = cfg.get("width", "250px")
    c_collapsible = cfg.get("collapsible", True)
    c_theme = cfg.get("theme", "dark")
    c_sticky = cfg.get("sticky", True)

    # Build classes
    classes = ["sidebar-navbar", "d-flex", "flex-column"]

    if c_theme == "dark":
        classes.extend(["bg-dark", "text-white"])
    else:
        classes.extend(["bg-light", "border-end"])

    if c_sticky:
        classes.append("sticky-top")

    if c_position == "right":
        classes.append("sidebar-right")

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

    # Build sidebar parts
    sidebar_parts = []

    # Brand
    if brand:
        brand_classes = "sidebar-brand d-flex align-items-center p-3 mb-3 text-decoration-none"
        if c_theme == "dark":
            brand_classes += " text-white border-bottom border-secondary"
        else:
            brand_classes += " text-dark border-bottom"

        sidebar_parts.append(A(Span(brand, cls="fs-4 fw-bold"), href=brand_href, cls=brand_classes))

    # Navigation items
    nav_items = []
    for item in items:
        if isinstance(item, tuple):
            # Tuple format: (label, href, icon)
            if len(item) == 3:
                label, href, icon_name = item
                nav_items.append(SidebarNavItem(label, href=href, icon=icon_name, theme=c_theme))
            elif len(item) == 2:
                label, href = item
                nav_items.append(SidebarNavItem(label, href=href, theme=c_theme))
        else:
            # Already a component
            nav_items.append(item)

    sidebar_parts.append(Nav(*nav_items, cls="nav nav-pills flex-column mb-auto px-2"))

    # Build attributes
    attrs: dict[str, Any] = {"cls": all_classes, "style": {"width": c_width, "min-height": "100vh"}}

    # Collapsible ID for mobile
    if c_collapsible:
        attrs["id"] = "sidebarNav"

    attrs.update(convert_attrs(kwargs))

    return Div(*sidebar_parts, **attrs)

faststrap.components.navigation.sidebar_navbar.SidebarNavItem(label, href='#', icon=None, active=False, theme='dark', **kwargs)

Individual sidebar navigation item.

Parameters:

Name Type Description Default
label str

Item label text

 required
href str

Link URL

 '#'
icon str | None

Bootstrap icon name (without "bi-" prefix)

 None
active bool

Mark as active/selected

 False
theme str

Theme variant ("light" or "dark")

 'dark'
**kwargs Any

Additional HTML attributes

 {}

Returns:

Type Description
A

FastHTML A element with nav-link styling

Examples:

>>> SidebarNavItem("Dashboard", href="/dashboard", icon="house", active=True)
Source code in src/faststrap/components/navigation/sidebar_navbar.py 
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
@register(category="navigation")
def SidebarNavItem(
    label: str,
    href: str = "#",
    icon: str | None = None,
    active: bool = False,
    theme: str = "dark",
    **kwargs: Any,
) -> A:
    """Individual sidebar navigation item.

    Args:
        label: Item label text
        href: Link URL
        icon: Bootstrap icon name (without "bi-" prefix)
        active: Mark as active/selected
        theme: Theme variant ("light" or "dark")
        **kwargs: Additional HTML attributes

    Returns:
        FastHTML A element with nav-link styling

    Examples:
        >>> SidebarNavItem("Dashboard", href="/dashboard", icon="house", active=True)
    """
    # Build classes
    classes = ["nav-link", "d-flex", "align-items-center", "gap-2", "py-2", "px-3"]

    if active:
        classes.append("active")
    else:
        if theme == "dark":
            classes.append("text-white")
        else:
            classes.append("text-dark")

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

    # Build content
    content = []
    if icon:
        content.append(Icon(icon, cls="fs-5"))
    content.append(Span(label))

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

    attrs.update(convert_attrs(kwargs))

    return A(*content, **attrs)