Skip to content

ParallaxSection

ParallaxSection renders a CSS-only background image section with a configurable overlay. It is useful for landing pages, editorial sections, hero breaks, and showcase pages.

Quick Start

from faststrap import Button, ParallaxSection

ParallaxSection(
    Button("Explore rooms", variant="light"),
    img_src="/static/hotel.jpg",
    height="520px",
    overlay_opacity=0.45,
)

Parameters

Parameter Type Default Description
*children Any empty Content centered inside the section overlay.
img_src str required Background image URL.
height str \| None 500px Section height.
overlay_opacity float \| None 0.5 Overlay opacity clamped between 0 and 1.

Notes

  • Mobile browsers often handle background-attachment: fixed poorly, so Faststrap automatically falls back to normal scrolling below 768px.
  • faststrap-visual.css is loaded automatically by add_bootstrap().
  • Treat img_src like any other image URL: pass trusted/static paths, not unescaped user input.

API Reference

faststrap.components.layout.parallax.ParallaxSection(*children, img_src, height=UNSET, overlay_opacity=UNSET, **kwargs)

Render a CSS-only parallax-style background section.

Source code in src/faststrap/components/layout/parallax.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
@register(category="layout")
@beta
def ParallaxSection(
    *children: Any,
    img_src: str,
    height: str | None = UNSET,
    overlay_opacity: float | None = UNSET,
    **kwargs: Any,
) -> Div:
    """Render a CSS-only parallax-style background section."""
    cfg = resolve_defaults(
        "ParallaxSection",
        height=height,
        overlay_opacity=overlay_opacity,
    )
    c_height = cfg.get("height") or "500px"
    c_opacity = cfg.get("overlay_opacity")
    if c_opacity is None:
        c_opacity = 0.5
    c_opacity = min(1.0, max(0.0, float(c_opacity)))

    user_cls = kwargs.pop("cls", "")
    user_style = kwargs.pop("style", "")
    base_style = f"background-image: url('{img_src}'); height: {c_height};"
    if isinstance(user_style, str) and user_style.strip():
        base_style = f"{base_style} {user_style.strip()}"

    attrs: dict[str, Any] = {
        "cls": merge_classes("faststrap-parallax-section", user_cls),
        "style": base_style,
    }
    attrs.update(convert_attrs(kwargs))

    return Div(
        Div(
            *children,
            cls="faststrap-parallax-overlay",
            style=f"--faststrap-parallax-overlay-opacity: {c_opacity};",
        ),
        **attrs,
    )