Grid

The Container, Row, and Col components implement the Bootstrap 5 responsive grid system.

Quick Start

Container(
    Row(
        Col("Column 1", span=6),
        Col("Column 2", span=6),
    )
)

Usage Scenarios

Fixed-Width Container

Container(H1("Welcome"), P("Content"))

Fluid Container

Container(Row(...), fluid=True)

Fluid Until Breakpoint

Container(content, fluid="lg")

Responsive Row

Row(
    Col("A", span=12, cols_md=6, cols_lg=4),
    Col("B", span=12, cols_md=6, cols_lg=4),
    Col("C", span=12, cols_md=6, cols_lg=4),
)

Column with Offset

Col("Offset by 3", span=6, offset=3)

Responsive Column Sizing

Col("Content", span=12, md=6, lg=4, xl=3)

Parameter Reference

Container

Parameter	Type	Default	Description
*children	Any	Required	Container content
fluid	bool \| str	False	Fluid container type (True/"fluid" for full-width, "sm"/"md"/"lg"/"xl"/"xxl" for fluid until breakpoint)
**kwargs	Any	-	Additional HTML attributes

Row

Parameter	Type	Default	Description
*children	Any	Required	Row content (typically Col components)
cols	int \| None	None	Number of columns for all breakpoints (1-12)
cols_sm	int \| None	None	Columns for small devices (≥576px)
cols_md	int \| None	None	Columns for medium devices (≥768px)
cols_lg	int \| None	None	Columns for large devices (≥992px)
cols_xl	int \| None	None	Columns for extra large devices (≥1200px)
cols_xxl	int \| None	None	Columns for extra extra large devices (≥1400px)
**kwargs	Any	-	Additional HTML attributes

Col

Parameter	Type	Default	Description
*children	Any	Required	Column content
span	int \| bool	True	Column span (1-12) or True for auto-width
sm	int \| None	None	Span for small devices (≥576px)
md	int \| None	None	Span for medium devices (≥768px)
lg	int \| None	None	Span for large devices (≥992px)
xl	int \| None	None	Span for extra large devices (≥1200px)
xxl	int \| None	None	Span for extra extra large devices (≥1400px)
offset	int \| None	None	Offset columns (0-11)
offset_sm	int \| None	None	Offset for small devices
offset_md	int \| None	None	Offset for medium devices
offset_lg	int \| None	None	Offset for large devices
offset_xl	int \| None	None	Offset for extra large devices
offset_xxl	int \| None	None	Offset for extra extra large devices
**kwargs	Any	-	Additional HTML attributes

Accessibility

• Grid is purely structural and does not add accessibility barriers.
• Content within columns maintains proper heading hierarchy.

API Reference

faststrap.components.layout.grid.Container(*children, fluid=False, **kwargs)

Bootstrap Container for responsive fixed-width or fluid layouts.

Parameters:

Name	Type	Description	Default
*children	Any	Container content	()
fluid	ContainerType | bool	Fluid container type: - False: Fixed-width responsive container (default) - True/"fluid": Full-width container - "sm"/"md"/"lg"/"xl"/"xxl": Fluid until breakpoint	False
**kwargs	Any	Additional HTML attributes (cls, id, hx-, data-, etc.)	{}

Returns:

Type	Description
Div	FastHTML Div element with container classes

Examples:

Fixed-width responsive:

>>> Container(H1("Welcome"), P("Content"))

Full-width fluid:

>>> Container(Row(...), fluid=True)

Fluid until large breakpoint:

>>> Container(content, fluid="lg")

See Also

Bootstrap docs: https://getbootstrap.com/docs/5.3/layout/containers/

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

@register(category="layout")
@stable
def Container(
    *children: Any,
    fluid: ContainerType | bool = False,
    **kwargs: Any,
) -> Div:
    """Bootstrap Container for responsive fixed-width or fluid layouts.

    Args:
        *children: Container content
        fluid: Fluid container type:
            - False: Fixed-width responsive container (default)
            - True/"fluid": Full-width container
            - "sm"/"md"/"lg"/"xl"/"xxl": Fluid until breakpoint
        **kwargs: Additional HTML attributes (cls, id, hx-*, data-*, etc.)

    Returns:
        FastHTML Div element with container classes

    Examples:
        Fixed-width responsive:
        >>> Container(H1("Welcome"), P("Content"))

        Full-width fluid:
        >>> Container(Row(...), fluid=True)

        Fluid until large breakpoint:
        >>> Container(content, fluid="lg")

    See Also:
        Bootstrap docs: https://getbootstrap.com/docs/5.3/layout/containers/
    """
    # Build container class
    if fluid is True or fluid == "fluid":
        container_cls = "container-fluid"
    elif fluid:
        container_cls = f"container-{fluid}"
    else:
        container_cls = "container"

    # Merge with user classes
    user_cls = kwargs.pop("cls", "")
    all_classes = merge_classes(container_cls, user_cls)

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

    return Div(*children, **attrs)

faststrap.components.layout.grid.Row(*children, cols=None, cols_sm=None, cols_md=None, cols_lg=None, cols_xl=None, cols_xxl=None, **kwargs)

Bootstrap Row for grid layout.

Parameters:

Name	Type	Description	Default
*children	Any	Row content (typically Col components)	()
cols	int | None	Number of columns for all breakpoints (1-12)	None
cols_sm	int | None	Columns for small devices (≥576px)	None
cols_md	int | None	Columns for medium devices (≥768px)	None
cols_lg	int | None	Columns for large devices (≥992px)	None
cols_xl	int | None	Columns for extra large devices (≥1200px)	None
cols_xxl	int | None	Columns for extra extra large devices (≥1400px)	None
**kwargs	Any	Additional HTML attributes	{}

Returns:

Type	Description
Div	FastHTML Div element with row classes

Examples:

Basic row:

>>> Row(Col("Column 1"), Col("Column 2"))

Auto-layout 3 equal columns:

>>> Row(Col(...), Col(...), Col(...), cols=3)

Responsive columns:

>>> Row(children, cols=1, cols_md=2, cols_lg=3)

See Also

Bootstrap docs: https://getbootstrap.com/docs/5.3/layout/grid/

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

@register(category="layout")
@stable
def Row(
    *children: Any,
    cols: int | None = None,
    cols_sm: int | None = None,
    cols_md: int | None = None,
    cols_lg: int | None = None,
    cols_xl: int | None = None,
    cols_xxl: int | None = None,
    **kwargs: Any,
) -> Div:
    """Bootstrap Row for grid layout.

    Args:
        *children: Row content (typically Col components)
        cols: Number of columns for all breakpoints (1-12)
        cols_sm: Columns for small devices (≥576px)
        cols_md: Columns for medium devices (≥768px)
        cols_lg: Columns for large devices (≥992px)
        cols_xl: Columns for extra large devices (≥1200px)
        cols_xxl: Columns for extra extra large devices (≥1400px)
        **kwargs: Additional HTML attributes

    Returns:
        FastHTML Div element with row classes

    Examples:
        Basic row:
        >>> Row(Col("Column 1"), Col("Column 2"))

        Auto-layout 3 equal columns:
        >>> Row(Col(...), Col(...), Col(...), cols=3)

        Responsive columns:
        >>> Row(children, cols=1, cols_md=2, cols_lg=3)

    See Also:
        Bootstrap docs: https://getbootstrap.com/docs/5.3/layout/grid/
    """
    # Build classes
    classes = ["row"]

    # Add responsive column classes
    if cols:
        classes.append(f"row-cols-{cols}")
    if cols_sm:
        classes.append(f"row-cols-sm-{cols_sm}")
    if cols_md:
        classes.append(f"row-cols-md-{cols_md}")
    if cols_lg:
        classes.append(f"row-cols-lg-{cols_lg}")
    if cols_xl:
        classes.append(f"row-cols-xl-{cols_xl}")
    if cols_xxl:
        classes.append(f"row-cols-xxl-{cols_xxl}")

    # 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}
    attrs.update(convert_attrs(kwargs))

    return Div(*children, **attrs)

faststrap.components.layout.grid.Col(*children, span=True, sm=None, md=None, lg=None, xl=None, xxl=None, offset=None, offset_sm=None, offset_md=None, offset_lg=None, offset_xl=None, offset_xxl=None, **kwargs)

Bootstrap Column for grid layout.

Parameters:

Name	Type	Description	Default
*children	Any	Column content	()
span	int | bool	Column span (1-12) or True for auto-width	True
sm	int | None	Span for small devices (≥576px)	None
md	int | None	Span for medium devices (≥768px)	None
lg	int | None	Span for large devices (≥992px)	None
xl	int | None	Span for extra large devices (≥1200px)	None
xxl	int | None	Span for extra extra large devices (≥1400px)	None
offset	int | None	Offset columns (0-11)	None
offset_sm	int | None	Offset for small devices	None
offset_md	int | None	Offset for medium devices	None
offset_lg	int | None	Offset for large devices	None
offset_xl	int | None	Offset for extra large devices	None
offset_xxl	int | None	Offset for extra extra large devices	None
**kwargs	Any	Additional HTML attributes	{}

Returns:

Type	Description
Div	FastHTML Div element with column classes

Examples:

Auto-width column:

>>> Col("Auto width")

Fixed span:

>>> Col("Half width", span=6)

Responsive sizing:

>>> Col("Content", span=12, md=6, lg=4)

With offset:

>>> Col("Offset by 3", span=6, offset=3)

See Also

Bootstrap docs: https://getbootstrap.com/docs/5.3/layout/columns/

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

@register(category="layout")
@stable
def Col(
    *children: Any,
    span: int | bool = True,
    sm: int | None = None,
    md: int | None = None,
    lg: int | None = None,
    xl: int | None = None,
    xxl: int | None = None,
    offset: int | None = None,
    offset_sm: int | None = None,
    offset_md: int | None = None,
    offset_lg: int | None = None,
    offset_xl: int | None = None,
    offset_xxl: int | None = None,
    **kwargs: Any,
) -> Div:
    """Bootstrap Column for grid layout.

    Args:
        *children: Column content
        span: Column span (1-12) or True for auto-width
        sm: Span for small devices (≥576px)
        md: Span for medium devices (≥768px)
        lg: Span for large devices (≥992px)
        xl: Span for extra large devices (≥1200px)
        xxl: Span for extra extra large devices (≥1400px)
        offset: Offset columns (0-11)
        offset_sm: Offset for small devices
        offset_md: Offset for medium devices
        offset_lg: Offset for large devices
        offset_xl: Offset for extra large devices
        offset_xxl: Offset for extra extra large devices
        **kwargs: Additional HTML attributes

    Returns:
        FastHTML Div element with column classes

    Examples:
        Auto-width column:
        >>> Col("Auto width")

        Fixed span:
        >>> Col("Half width", span=6)

        Responsive sizing:
        >>> Col("Content", span=12, md=6, lg=4)

        With offset:
        >>> Col("Offset by 3", span=6, offset=3)

    See Also:
        Bootstrap docs: https://getbootstrap.com/docs/5.3/layout/columns/
    """
    # Build classes
    classes = []

    # Add base column class
    if span is True:
        classes.append("col")
    elif isinstance(span, int):
        classes.append(f"col-{span}")

    # Add responsive classes
    if sm:
        classes.append(f"col-sm-{sm}")
    if md:
        classes.append(f"col-md-{md}")
    if lg:
        classes.append(f"col-lg-{lg}")
    if xl:
        classes.append(f"col-xl-{xl}")
    if xxl:
        classes.append(f"col-xxl-{xxl}")

    # Add offset classes
    if offset:
        classes.append(f"offset-{offset}")
    if offset_sm:
        classes.append(f"offset-sm-{offset_sm}")
    if offset_md:
        classes.append(f"offset-md-{offset_md}")
    if offset_lg:
        classes.append(f"offset-lg-{offset_lg}")
    if offset_xl:
        classes.append(f"offset-xl-{offset_xl}")
    if offset_xxl:
        classes.append(f"offset-xxl-{offset_xxl}")

    # 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}
    attrs.update(convert_attrs(kwargs))

    return Div(*children, **attrs)