AspectRatio

Installation

npx vayu-ui init #one time only

npx vayu-ui add aspectratio

npx vayu-ui add -t aspectratio #with test case needs

Usage

PreviewCode

Preset Ratios

Built-in aspect ratio presets for common use cases.

square (1:1)

video (16:9)

photo (4:3)

landscape (3:2)

ultrawide (21:9)

cinema (2.39:1)

portrait (9:16)

golden (1.618)

a4 (√2)

Device Presets

Aspect ratios optimized for specific device screens.

iPhone

19.5:9

iPad

4:3

Custom Numeric Ratio

Pass any numeric value for custom aspect ratios.

2.5 : 1

Object Fit Options

Control how images and videos fill the container.

objectFit="cover" (Default)

objectFit="contain"

Design System Props

Built-in props for rounded corners, shadows, and borders using design tokens.

rounded

Rounded corners

shadow

Subtle shadow

bordered

With border

Accessibility (Named Region)

Pass an aria-label to create a named landmark region for screen readers.

Interactive Example

Combine AspectRatio with other components for interactive layouts.

Mountain Vista

Explore the beauty of nature

Learn More

Waterfall Wonder

Discover hidden gems

Explore

<AspectRatio ratio="square" decorative className="rounded bg-ground-100 dark:bg-ground-800">
  <div className="flex items-center justify-center h-full text-sm text-muted-content">Square (1:1)</div>
</AspectRatio>

<AspectRatio ratio="video" decorative className="rounded bg-ground-100 dark:bg-ground-800">
  <div className="flex items-center justify-center h-full text-sm text-muted-content">Video (16:9)</div>
</AspectRatio>

<AspectRatio ratio={2.5} decorative className="rounded bg-ground-100 dark:bg-ground-800">
  <div className="flex items-center justify-center h-full text-sm text-muted-content">Custom (2.5)</div>
</AspectRatio>

<AspectRatio ratio="video" aria-label="Mountain landscape" bordered rounded>
  <img
    src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800&q=80"
    alt="Mountain landscape"
  />
</AspectRatio>

Anatomy

import { AspectRatio } from 'vayu-ui';

<AspectRatio ratio="video" aria-label="Description">
  {/* Outer div with aspect-ratio constraint */}
  <div className="relative w-full aspect-video">
    {/* Inner wrapper fills the container */}
    <div className="absolute inset-0">{/* Your content renders here */}</div>
  </div>
</AspectRatio>;

• Root — Outer <div> with the aspect ratio applied via Tailwind class (presets) or padding-bottom fallback (custom ratios). Manages overflow, accessibility roles, and design system tokens.
• Inner — Absolutely positioned wrapper that fills the root container. Applies object-fit styles to direct <img> and <video> children.

Accessibility

• Keyboard Support:
  • AspectRatio is a non-interactive layout primitive. No keyboard interactions are required.
• ARIA Attributes:
  • When decorative is true: role="presentation" and aria-hidden="true" are applied, hiding the container from assistive technology.
  • When aria-label is provided: role="region" is applied, making the container a named landmark for screen readers.
  • When neither is set: no semantic role is added — the element is treated as a generic container.
• Focus Behavior:
  • No focus management. The component delegates focus behavior to its children (e.g., links, buttons, interactive media).

Screen reader behavior

When decorative is set, the screen reader skips the container entirely — it will not be announced or included in the accessibility tree. When aria-label is provided, the screen reader identifies the container as a named region and announces the label when the user navigates into it (e.g., via landmarks or reading order). The content inside (images, videos, text) is announced normally based on its own semantics. When neither prop is set, the container is transparent to the screen reader and only its children are announced.

Component Folder Structure

AspectRatio/
├── AspectRatio.tsx    # Root component with UI + accessibility logic
├── types.ts           # TypeScript types, preset maps, and constant definitions
├── index.ts           # Re-exports component and types
└── README.md          # Component usage reference

Props

AspectRatio