Skip to content

Aspect Ratio

The AspectRatio component renders content in a responsive container constrained to a specific aspect ratio.

Quick Start

AspectRatio(
    Img(src="/hero.jpg", cls="img-fluid"),
    ratio="16/9",
)

Usage Scenarios

Video Embed

AspectRatio(
    Iframe(src="https://www.youtube.com/embed/dQw4w9WgXcQ", cls="border-0"),
    ratio="16/9",
)

Square Image

AspectRatio(
    Img(src="/avatar.jpg", cls="img-fluid"),
    ratio="1/1",
)

Ultra-Wide Banner

AspectRatio(
    Img(src="/banner.jpg", cls="img-fluid"),
    ratio="21/9",
)

Classic 4:3

AspectRatio(
    Img(src="/presentation.jpg", cls="img-fluid"),
    ratio="4/3",
)

Parameter Reference

Parameter Type Default Description
children Any Required Content to display (images, videos, iframes, etc.)
ratio str "16/9" Aspect ratio as width/height string (e.g. "16/9", "4/3", "1/1", "21/9")
**kwargs Any - Additional HTML attributes (cls, id, hx-, data-, etc.)

Accessibility

  • Ensure child media elements (images, iframes) have appropriate alt text or titles.
  • Use object-fit: cover on images for best visual results within the constrained container.

API Reference

faststrap.components.layout.aspect_ratio.AspectRatio(children, *, ratio='16/9', **kwargs)

Render content in a responsive aspect ratio container.

Uses the CSS aspect-ratio property for consistent sizing across viewports. Children fill the container; use object-fit on child media for best results.

Parameters:

Name Type Description Default
children Any

Content to display (images, videos, iframes, etc.)

 required
ratio str

Aspect ratio as width/height string (e.g. "16/9", "4/3", "1/1", "21/9")

 '16/9'
**kwargs Any

Additional HTML attributes (cls, id, hx-, data-, etc.)

 {}

Returns:

Type Description
Div

FastHTML Div element constrained to the specified aspect ratio
Source code in src/faststrap/components/layout/aspect_ratio.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
54
@register(category="layout")
@stable
def AspectRatio(
    children: Any,
    *,
    ratio: str = "16/9",
    **kwargs: Any,
) -> Div:
    """Render content in a responsive aspect ratio container.

    Uses the CSS aspect-ratio property for consistent sizing across viewports.
    Children fill the container; use object-fit on child media for best results.

    Args:
        children: Content to display (images, videos, iframes, etc.)
        ratio: Aspect ratio as width/height string (e.g. "16/9", "4/3", "1/1", "21/9")
        **kwargs: Additional HTML attributes (cls, id, hx-*, data-*, etc.)

    Returns:
        FastHTML Div element constrained to the specified aspect ratio
    """
    user_cls = kwargs.pop("cls", "")

    classes = ["overflow-hidden"]

    style = f"aspect-ratio: {ratio};"

    attrs: dict[str, Any] = {
        "cls": merge_classes(" ".join(classes), user_cls),
        "style": style,
    }
    attrs.update(convert_attrs(kwargs))

    # Wrap children in a container that fills the aspect ratio box
    inner = Div(
        children,
        style="width: 100%; height: 100%;",
    )

    return Div(inner, **attrs)