Skip to content

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)

Prefer Row(..., cols=...) when you want evenly sized cards or repeated items, and define the mobile layout first.

Row(
    Card("Revenue"),
    Card("Retention"),
    Card("Pipeline"),
    cols=1,
    cols_md=2,
    cols_lg=3,
    gutter=3,
)

This makes the intended stack explicit:

  • mobile: 1 item per row
  • tablet: 2 items per row
  • desktop: 3 items per row

Use custom cls="row ..." only when you specifically need raw Bootstrap row behavior that is not already covered by Row() arguments.

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

You can also control equal-width card grids at the row level:

Row(
    Card("Item 1"),
    Card("Item 2"),
    Card("Item 3"),
    cols=1,
    cols_md=2,
    cols_lg=3,
)

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
cols int .row-cols-{val} Equal columns for the default/mobile layout.
cols_sm int .row-cols-sm-{val} Equal columns from the sm breakpoint upward.
cols_md int .row-cols-md-{val} Equal columns from the md breakpoint upward.
cols_lg int .row-cols-lg-{val} Equal columns from the lg breakpoint upward.
cols_xl int .row-cols-xl-{val} Equal columns from the xl breakpoint upward.
cols_xxl int .row-cols-xxl-{val} Equal columns from the xxl breakpoint upward.
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
span int \| bool .col / .col-{val} Auto width when True, or a specific mobile/default span (1-12).
sm int .col-sm-{val} Width from the sm breakpoint upward.
md int .col-md-{val} Width from the md breakpoint upward.
lg int .col-lg-{val} Width from the lg breakpoint upward.
xl int .col-xl-{val} Width from the xl breakpoint upward.
xxl int .col-xxl-{val} Width from the xxl breakpoint upward.
offset int .offset-{val} Prepend empty columns.
offset_sm int .offset-sm-{val} Offset from the sm breakpoint upward.
offset_md int .offset-md-{val} Offset from the md breakpoint upward.
offset_lg int .offset-lg-{val} Offset from the lg breakpoint upward.
offset_xl int .offset-xl-{val} Offset from the xl breakpoint upward.
offset_xxl int .offset-xxl-{val} Offset from the xxl breakpoint upward.

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 
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
54
55
56
57
58
59
60
61
62
63
64
65
@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 
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
@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 
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
@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)