---
title: Aspect Ratio
description: Constrained aspect ratio wrapper
visibility: guest
draft: false
---

# Aspect Ratio

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

## Basic Usage

:::preview{title="Image constrained to 16:9"}
<x-wirekit::aspect-ratio style="max-width: 600px">
    <img src="/_assets/sample_1920x1080_98p.jpg" alt="Landscape photo" style="width: 100%; height: 100%; object-fit: cover;" />
</x-wirekit::aspect-ratio>
:::

## Common Ratios

:::preview{title="Different ratios with the same image"}
<x-wirekit::row gap="lg" style="align-items: start;">
    <x-wirekit::stack gap="sm" style="flex: 1;">
        <x-wirekit::aspect-ratio>
            <img src="/_assets/sample_1920x1080_98p.jpg" alt="16:9 landscape" style="width: 100%; height: 100%; object-fit: cover;" />
        </x-wirekit::aspect-ratio>
        <x-wirekit::text variant="muted" size="sm">16:9 (default)</x-wirekit::text>
    </x-wirekit::stack>
    <x-wirekit::stack gap="sm" style="flex: 1;">
        <x-wirekit::aspect-ratio ratio="4/3">
            <img src="/_assets/sample_1920x1080_98p.jpg" alt="4:3 landscape" style="width: 100%; height: 100%; object-fit: cover;" />
        </x-wirekit::aspect-ratio>
        <x-wirekit::text variant="muted" size="sm">4:3</x-wirekit::text>
    </x-wirekit::stack>
    <x-wirekit::stack gap="sm" style="flex: 1;">
        <x-wirekit::aspect-ratio ratio="1/1">
            <img src="/_assets/sample_1920x1080_98p.jpg" alt="1:1 square" style="width: 100%; height: 100%; object-fit: cover;" />
        </x-wirekit::aspect-ratio>
        <x-wirekit::text variant="muted" size="sm">1:1 (square)</x-wirekit::text>
    </x-wirekit::stack>
</x-wirekit::row>
:::

## Portrait and Ultrawide

:::preview{title="Portrait and ultrawide ratios"}
<x-wirekit::row gap="lg" style="align-items: start;">
    <x-wirekit::stack gap="sm" style="max-width: 200px;">
        <x-wirekit::aspect-ratio ratio="3/4">
            <img src="/_assets/sample_840x1120_98p.jpg" alt="3:4 portrait" style="width: 100%; height: 100%; object-fit: cover;" />
        </x-wirekit::aspect-ratio>
        <x-wirekit::text variant="muted" size="sm">3:4 (portrait)</x-wirekit::text>
    </x-wirekit::stack>
    <x-wirekit::stack gap="sm" style="flex: 1;">
        <x-wirekit::aspect-ratio ratio="21/9">
            <img src="/_assets/sample_1920x823_98p.jpg" alt="21:9 ultrawide" style="width: 100%; height: 100%; object-fit: cover;" />
        </x-wirekit::aspect-ratio>
        <x-wirekit::text variant="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.

## Keyboard Interaction

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