Separator

Separator renders a semantic divider for visually grouping content. It supports horizontal and vertical orientations, optional centered labels, and configurable thickness and spacing.

Bootstrap Reference

Bootstrap 5 Dividers

---

Quick Start

from faststrap import Separator

# Horizontal divider
Separator()

# Vertical divider
Separator(orientation="vertical")

# Labeled divider
Separator(label="Section")

---

Visual Examples & Use Cases

1. Horizontal Separator

Live Preview

Content above

Content below

Separator()

2. Vertical Separator

Live Preview

Left Right

Separator(orientation="vertical")

3. Labeled Separator

Live Preview

OR

Separator(label="OR")

4. Custom Thickness and Spacing

Live Preview

Above

Below

Separator(thickness=3, spacing=3)

---

Practical Functionality

1. Inside a Card

Card(
    Card.Header("Settings"),
    Card.Body(
        Separator(label="General"),
        # ... general settings
        Separator(label="Security"),
        # ... security settings
    ),
)

2. Inside a Stack

Stack(
    "First item",
    Separator(),
    "Second item",
    Separator(),
    "Third item",
    gap=2,
)

3. Vertical Separator in a Toolbar

Cluster(
    Button("Save", variant="primary"),
    Separator(orientation="vertical"),
    Button("Cancel", variant="secondary"),
    Separator(orientation="vertical"),
    Button("Delete", variant="danger"),
)

---

Parameter Reference

Parameter	Type	Default	Description
orientation	"horizontal" \| "vertical"	"horizontal"	Divider orientation.
thickness	int \| None	None	Border width in pixels (default: 1).
spacing	int \| None	None	Margin in Bootstrap spacing units (0–5).
label	str \| None	None	Centered text label on the divider.
**kwargs	Any	{}	Additional HTML attributes (cls, id, etc.).

---

Accessibility

• Renders role="separator" on the wrapper element.
• Sets aria-orientation to match the orientation parameter.
• When label is provided, the text is wrapped in a <span> for screen readers.

---

API Reference

faststrap.components.layout.separator.Separator(*, orientation='horizontal', thickness=None, spacing=None, label=None, **kwargs)

Render a semantic separator/divider.

Parameters:

Name	Type	Description	Default
orientation	Literal['horizontal', 'vertical']	horizontal (default) or vertical	'horizontal'
thickness	int | None	border width in px (default: 1)	None
spacing	int | None	margin in Bootstrap spacing units (0-5)	None
label	str | None	optional text label centered on the divider	None
**kwargs	Any	Additional HTML attributes (cls, id, hx-, data-, etc.)	{}

Returns:

Type	Description
Div	FastHTML Div element with separator styling

Source code in src/faststrap/components/layout/separator.py

@register(category="layout")
@stable
def Separator(
    *,
    orientation: Literal["horizontal", "vertical"] = "horizontal",
    thickness: int | None = None,
    spacing: int | None = None,
    label: str | None = None,
    **kwargs: Any,
) -> Div:
    """Render a semantic separator/divider.

    Args:
        orientation: horizontal (default) or vertical
        thickness: border width in px (default: 1)
        spacing: margin in Bootstrap spacing units (0-5)
        label: optional text label centered on the divider
        **kwargs: Additional HTML attributes (cls, id, hx-*, data-*, etc.)

    Returns:
        FastHTML Div element with separator styling
    """
    user_cls = kwargs.pop("cls", "")

    if orientation == "vertical":
        classes = ["vr"]
        style_parts = ["display: inline-block; width: 1px;"]
        if thickness is not None:
            style_parts.append(f"width: {thickness}px;")
        if spacing is not None:
            style_parts.append(f"margin-inline: {spacing * 0.25}rem;")
        attrs: dict[str, Any] = {
            "cls": merge_classes(" ".join(classes), user_cls),
            "role": "separator",
            "aria-orientation": "vertical",
            "style": " ".join(style_parts),
        }
        attrs.update(convert_attrs(kwargs))
        return Div(**attrs)
    else:
        if label:
            # Labeled divider: line — text — line
            line_cls = merge_classes("flex-grow-1 border", user_cls)
            label_cls = "px-2 text-muted small"
            style_parts = ["border-top-width: 1px;"]
            if thickness is not None:
                style_parts.append(f"border-top-width: {thickness}px;")
            if spacing is not None:
                style_parts.append(f"margin-block: {spacing * 0.25}rem;")

            attrs = {
                "cls": "d-flex align-items-center",
                "role": "separator",
                "aria-orientation": "horizontal",
            }
            if spacing is not None:
                attrs["style"] = " ".join(style_parts)
            attrs.update(convert_attrs(kwargs))

            return Div(
                Div(cls=line_cls),
                Span(label, cls=label_cls),
                Div(cls=line_cls),
                **attrs,
            )
        else:
            # Simple divider
            classes = ["border-top"]
            if spacing is not None:
                classes.append(f"my-{spacing}")
            attrs = {
                "cls": merge_classes(" ".join(classes), user_cls),
                "role": "separator",
                "aria-orientation": "horizontal",
            }
            if thickness is not None:
                attrs["style"] = f"border-top-width: {thickness}px;"
            attrs.update(convert_attrs(kwargs))
            return Div(**attrs)