Aspect Ratio | astryx-vue

Usage

AspectRatio keeps a fixed width-to-height ratio as its container changes size. Use it for images, video, thumbnails, and other media that should stay in proportion. The width comes from the parent, and the height is derived from ratio, so an ancestor needs a definite width.

vue

<script setup lang="ts">
import { AspectRatio } from '@astryx-vue/core/AspectRatio'
</script>

<template>
  <AspectRatio :ratio="16 / 9" fit="cover">
    <img alt="Landscape" src="/photo.jpg">
  </AspectRatio>
</template>

ratio is width divided by height. Write 16 / 9 rather than a rounded decimal. shape is rectangle or ellipse; an ellipse with ratio 1 is a circle. fit sizes the child: cover fills and crops, contain letterboxes, and center keeps the natural size. Leave fit unset when the child sizes itself.

The ratio is written to the CSS variable --astryx-aspect-ratio, not as an inline aspect-ratio declaration, so a stylesheet can override it.

Anatomy

Element	Description
Ratio box	The outer element that holds the aspect ratio and clips overflow. Carries the `astryx-aspect-ratio` theme target, and the elliptical clip when `shape` is `ellipse`.
Content slot	A wrapper that fills the ratio box and positions the child. With `fit` set it also sizes the child; without it the child styles itself.

Best practices

Guidance	Practices
Do	Pass one child when `fit` is set. Every direct child is stretched, so put an overlay inside that child.
Do	Give images an `alt`, or `alt=""` when the image is decorative. The ratio box adds no accessible name of its own.
Don't	Use it as a general layout container. Use `Section`, `Card`, or `Layout` for page regions.
Don't	Set only a height. The width comes from the container, so a lone height clamps the box off ratio.