ListGroup

The ListGroup component creates flexible, versatile lists for displaying content, navigation, and custom interfaces. Perfect for sidebars, settings panels, and any structured content display.

Goal

Master creating list groups with various styles, understand Bootstrap list-group classes, and build organized content displays that enhance user navigation.

Bootstrap Reference

Bootstrap 5 List Group Documentation

---

Quick Start

Live Preview

• First item
• Second item
• Third item

from faststrap import ListGroup, ListGroupItem

ListGroup(
    ListGroupItem("First item"),
    ListGroupItem("Second item"),
    ListGroupItem("Third item")
)

---

Visual Examples & Use Cases

1. Active and Disabled Items

ListGroup(
    ListGroupItem("Active item", active=True),
    ListGroupItem("Normal item"),
    ListGroupItem("Disabled item", disabled=True)
)

---

2. With Links - Interactive Lists

ListGroup(
    ListGroupItem("Dashboard", href="/dashboard", action=True),
    ListGroupItem("Settings", href="/settings", action=True),
    ListGroupItem("Profile", href="/profile", action=True, active=True)
)

---

3. Color Variants

ListGroup(
    ListGroupItem("Success", variant="success"),
    ListGroupItem("Danger", variant="danger"),
    ListGroupItem("Warning", variant="warning"),
    ListGroupItem("Info", variant="info")
)

---

4. With Badges

from faststrap import ListGroup, ListGroupItem, Badge

ListGroup(
    ListGroupItem(
        "Inbox",
        badge=Badge("12", variant="primary"),
        href="/inbox",
        action=True
    ),
    ListGroupItem(
        "Drafts",
        badge=Badge("3", variant="secondary"),
        href="/drafts",
        action=True
    )
)

---

5. Flush Style - Edge-to-Edge

ListGroup(
    ListGroupItem("Item 1"),
    ListGroupItem("Item 2"),
    ListGroupItem("Item 3"),
    flush=True  # ← Removes borders
)

---

6. Horizontal Lists

# Horizontal on all screens
ListGroup(
    ListGroupItem("Left"),
    ListGroupItem("Center"),
    ListGroupItem("Right"),
    horizontal=True
)

# Horizontal on medium screens and up
ListGroup(
    ListGroupItem("Item 1"),
    ListGroupItem("Item 2"),
    horizontal="md"
)

---

Bootstrap CSS Classes Explained

Class	Purpose
.list-group	Container for list items
.list-group-item	Individual list item
.list-group-item-action	Hover/focus styles for interactive items
.list-group-item-{variant}	Color variants (success, danger, etc.)
.list-group-flush	Removes borders for edge-to-edge
.list-group-horizontal	Horizontal layout
.active	Active/selected state
.disabled	Disabled state

---

Common Recipes

Settings Menu

from faststrap import ListGroup, ListGroupItem, Icon

ListGroup(
    ListGroupItem(
        Icon("person"), " Profile",
        href="/settings/profile",
        action=True,
        active=True
    ),
    ListGroupItem(
        Icon("bell"), " Notifications",
        href="/settings/notifications",
        action=True
    ),
    ListGroupItem(
        Icon("shield-lock"), " Privacy",
        href="/settings/privacy",
        action=True
    ),
    flush=True
)

---

Parameter Reference

ListGroup

Parameter	Type	Default	Description
*children	Any	Required	ListGroupItem components
flush	bool	False	Remove borders
horizontal	bool \| str	False	Horizontal layout (True or breakpoint)
numbered	bool	False	Numbered list
**kwargs	Any	-	Additional HTML attributes

ListGroupItem

Parameter	Type	Default	Description
*children	Any	Required	Item content
variant	VariantType \| None	None	Color variant
active	bool	False	Active state
disabled	bool	False	Disabled state
action	bool	False	Enable hover/focus styles
href	str \| None	None	Make item a link
badge	Any	None	Badge to display
**kwargs	Any	-	Additional HTML attributes

faststrap.components.navigation.listgroup.ListGroup(*children, flush=False, horizontal=False, numbered=False, **kwargs)

Bootstrap ListGroup component.

A flexible component for displaying lists of content.

Parameters:

Name	Type	Description	Default
*children	Any	ListGroupItem components or other content	()
flush	bool	Remove borders for edge-to-edge display in parent containers	False
horizontal	bool | Literal['sm', 'md', 'lg', 'xl', 'xxl']	Display items horizontally. True for all breakpoints, or specify breakpoint (sm, md, lg, xl, xxl)	False
numbered	bool	Display numbered list	False
**kwargs	Any	Additional HTML attributes (cls, id, hx-, data-, etc.)	{}

Returns:

Type	Description
Ul | Div	FastHTML Ul or Div element with list-group structure

Example

Basic list:

ListGroup( ... ListGroupItem("Item 1"), ... ListGroupItem("Item 2"), ... ListGroupItem("Item 3"), ... )

With active and disabled items:

ListGroup( ... ListGroupItem("Active", active=True), ... ListGroupItem("Normal"), ... ListGroupItem("Disabled", disabled=True), ... )

Flush style:

ListGroup( ... ListGroupItem("Edge to edge"), ... flush=True ... )

Horizontal:

ListGroup( ... ListGroupItem("Left"), ... ListGroupItem("Center"), ... ListGroupItem("Right"), ... horizontal=True ... )

See Also

Bootstrap docs: https://getbootstrap.com/docs/5.3/components/list-group/

Source code in src/faststrap/components/navigation/listgroup.py

@register(category="navigation")
def ListGroup(
    *children: Any,
    flush: bool = False,
    horizontal: bool | Literal["sm", "md", "lg", "xl", "xxl"] = False,
    numbered: bool = False,
    **kwargs: Any,
) -> Ul | Div:
    """Bootstrap ListGroup component.

    A flexible component for displaying lists of content.

    Args:
        *children: ListGroupItem components or other content
        flush: Remove borders for edge-to-edge display in parent containers
        horizontal: Display items horizontally. True for all breakpoints,
                   or specify breakpoint (sm, md, lg, xl, xxl)
        numbered: Display numbered list
        **kwargs: Additional HTML attributes (cls, id, hx-*, data-*, etc.)

    Returns:
        FastHTML Ul or Div element with list-group structure

    Example:
        Basic list:
        >>> ListGroup(
        ...     ListGroupItem("Item 1"),
        ...     ListGroupItem("Item 2"),
        ...     ListGroupItem("Item 3"),
        ... )

        With active and disabled items:
        >>> ListGroup(
        ...     ListGroupItem("Active", active=True),
        ...     ListGroupItem("Normal"),
        ...     ListGroupItem("Disabled", disabled=True),
        ... )

        Flush style:
        >>> ListGroup(
        ...     ListGroupItem("Edge to edge"),
        ...     flush=True
        ... )

        Horizontal:
        >>> ListGroup(
        ...     ListGroupItem("Left"),
        ...     ListGroupItem("Center"),
        ...     ListGroupItem("Right"),
        ...     horizontal=True
        ... )

    See Also:
        Bootstrap docs: https://getbootstrap.com/docs/5.3/components/list-group/
    """
    # Build classes
    classes = ["list-group"]

    if flush:
        classes.append("list-group-flush")

    if horizontal:
        if horizontal is True:
            classes.append("list-group-horizontal")
        else:
            classes.append(f"list-group-horizontal-{horizontal}")

    if numbered:
        classes.append("list-group-numbered")

    user_cls = kwargs.pop("cls", "")
    all_classes = merge_classes(" ".join(classes), user_cls)

    # Build attributes
    attrs: dict[str, Any] = {"cls": all_classes}
    attrs.update(convert_attrs(kwargs))

    # Use Div for numbered lists (they use ol styling via CSS)
    if numbered:
        return Div(*children, **attrs)

    return Ul(*children, **attrs)

faststrap.components.navigation.listgroup.ListGroupItem(*children, variant=None, active=False, disabled=False, action=False, href=None, badge=None, **kwargs)

Bootstrap ListGroup Item component.

A single item within a ListGroup.

Parameters:

Name	Type	Description	Default
*children	Any	Item content	()
variant	VariantType | None	Bootstrap color variant for background	None
active	bool	Mark item as active/selected	False
disabled	bool	Disable the item	False
action	bool	Enable hover/focus styles (for interactive items)	False
href	str | None	Make item a link (renders as )	None
badge	Any	Optional badge to display on right side	None
**kwargs	Any	Additional HTML attributes	{}

Returns:

Type	Description
Li | A | Button	FastHTML Li, A, or Button element

Example

Basic item:

ListGroupItem("Simple item")

Active with variant:

ListGroupItem("Selected", variant="primary", active=True)

Link item:

ListGroupItem("Click me", href="/page", action=True)

With badge:

ListGroupItem("Messages", badge=Badge("5", variant="primary"))

See Also

Bootstrap docs: https://getbootstrap.com/docs/5.3/components/list-group/

Source code in src/faststrap/components/navigation/listgroup.py

@register(category="navigation")
def ListGroupItem(
    *children: Any,
    variant: VariantType | None = None,
    active: bool = False,
    disabled: bool = False,
    action: bool = False,
    href: str | None = None,
    badge: Any = None,
    **kwargs: Any,
) -> Li | A | Button:
    """Bootstrap ListGroup Item component.

    A single item within a ListGroup.

    Args:
        *children: Item content
        variant: Bootstrap color variant for background
        active: Mark item as active/selected
        disabled: Disable the item
        action: Enable hover/focus styles (for interactive items)
        href: Make item a link (renders as <a>)
        badge: Optional badge to display on right side
        **kwargs: Additional HTML attributes

    Returns:
        FastHTML Li, A, or Button element

    Example:
        Basic item:
        >>> ListGroupItem("Simple item")

        Active with variant:
        >>> ListGroupItem("Selected", variant="primary", active=True)

        Link item:
        >>> ListGroupItem("Click me", href="/page", action=True)

        With badge:
        >>> ListGroupItem("Messages", badge=Badge("5", variant="primary"))

    See Also:
        Bootstrap docs: https://getbootstrap.com/docs/5.3/components/list-group/
    """
    # Build classes
    classes = ["list-group-item"]

    if variant:
        classes.append(f"list-group-item-{variant}")

    if active:
        classes.append("active")

    if disabled:
        classes.append("disabled")

    if action or href:
        classes.append("list-group-item-action")

    user_cls = kwargs.pop("cls", "")
    all_classes = merge_classes(" ".join(classes), user_cls)

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

    if active:
        attrs["aria-current"] = "true"

    if disabled and not href:
        attrs["aria-disabled"] = "true"

    attrs.update(convert_attrs(kwargs))

    # Build content with optional badge
    content = list(children)
    if badge:
        # Wrap content for flex layout with badge
        content = [
            Div(
                Div(*children),
                badge,
                cls="d-flex justify-content-between align-items-center w-100",
            )
        ]

    # Determine element type
    if href:
        if disabled:
            attrs["tabindex"] = "-1"
            attrs["aria-disabled"] = "true"
        return A(*content, href=href, **attrs)

    return Li(*content, **attrs)