ButtonGroup

The ButtonGroup component groups related buttons together for toolbars, segmented controls, and action sets. Creates a seamless, professional appearance by merging adjacent buttons.

Goal

Master creating button groups and toolbars, understand Bootstrap btn-group classes, and build cohesive action controls that improve UI organization.

Bootstrap Reference

Bootstrap 5 Button Group Documentation

---

Quick Start

Live Preview

Left Middle Right

from faststrap import ButtonGroup, Button

ButtonGroup(
    Button("Left", variant="primary"),
    Button("Middle", variant="primary"),
    Button("Right", variant="primary")
)

---

Visual Examples & Use Cases

1. Sizes

# Large
ButtonGroup(
    Button("One", variant="primary"),
    Button("Two", variant="primary"),
    Button("Three", variant="primary"),
    size="lg"
)

# Small
ButtonGroup(
    Button("One", variant="secondary"),
    Button("Two", variant="secondary"),
    size="sm"
)

---

2. Vertical Groups

ButtonGroup(
    Button("Top", variant="outline-primary"),
    Button("Middle", variant="outline-primary"),
    Button("Bottom", variant="outline-primary"),
    vertical=True
)

---

3. Button Toolbar - Multiple Groups

from faststrap import ButtonToolbar, ButtonGroup, Button

ButtonToolbar(
    ButtonGroup(
        Button("1"), Button("2"), Button("3"), Button("4")
    ),
    ButtonGroup(
        Button("5"), Button("6"), Button("7")
    ),
    ButtonGroup(
        Button("8")
    )
)

---

Bootstrap CSS Classes Explained

Class	Purpose
.btn-group	Horizontal button group
.btn-group-vertical	Vertical button group
.btn-group-lg	Large size
.btn-group-sm	Small size
.btn-toolbar	Groups multiple button groups

---

Common Recipes

Text Editor Toolbar

from faststrap import ButtonToolbar, ButtonGroup, Button, Icon

ButtonToolbar(
    ButtonGroup(
        Button(Icon("type-bold"), variant="outline-secondary"),
        Button(Icon("type-italic"), variant="outline-secondary"),
        Button(Icon("type-underline"), variant="outline-secondary"),
        size="sm"
    ),
    ButtonGroup(
        Button(Icon("list-ul"), variant="outline-secondary"),
        Button(Icon("list-ol"), variant="outline-secondary"),
        size="sm"
    ),
    ButtonGroup(
        Button(Icon("link"), variant="outline-secondary"),
        size="sm"
    )
)

---

Parameter Reference

Parameter	Type	Default	Description
*buttons	Any	Required	Button components
size	"sm" \| "lg" \| None	None	Group size
vertical	bool	False	Stack vertically
**kwargs	Any	-	Additional HTML attributes

faststrap.components.forms.buttongroup.ButtonGroup(*buttons, size=None, vertical=False, **kwargs)

Bootstrap ButtonGroup for grouping related buttons together.

Parameters:

Name	Type	Description	Default
*buttons	Any	Button components or elements	()
size	SizeType | None	Button group size (sm, lg)	None
vertical	bool	Stack buttons vertically	False
**kwargs	Any	Additional HTML attributes (cls, id, hx-, data-, etc.)	{}

Returns:

Type	Description
Div	FastHTML Div element with button group

Examples:

Basic group:

>>> ButtonGroup(
...     Button("Left", variant="primary"),
...     Button("Middle", variant="primary"),
...     Button("Right", variant="primary")
... )

Vertical group:

>>> ButtonGroup(
...     Button("Top"),
...     Button("Middle"),
...     Button("Bottom"),
...     vertical=True
... )

Small group:

>>> ButtonGroup(
...     Button("One"),
...     Button("Two"),
...     Button("Three"),
...     size="sm"
... )

With toggle buttons (radio-style):

>>> ButtonGroup(
...     Button("Option 1", data_bs_toggle="button"),
...     Button("Option 2", data_bs_toggle="button"),
...     Button("Option 3", data_bs_toggle="button")
... )

Note

Button groups merge adjacent buttons and remove rounded corners on inner buttons for a seamless look.

For toolbar-style layouts, wrap multiple button groups:

Div( ... ButtonGroup(Button("1"), Button("2")), ... ButtonGroup(Button("3"), Button("4")), ... cls="btn-toolbar" ... )

See Also

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

Source code in src/faststrap/components/forms/buttongroup.py

@register(category="forms")
def ButtonGroup(
    *buttons: Any,
    size: SizeType | None = None,
    vertical: bool = False,
    **kwargs: Any,
) -> Div:
    """Bootstrap ButtonGroup for grouping related buttons together.

    Args:
        *buttons: Button components or elements
        size: Button group size (sm, lg)
        vertical: Stack buttons vertically
        **kwargs: Additional HTML attributes (cls, id, hx-*, data-*, etc.)

    Returns:
        FastHTML Div element with button group

    Examples:
        Basic group:
        >>> ButtonGroup(
        ...     Button("Left", variant="primary"),
        ...     Button("Middle", variant="primary"),
        ...     Button("Right", variant="primary")
        ... )

        Vertical group:
        >>> ButtonGroup(
        ...     Button("Top"),
        ...     Button("Middle"),
        ...     Button("Bottom"),
        ...     vertical=True
        ... )

        Small group:
        >>> ButtonGroup(
        ...     Button("One"),
        ...     Button("Two"),
        ...     Button("Three"),
        ...     size="sm"
        ... )

        With toggle buttons (radio-style):
        >>> ButtonGroup(
        ...     Button("Option 1", data_bs_toggle="button"),
        ...     Button("Option 2", data_bs_toggle="button"),
        ...     Button("Option 3", data_bs_toggle="button")
        ... )

    Note:
        Button groups merge adjacent buttons and remove rounded corners
        on inner buttons for a seamless look.

        For toolbar-style layouts, wrap multiple button groups:
        >>> Div(
        ...     ButtonGroup(Button("1"), Button("2")),
        ...     ButtonGroup(Button("3"), Button("4")),
        ...     cls="btn-toolbar"
        ... )

    See Also:
        Bootstrap docs: https://getbootstrap.com/docs/5.3/components/button-group/
    """
    # Build classes
    classes = ["btn-group-vertical" if vertical else "btn-group"]

    # Add size class
    if size:
        classes.append(f"btn-group-{size}")

    # 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,
        "role": "group",
    }

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

    return Div(*buttons, **attrs)

faststrap.components.forms.buttongroup.ButtonToolbar(*groups, **kwargs)

Bootstrap ButtonToolbar for grouping multiple button groups.

Parameters:

Name	Type	Description	Default
*groups	Any	ButtonGroup components or other toolbar items	()
**kwargs	Any	Additional HTML attributes	{}

Returns:

Type	Description
Div	FastHTML Div element with button toolbar

Examples:

>>> ButtonToolbar(
...     ButtonGroup(
...         Button("1"), Button("2"), Button("3")
...     ),
...     ButtonGroup(
...         Button("4"), Button("5")
...     ),
...     ButtonGroup(
...         Button("6")
...     )
... )

See Also

Bootstrap docs: https://getbootstrap.com/docs/5.3/components/button-group/#button-toolbar

Source code in src/faststrap/components/forms/buttongroup.py

@register(category="forms")
def ButtonToolbar(
    *groups: Any,
    **kwargs: Any,
) -> Div:
    """Bootstrap ButtonToolbar for grouping multiple button groups.

    Args:
        *groups: ButtonGroup components or other toolbar items
        **kwargs: Additional HTML attributes

    Returns:
        FastHTML Div element with button toolbar

    Examples:
        >>> ButtonToolbar(
        ...     ButtonGroup(
        ...         Button("1"), Button("2"), Button("3")
        ...     ),
        ...     ButtonGroup(
        ...         Button("4"), Button("5")
        ...     ),
        ...     ButtonGroup(
        ...         Button("6")
        ...     )
        ... )

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

    # 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,
        "role": "toolbar",
    }

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

    return Div(*groups, **attrs)