Skip to content

FormSection

FormSection groups related form fields under an optional title, description, divider, and action row.

Quick Start

from faststrap import Button, FormSection, Input

FormSection(
    Input(name="name", label="Name"),
    Input(name="email", label="Email", type="email"),
    title="Profile",
    description="Public account details.",
    actions=Button("Save", variant="primary"),
)

Parameters

Name Type Default Description
*fields Any required Field components or arbitrary content.
title str | None None Section heading.
description str | None None Muted helper copy below the heading.
actions Any | list[Any] | tuple[Any, ...] | None None Right-aligned section actions.
divider bool True Adds a top border and spacing before the section.
**kwargs Any {} Additional HTML/HTMX/data/ARIA attributes.

Notes

  • Use divider=False for the first section in a form.
  • FormSection is layout-only; validation still belongs to FormGroup, LiveValidationField, and server-side form handling.

API Reference

faststrap.components.forms.form_section.FormSection(*fields, title=None, description=None, actions=None, divider=True, **kwargs)

Group related form controls under a section heading.

Source code in src/faststrap/components/forms/form_section.py 
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
@register(category="forms")
@beta
def FormSection(
    *fields: Any,
    title: str | None = None,
    description: str | None = None,
    actions: Any | list[Any] | tuple[Any, ...] | None = None,
    divider: bool = True,
    **kwargs: Any,
) -> Div:
    """Group related form controls under a section heading."""
    user_cls = kwargs.pop("cls", "")

    children: list[Any] = []
    if title or description:
        header_children: list[Any] = []
        if title:
            header_children.append(H3(title, cls="h5 mb-1"))
        if description:
            header_children.append(P(description, cls="text-muted mb-0"))
        children.append(Div(*header_children, cls="mb-3"))

    children.append(Div(*fields, cls="d-grid gap-3"))

    if actions is not None:
        action_children = list(actions) if isinstance(actions, (list, tuple)) else [actions]
        children.append(
            Div(*action_children, cls="d-flex flex-wrap gap-2 justify-content-end mt-3")
        )

    attrs: dict[str, Any] = {
        "cls": merge_classes(
            "faststrap-form-section",
            "border-top pt-4 mt-4" if divider else "",
            user_cls,
        )
    }
    attrs.update(convert_attrs(kwargs))
    return Div(*children, **attrs)