HelixTimelyCare Experience Design System
Light

Aspect Ratio

Displays content within a desired ratio.

Spec · from metadata

When to use

  • •Displaying images or videos at a consistent aspect ratio (16/9, 4/3, 1/1, etc.)
  • •Ensuring media containers do not shift layout during loading
  • •Embedding iframes or maps with a fixed ratio

When not to use

  • •When the Tailwind `aspect-video` or `aspect-square` utility is sufficient on the element itself
  • •For non-visual content that does not need ratio constraints

Anti-patterns

Avoid<AspectRatio ratio="16:9"><img src="/photo.jpg" /></AspectRatio>
Prefer<AspectRatio ratio={16 / 9}><img src="/photo.jpg" alt="Photo" className="h-full w-full object-cover" /></AspectRatio>

ratio must be a number (width divided by height), not a string; child should fill with object-cover

Avoid<AspectRatio ratio={16 / 9}><img src="/photo.jpg" alt="Photo" /></AspectRatio>
Prefer<AspectRatio ratio={16 / 9}><img src="/photo.jpg" alt="Photo" className="h-full w-full object-cover" /></AspectRatio>

Without h-full w-full object-cover, the image will not fill the aspect-ratio container properly

Accessibility

  • Screen readerAspectRatio is a layout primitive with no semantic meaning; ensure child media has proper alt text or aria-label

Import

import { AspectRatio } from "@timelycare/helix-ui"

Props

interface AspectRatioProps {
  ratio?: number  // width / height (e.g., 16/9, 4/3, 1)
  className?: string
  children: React.ReactNode
}

Ratios

RatioValueUse For
1:1ratio={1}Square thumbnails, avatars, Instagram-style
16:9ratio={16/9}HD video, YouTube embeds, hero images
4:3ratio={4/3}Standard photos, presentations
3:2ratio={3/2}35mm film, photography portfolios
21:9ratio={21/9}Ultrawide cinema, banner images
9:16ratio={9/16}Vertical video (TikTok, Reels, Stories)
1.618:1ratio={1.618}Golden ratio compositions
2:1ratio={2/1}Panoramic images

All Ratios Quick Reference

RatioDecimalPortrait Equivalent
1:11.0—
5:41.254:5 (0.8)
4:31.3333:4 (0.75)
3:21.52:3 (0.667)
16:101.610:16 (0.625)
1.618:11.6181:1.618 (0.618)
16:91.7789:16 (0.5625)
2:12.01:2 (0.5)
21:92.3339:21 (0.429)

States

Aspect Ratio is a layout utility—no interactive states.

Common Patterns

Basic Image

<AspectRatio ratio={16 / 9}>
  <img
    src="/image.jpg"
    alt="Photo"
    className="absolute inset-0 size-full rounded-md object-cover"
  />
</AspectRatio>

Square Avatar

<AspectRatio ratio={1}>
  <img
    src="/avatar.jpg"
    alt="User"
    className="absolute inset-0 size-full rounded-full object-cover"
  />
</AspectRatio>

Video Embed

<AspectRatio ratio={16 / 9}>
  <iframe
    src="https://www.youtube.com/embed/..."
    className="absolute inset-0 size-full"
    allowFullScreen
  />
</AspectRatio>

Gallery Grid

<div className="grid grid-cols-3 gap-4">
  {images.map((src) => (
    <AspectRatio key={src} ratio={1}>
      <img src={src} className="absolute inset-0 size-full object-cover rounded-md" />
    </AspectRatio>
  ))}
</div>

Child Content Styling

Always apply these classes to child content (images, videos):

className="absolute inset-0 size-full object-cover"
ClassPurpose
absolute inset-0Position to fill container
size-fullWidth and height 100%
object-coverMaintain aspect ratio, crop overflow
object-centerCenter the content (default)
rounded-mdOptional: round corners

Accessibility

  • Presentational container — no interactive behavior
  • No keyboard interaction needed
  • Ensure child images have meaningful alt text
  • Use aria-hidden="true" on decorative images

Gotchas

ProblemSolution
Image distortedAdd object-cover to child element
Image not fillingAdd absolute inset-0 size-full to child element
Content overflowsContainer has overflow-hidden by default
Need placeholder colorAdd bg-muted to AspectRatio
Child not positionedEnsure child has absolute inset-0

See Also

  • Related Components: Card (media cards), Carousel (slide sizing)
  • Patterns: Layouts — Layout patterns

Figma Reference

View in Figma

Last updated: February 9, 2026