Aspect Ratio

A container that maintains a fixed aspect ratio. Useful for images, videos, maps, and embeds.

Basic Usage

Image constrained to 16:9

<x-wirekit::aspect-ratio style="max-width: 600px">
    <img src="/_assets/sample_1280x720_80p.jpg" alt="Landscape photo" style="width: 100%; height: 100%; object-fit: cover;" />
</x-wirekit::aspect-ratio>

Common Ratios

Different ratios with the same image

16:9 (default)

4:3

1:1 (square)

<x-wirekit::row gap="lg" style="align-items: start;">
    <x-wirekit::stack gap="sm" style="flex: 1; min-width: 0;">
        <x-wirekit::aspect-ratio>
            <img src="/_assets/sample_1280x720_80p.jpg" alt="16:9 landscape" style="width: 100%; height: 100%; object-fit: cover;" />
        </x-wirekit::aspect-ratio>
        <x-wirekit::text intent="muted" size="sm">16:9 (default)</x-wirekit::text>
    </x-wirekit::stack>
    <x-wirekit::stack gap="sm" style="flex: 1; min-width: 0;">
        <x-wirekit::aspect-ratio ratio="4/3">
            <img src="/_assets/sample_1280x720_80p.jpg" alt="4:3 landscape" style="width: 100%; height: 100%; object-fit: cover;" />
        </x-wirekit::aspect-ratio>
        <x-wirekit::text intent="muted" size="sm">4:3</x-wirekit::text>
    </x-wirekit::stack>
    <x-wirekit::stack gap="sm" style="flex: 1; min-width: 0;">
        <x-wirekit::aspect-ratio ratio="1/1">
            <img src="/_assets/sample_1280x720_80p.jpg" alt="1:1 square" style="width: 100%; height: 100%; object-fit: cover;" />
        </x-wirekit::aspect-ratio>
        <x-wirekit::text intent="muted" size="sm">1:1 (square)</x-wirekit::text>
    </x-wirekit::stack>
</x-wirekit::row>

Portrait and Ultrawide

Portrait and ultrawide ratios

3:4 (portrait)

21:9 (ultrawide)

<x-wirekit::row gap="lg" style="align-items: start;">
    <x-wirekit::stack gap="sm" style="max-width: 200px; min-width: 0;">
        <x-wirekit::aspect-ratio ratio="3/4">
            <img src="/_assets/sample_768x1024_80p.jpg" alt="3:4 portrait" style="width: 100%; height: 100%; object-fit: cover;" />
        </x-wirekit::aspect-ratio>
        <x-wirekit::text intent="muted" size="sm">3:4 (portrait)</x-wirekit::text>
    </x-wirekit::stack>
    <x-wirekit::stack gap="sm" style="flex: 1; min-width: 8rem;">
        <x-wirekit::aspect-ratio ratio="21/9">
            <img src="/_assets/sample_1280x548_80p.jpg" alt="21:9 ultrawide" style="width: 100%; height: 100%; object-fit: cover;" />
        </x-wirekit::aspect-ratio>
        <x-wirekit::text intent="muted" size="sm">21:9 (ultrawide)</x-wirekit::text>
    </x-wirekit::stack>
</x-wirekit::row>

Props

Prop	Type	Default	Description
`ratio`	string\|number	`'16/9'`	Aspect ratio value, e.g. `"16/9"`, `"4/3"`, `"1/1"`, or `1.5`
`scope`	string\|null	`null`	Scoped personalization name

The component renders as a <div> with overflow-hidden and position: relative. The native CSS aspect-ratio property handles the sizing. Children (images, videos, embeds) should use object-fit: cover and width: 100%; height: 100% to fill the container.

In a row or a grid of columns, give each column that holds a box min-width: 0, as the previews above do. A flex or grid item does not shrink below the width of its content, and Safari and every other browser on iOS keep measuring that content at the width the column had before the window narrowed. A phone turned upright then leaves the columns wider than the screen. A grid already gives the columns it builds from cols a minimum of zero.

Zero suits a column that holds only a box. A column with a caption under its box cannot shrink past the caption's longest word, so give it a floor that carries the caption, as the ultrawide column in the second preview does with min-width: 8rem. A floor set as a length does not depend on the image, so the narrowing problem above does not reach it.

Keyboard Interaction

This component is a layout wrapper. Keyboard interaction is delegated to its children.