Grid System

Bootstrap's grid system uses a series of containers, rows, and columns to layout and align content. It's built with flexbox and is fully responsive. FastStrap mirrors this with Container, Row, and Col.

Bootstrap Reference

Bootstrap 5 Grid System Documentation

Quick Start

The grid follows a 12-column system.

Live Preview

Left (4/12)

Center (4/12)

Right (4/12)

Container(
    Row(
        Col("Left Column", width=4),
        Col("Center Column", width=4),
        Col("Right Column", width=4)
    )
)

![Screenshot: A three-column layout with equal widths](../../assets/images/grid-basic.png)

Visual Examples & Use Cases

1. Responsive Breakpoints

You can specify different widths for different screen sizes (sm, md, lg, xl, xxl).

Code & Output

Live Preview (Responsive)

Item 1

Item 2

Item 3

# 1 column on mobile, 2 on tablet, 3 on desktop
Row(
    Col("Item 1", width=12, md=6, lg=4),
    Col("Item 2", width=12, md=6, lg=4),
    Col("Item 3", width=12, md=12, lg=4)
)

2. Alignment & Spacing (Gutter)

Bootstrap's Flexbox utilities are available through the Row and Col arguments.

Code & Output

Live Preview (Centered)

I am centered

# Centered Row with gap (gutter) level 4
Row(
    Col("I am centered", width=6),
    justify="center",
    gutter=4
)

3. Container Fluid

By default, Container has a fixed width that changes at each breakpoint. Use fluid=True for a container that is always 100% wide.

Container("Full width content", fluid=True)

Practical Functionality

1. Auto-width Columns

If you don't specify a width, Col will automatically share the space with other sibling columns.

Row(
    Col("Variable width"),
    Col("Variable width"),
    Col("Variable width")
)

2. Offsetting Columns

Move columns to the right using offset.

Row(
    Col("Centered offset", width=6, offset=3)
)

Parameter Reference

Container

Param	Type	Bootstrap Class	Description
`fluid`	`bool`	`.container-fluid`	Spans the full width of the viewport.

Row

Param	Type	Bootstrap Class	Description
`gutter`	`int`	`.g-{val}`	Spacing between columns (0-5).
`gx`	`int`	`.gx-{val}`	Horizontal gutter only.
`gy`	`int`	`.gy-{val}`	Vertical gutter only.
`justify`	`str`	`.justify-content-{val}`	Alignment: `start`, `center`, `end`, `around`, `between`.
`align`	`str`	`.align-items-{val}`	Vertical alignment: `start`, `center`, `end`.

Col

Param	Type	Bootstrap Class	Description
`width`	`int`	`.col-{val}`	Mobile/default width (1-12).
`sm`	`int`	`.col-sm-{val}`	Tablet width.
`md`	`int`	`.col-md-{val}`	Desktop width.
`lg`	`int`	`.col-lg-{val}`	Large screen width.
`offset`	`int`	`.offset-{val}`	Prepend empty columns.

`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

Example

Fixed-width responsive:

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

Full-width fluid:

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

Fluid until large breakpoint:

Container(content, fluid="lg")

`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

Example

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)

`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

Example

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

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