Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Layout

AspectRatio

A CSS aspect-ratio wrapper for media and previews.

Last changed in version 0.13.0: Add avatar groups and chips, expand the block gallery, and improve component colors, spacing, and motion.

Interactive showcase

Case study

Designing calmer project handoffs

A 16:9 media card that stays stable at every width.

Install

Run in your project
bunx --bun @getweini/cli@latest add aspect-ratio

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Mountain landscape
Vue
<script setup lang="ts">
import AspectRatio from './components/ui/aspect-ratio/AspectRatio.vue'

const landscape =
  'data:image/svg+xml,' +
  encodeURIComponent(
    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 480"><rect width="640" height="480" fill="#e4e4e7"/><path d="M0 480 240 100 440 480Z" fill="#71717a"/><path d="m180 480 250-310 210 310Z" fill="#a1a1aa"/></svg>',
  )
</script>

<template>
  <AspectRatio :ratio="4 / 3" as="figure">
    <img :src="landscape" alt="Mountain landscape" class="h-full w-full object-cover">
  </AspectRatio>
</template>

Give images meaningful alternative text when they convey information.

When to use it

Media gallery

Keep image tiles the same shape while assets load.

Video preview

Preserve a widescreen preview inside a flexible card.

More examples

The wrapper sets shape while the image fills it.

Gallery thumbnail
<script setup lang="ts">
import AspectRatio from './components/ui/aspect-ratio/AspectRatio.vue'

const landscape =
  'data:image/svg+xml,' +
  encodeURIComponent(
    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 480"><rect width="640" height="480" fill="#e4e4e7"/><path d="M0 480 240 100 440 480Z" fill="#71717a"/><path d="m180 480 250-310 210 310Z" fill="#a1a1aa"/></svg>',
  )
</script>

<template>
  <AspectRatio :ratio="4 / 3" as="figure">
    <img :src="landscape" alt="Mountain landscape" class="h-full w-full object-cover">
  </AspectRatio>
</template>

Widescreen preview

A string ratio can represent a familiar format.

Widescreen preview
<script setup lang="ts">
import AspectRatio from './components/ui/aspect-ratio/AspectRatio.vue'
</script>

<template>
  <AspectRatio ratio="16 / 9">
    <iframe
      title="Widescreen content preview"
      srcdoc="<p>A self-contained widescreen embed.</p>"
      class="h-full w-full border-0"
    />
  </AspectRatio>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

AspectRatio

Complete API for AspectRatio
NameType or signatureDefaultWhat it does
ratiopropstring | number | undefined16 / 9ratio accepts a number or a valid CSS aspect-ratio string.
asprop"div" | "figure" | undefined"div"Choose the HTML element or Vue component used for this control.
defaultslot{}OptionalContent shown inside AspectRatio.
Public type definitions
Public types
// packages/frameworks/vue/components/aspect-ratio/types.ts
// ------- TYPES -------

export interface AspectRatioProps {
  ratio?: number | string
  as?: 'div' | 'figure'
}

Implementation notes

  • Set object-fit on images or video to choose cropping behavior inside the frame.
  • The ratio controls layout, not the intrinsic dimensions of the media.

Accessibility and localization

  • Give informative images alt text and caption media when the content requires it.

Source contract and editing guidance