Aspect Ratio

Overview

VyAspectRatio is the @vyui/core AspectRatio primitive re-exported by @vyui/kit. It renders one primitive element at width: 100% and applies the native CSS aspect-ratio property.

Usage

Import the component and its public type from the kit barrel.

import { VyAspectRatio, type AspectRatioProps } from '@vyui/kit'

The unprefixed AspectRatio primitive is still available from @vyui/core if you prefer the raw name.

Features and behavior

• ratio is width divided by height: use 16 / 9, 4 / 3, or 1 for a square.
• The component sets width: 100% because Lynx needs one definite dimension before it can derive the other.
• It renders a single element rather than a padding wrapper with absolutely positioned content.
• The default slot receives aspect, calculated as (1 / ratio) * 100, for consumers that need the percentage form.
• as and asChild come from the core Primitive API.

Props

Additional attributes, including class and style, are forwarded to the rendered primitive. The component's inline style supplies width: 100% and aspectRatio.

Emits

This component does not emit events.

Slots

Styling and theming

VyAspectRatio is not themeable through appConfig.ui and has no ui prop, slots, variants, or kit theme file. Style the component with forwarded class or style, and style its child so it fills the available box.

Accessibility

The ratio wrapper is structural and adds no role. Accessibility comes from its content: provide meaningful alternative text or native accessibility labeling for images and other media. Decorative media should be treated as decorative by the consuming application.

Platform notes

• Lynx Starlight supports the aspect-ratio property directly.
• If you want height to be the definite dimension, override the default width and provide an explicit height.
• Avoid ratio={0} or negative ratios; the component does not validate the value.
• The root exposes data-vyui-aspect-ratio with the current numeric ratio.

Related components

• Avatar for circular profile imagery.
• Skeleton for fixed-ratio loading placeholders.
• Card for framed media and content.