> ## Documentation Index
> Fetch the complete documentation index at: https://araf.badr.co.id/llms.txt
> Use this file to discover all available pages before exploring further.

# Aspect Ratio

> A utility wrapper that maintains a fixed width-to-height ratio for its child content — useful for images, videos, and embeds.

## Overview

<div style={{padding:"28px 24px",background:"#f9fafb",borderRadius:"12px",border:"1px solid #e5e7eb",display:"flex",gap:"16px",flexWrap:"wrap",justifyContent:"center",alignItems:"flex-end"}}>
  {[
      {label:"16 / 9",ratio:9/16},
      {label:"4 / 3",ratio:3/4},
      {label:"1 / 1",ratio:1},
    ].map(({label,ratio}) => (
      <div key={label} style={{display:"flex",flexDirection:"column",gap:"6px",alignItems:"center",fontFamily:"Inter,sans-serif"}}>
        <div style={{width:"140px",height:`${140*ratio}px`,background:"linear-gradient(135deg,#EFF8FF,#0479CE)",borderRadius:"8px",display:"flex",alignItems:"center",justifyContent:"center",color:"#fff",fontSize:"13px",fontWeight:500}}>
          {label}
        </div>
        <span style={{fontSize:"11px",color:"#667085"}}>{label}</span>
      </div>
    ))}
</div>

**Aspect Ratio** maintains a consistent width-to-height ratio for its child, regardless of the container width. It uses the CSS `padding-bottom` trick under the hood — no JavaScript resizing required.

***

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @araf-ds/core
  ```

  ```bash yarn theme={null}
  yarn add @araf-ds/core
  ```

  ```bash pnpm theme={null}
  pnpm add @araf-ds/core
  ```
</CodeGroup>

***

## Usage

```tsx theme={null}
import { AspectRatio } from "@araf-ds/core"

export default function Example() {
  return (
    <div className="w-full max-w-sm">
      <AspectRatio ratio={16 / 9}>
        <img
          src="/thumbnail.jpg"
          alt="Project thumbnail"
          className="rounded-lg object-cover w-full h-full"
        />
      </AspectRatio>
    </div>
  )
}
```

***

## Variants

### 16:9 — Video / Widescreen

<div style={{padding:"24px",background:"#f9fafb",borderRadius:"12px",border:"1px solid #e5e7eb",display:"flex",justifyContent:"center"}}>
  <div style={{width:"100%",maxWidth:"320px"}}>
    <div style={{width:"100%",paddingBottom:`${(9/16*100)}%`,position:"relative",background:"linear-gradient(135deg,#1e293b,#0479CE)",borderRadius:"10px",overflow:"hidden"}}>
      <div style={{position:"absolute",inset:0,display:"flex",alignItems:"center",justifyContent:"center"}}>
        <div style={{width:"44px",height:"44px",borderRadius:"50%",background:"rgba(255,255,255,0.2)",display:"flex",alignItems:"center",justifyContent:"center",cursor:"pointer"}}>
          <svg width="18" height="18" viewBox="0 0 24 24" fill="#fff">
            <polygon points="5 3 19 12 5 21 5 3" />
          </svg>
        </div>
      </div>
    </div>
  </div>
</div>

```tsx theme={null}
<AspectRatio ratio={16 / 9} className="bg-muted rounded-lg overflow-hidden">
  <video src="/intro.mp4" controls className="w-full h-full object-cover" />
</AspectRatio>
```

### 4:3 — Classic / Presentation

```tsx theme={null}
<AspectRatio ratio={4 / 3}>
  <img
    src="/slide.png"
    alt="Presentation slide"
    className="rounded-md object-cover w-full h-full"
  />
</AspectRatio>
```

### 1:1 — Square / Avatar / Product

```tsx theme={null}
<AspectRatio ratio={1 / 1} className="w-32">
  <img
    src="/product.jpg"
    alt="Product"
    className="rounded-full object-cover w-full h-full"
  />
</AspectRatio>
```

### Responsive Image Grid

```tsx theme={null}
<div className="grid grid-cols-3 gap-3">
  {images.map(img => (
    <AspectRatio key={img.id} ratio={1 / 1}>
      <img
        src={img.src}
        alt={img.alt}
        className="rounded-md object-cover w-full h-full"
      />
    </AspectRatio>
  ))}
</div>
```

***

## API Reference

<ParamField path="ratio" type="number" default="1">
  The width-to-height ratio. Pass as a fraction: `16/9`, `4/3`, `1/1`, `9/16`.
</ParamField>

<ParamField path="className" type="string">
  Additional class names applied to the outer container.
</ParamField>

***

## Common Ratios

| Ratio    | Value  | Use Case                                |
| -------- | ------ | --------------------------------------- |
| `16 / 9` | 1.778  | Video, widescreen images, banners       |
| `4 / 3`  | 1.333  | Classic photo, presentations            |
| `3 / 2`  | 1.5    | Standard photography                    |
| `1 / 1`  | 1.0    | Square avatars, product thumbnails      |
| `9 / 16` | 0.5625 | Mobile / portrait video (Reels, TikTok) |

***

## Accessibility

* AspectRatio is a purely layout utility — no ARIA roles needed
* Ensure child images have descriptive `alt` text
* For videos, ensure `controls` are visible or provide accessible custom controls
* The container does not affect tab order or screen reader behavior

***

## Do's & Don'ts

<CardGroup cols={2}>
  <Card title="Do" icon="check" iconType="solid" color="#16A34A">
    * Always set a width on the parent container — AspectRatio fills 100% of its parent
    * Use `object-cover` on child images to fill without distortion
    * Apply `overflow-hidden` on the container when using `border-radius`
    * Use for images, videos, iframes, and map embeds
  </Card>

  <Card title="Don't" icon="xmark" iconType="solid" color="#DC2626">
    * Don't use AspectRatio for text content — height will clip text on small screens
    * Don't nest AspectRatios — the inner one overrides the outer
    * Don't forget to set the parent width — without it, the component has zero size
    * Don't use `object-contain` with `overflow-hidden` — it creates letterboxing gaps
  </Card>
</CardGroup>