Capítulo 69 de 108

Aspect Ratio

Core Idea

Mantém proporção fixa de largura/altura para o conteúdo (tipicamente imagem/vídeo), evitando layout shift e distorção independentemente do tamanho do container.

Key Concepts

  • ratio: número obrigatório representando a razão largura/altura (ex. 16/9, 1/1, 9/16).
  • Conteúdo interno (ex. <Image fill>) deve preencher o container via fill + object-cover, já que o AspectRatio controla apenas as dimensões do wrapper.

Code Examples

<AspectRatio ratio={16 / 9} className="w-full max-w-sm rounded-lg bg-muted">
  <Image
    src="https://avatar.vercel.sh/shadcn1"
    alt="Photo"
    fill
    className="rounded-lg object-cover grayscale dark:brightness-20"
  />
</AspectRatio>
  • O que demonstra: uso padrão widescreen com Next.js <Image fill>.
<AspectRatio ratio={1 / 1} className="w-full max-w-[12rem] rounded-lg bg-muted">
  <Image src="..." alt="Photo" fill className="rounded-lg object-cover" />
</AspectRatio>
  • O que demonstra: proporção quadrada (1/1), útil para avatares/thumbnails.

Reference Tables

AspectRatio

PropTypeDefaultRequired
rationumber-Sim
classNamestring-Não

Anti-patterns

  • Esquecer fill + object-cover na imagem interna: sem isso a imagem não respeita a proporção do container e pode distorcer ou vazar.
  • Aplicar w-full/max-w-* só no <Image> em vez do AspectRatio: o dimensionamento responsivo deve vir do wrapper AspectRatio, a imagem apenas preenche.

Key Takeaways

  1. ratio é a única prop essencial: 16/9 (paisagem), 1/1 (quadrado), 9/16 (retrato) são os valores mais comuns.
  2. Combine sempre com fill + object-cover na mídia interna para evitar distorção.
  3. Componente extremamente simples e sem subcomponentes — é apenas um wrapper de proporção.

Connects To

  • Carousel (ch068): usado dentro de CarouselItem para manter proporção consistente entre slides.
  • Card (ch064): CardContent frequentemente contém um AspectRatio para imagens de capa.
AnteriorCarouselPróximoTypography