Layout/Aspect Ratio

Aspect Ratio

Displays content within a desired ratio.

Themed

When to Use

Use Aspect Ratio when you need to:

Maintain a consistent width-to-height ratio for images, videos, or maps
Prevent layout shift while media loads by reserving the correct space
Create uniform card image headers across a grid of cards
Embed responsive video or iframe content at a fixed proportion
Display avatar thumbnails or social media previews at standard sizes

When Not to Use

Flexible-height content that should grow naturally — use standard containers
Fixed pixel dimensions — set explicit width and height instead
Full-bleed hero images — use object-fit on the image directly
Scrollable content areas — use Scroll Area

Default (16:9)

The default appearance using a 16:9 widescreen ratio with an image that fills the container.

Common Ratios

Side-by-side comparison of the most frequently used aspect ratios in web design.

16:9

Widescreen

4:3

Traditional

1:1

Square

4:3 Traditional

Classic 4:3 ratio used in traditional photography and older displays.

Square (1:1)

Perfect square ratio popular in social media and profile images.

Video Embed

16:9 container for video embeds and media players. The iframe fills the container proportionally.

16:9 Video Embed

Card with Image

Practical composition using AspectRatio for consistent card image headers.

Healthy Recipes

Nutritious meals for a balanced lifestyle.

Discover our collection of wholesome and delicious meal ideas.

UX & Design Guidelines

Choosing the Right Ratio

Use 16/9 for widescreen hero images and video embeds. Use 4/3 for traditional photography and card thumbnails. Use 1 (square) for avatars, profile images, and social media previews. Use 21/9 for cinematic, ultrawide banner images.

Spacing & Layout

When using AspectRatio in card grids, apply a consistent ratio across all cards to maintain visual alignment. Add overflow-hidden and rounded-lg to the container for clean edge clipping. Set a bg-muted fallback background to provide a placeholder while images load.

Responsive Behavior

AspectRatio is fully responsive by default — the container scales proportionally with its parent width. Wrap it in a max-w-* container to cap maximum dimensions. Use Next.js fill prop on Image for responsive scaling without explicit width/height. Consider switching ratios at breakpoints (e.g., 16:9 on desktop, 4:3 on mobile) using conditional rendering.

Image Handling

Always use object-cover on child images to prevent distortion and letterboxing. Apply object-position (e.g., object-top) to control the focal point of cropped images. Add priority to above-the-fold hero images for faster LCP scores.

Accessibility

Keyboard Navigation

Tab — Moves focus to interactive children inside the container (links, buttons, play controls)
Enter or Space — Activates focused interactive elements within the container
Escape — Exits fullscreen mode for video embeds

Image Alt Text

Always provide meaningful alt text describing the image content for screen reader users
For decorative images, use an empty alt="" and role="presentation" to hide from assistive technology
Avoid redundant alt text that repeats surrounding heading or caption text

Video & Iframe Accessibility

Add a descriptive title attribute to all <iframe> elements
Ensure embedded videos have captions or subtitles available
Provide a text alternative or transcript link for users who cannot view video content

Motion & Reduced Motion

If the aspect ratio container holds animated or auto-playing content, respect prefers-reduced-motion by pausing animations. Avoid auto-playing video without user consent. Provide visible play/pause controls.

ARIA Attributes

{/* Image with descriptive alt text */}
<AspectRatio ratio={16 / 9} className="bg-muted rounded-lg overflow-hidden">
  <Image
    src="/images/hero.jpg"
    alt="Mountain sunrise over a misty valley"
    fill
    className="object-cover"
  />
</AspectRatio>

{/* Decorative image — hide from assistive technology */}
<AspectRatio ratio={16 / 9} className="bg-muted rounded-lg overflow-hidden">
  <Image
    src="/images/pattern.jpg"
    alt=""
    role="presentation"
    fill
    className="object-cover"
  />
</AspectRatio>

{/* Video embed with accessible title */}
<AspectRatio ratio={16 / 9}>
  <iframe
    src="https://www.youtube.com/embed/..."
    title="Product demo walkthrough"
    className="h-full w-full"
    allowFullScreen
  />
</AspectRatio>

API Reference

The AspectRatio component accepts the following props in addition to standard div attributes.

Prop	Type	Default	Description
ratio	`number`	1	The desired aspect ratio expressed as width / height. E.g., 16/9, 4/3, 1.
asChild	`boolean`	false	When true, renders the child as the root element, merging props and behavior.
className	`string`	—	Additional CSS classes to apply to the container.
children	`ReactNode`	—	Content to display within the aspect ratio container. Typically an image, video, or map.