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

Example

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

    Example:
        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

Example

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

    Example:
        >>> 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)