# Aspect Ratio

Displays content within a desired ratio.

Source: https://webjs.dev/ui/docs/components/aspect-ratio

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { aspectRatioClass } from '#components/ui/aspect-ratio.ts';

export default function AspectRatioDemo() {
  return html`
    <div class="w-full max-w-sm">
      <div data-slot="aspect-ratio" style="aspect-ratio: 16 / 9" class=${cn(aspectRatioClass(), 'rounded-lg bg-muted')}>
        <img
          src="https://avatar.vercel.sh/shadcn1"
          alt="Photo"
          class="absolute inset-0 h-full w-full rounded-lg object-cover grayscale dark:brightness-20"
        >
      </div>
    </div>
  `;
}
```

## Installation

```bash
npx @webjsdev/ui add aspect-ratio
```

### Copy and paste the following code into your project.

````ts title="components/ui/aspect-ratio.ts"
/**
 * AspectRatio: preserve a width:height ratio for its child. Tier-1
 * class helper over the modern CSS `aspect-ratio` property (Baseline
 * 2022). No JS, no custom element.
 *
 * shadcn parity:
 *   AspectRatio (Radix primitive)  → aspectRatioClass() + inline `aspect-ratio` style
 *
 * Design tokens used: none (layout only).
 *
 * A11y (required for accessible output):
 *   Layout only, so it adds no semantics and takes none away. What matters is
 *   the CONTENT you put inside it: an `<img>` still needs an `alt` (empty
 *   `alt=""` when it is purely decorative), an `<iframe>` still needs a `title`,
 *   and a `<video>` still needs its captions.
 *   Reserving the ratio IS the accessibility win: the box keeps its space before
 *   the media loads, so the page does not shift under someone who is already
 *   reading or aiming at a target (WCAG 2.4.x-adjacent).
 *   Do not clip meaningful content to make a ratio fit. If a crop would hide
 *   part of an image that carries information, put that information in the
 *   surrounding text too.
 *
 * @example
 * ```html
 * <div style="aspect-ratio: 16/9;" class="${aspectRatioClass()}">
 *   <img src="/hero.jpg" alt="Team offsite" class="h-full w-full object-cover rounded-md">
 * </div>
 *
 * <!-- Or with Tailwind's arbitrary aspect-ratio (no helper needed): -->
 * <div class="aspect-[16/9]">
 *   <img src="/hero.jpg" alt="Team offsite" class="h-full w-full object-cover rounded-md">
 * </div>
 * ```
 */

export const aspectRatioClass = (): string => 'relative w-full';
````

### Update the import paths to match your project setup.

## Usage

```ts
import { aspectRatioClass } from '#components/ui/aspect-ratio.ts';
```

```ts
<div data-slot="aspect-ratio" style="aspect-ratio: 16 / 9" class=${aspectRatioClass()}>
  <img src="..." alt="Image" class="absolute inset-0 h-full w-full rounded-md object-cover">
</div>
```

## Square

A square aspect ratio component using `style="aspect-ratio: 1 / 1"`. This is useful for displaying images in a square format.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { aspectRatioClass } from '#components/ui/aspect-ratio.ts';

export default function AspectRatioSquare() {
  return html`
    <div class="w-full max-w-[12rem]">
      <div data-slot="aspect-ratio" style="aspect-ratio: 1 / 1" class=${cn(aspectRatioClass(), 'rounded-lg bg-muted')}>
        <img
          src="https://avatar.vercel.sh/shadcn1"
          alt="Photo"
          class="absolute inset-0 h-full w-full rounded-lg object-cover grayscale dark:brightness-20"
        >
      </div>
    </div>
  `;
}
```

## Portrait

A portrait aspect ratio component using `style="aspect-ratio: 9 / 16"`. This is useful for displaying images in a portrait format.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { aspectRatioClass } from '#components/ui/aspect-ratio.ts';

export default function AspectRatioPortrait() {
  return html`
    <div class="w-full max-w-[10rem]">
      <div data-slot="aspect-ratio" style="aspect-ratio: 9 / 16" class=${cn(aspectRatioClass(), 'rounded-lg bg-muted')}>
        <img
          src="https://avatar.vercel.sh/shadcn1"
          alt="Photo"
          class="absolute inset-0 h-full w-full rounded-lg object-cover grayscale dark:brightness-20"
        >
      </div>
    </div>
  `;
}
```

## RTL

To enable RTL support, see the [RTL configuration guide](https://webjs.dev/ui/docs/rtl).

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { aspectRatioClass } from '#components/ui/aspect-ratio.ts';

const translations = {
  en: {
    dir: 'ltr',
    values: {
      caption: 'Beautiful landscape',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      caption: 'منظر طبيعي جميل',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      caption: 'נוף יפה',
    },
  },
};

export default function AspectRatioRtl() {
  const lang = 'ar';
  const { dir, values: t } = translations[lang];

  return html`
    <figure class="w-full max-w-sm" dir=${dir} lang=${lang}>
      <div data-slot="aspect-ratio" style="aspect-ratio: 16 / 9" class=${cn(aspectRatioClass(), 'rounded-lg bg-muted')}>
        <img
          src="https://avatar.vercel.sh/shadcn1"
          alt="Photo"
          class="absolute inset-0 h-full w-full rounded-lg object-cover grayscale dark:brightness-20"
        >
      </div>
      <figcaption class="mt-2 text-center text-sm text-muted-foreground">${t.caption}</figcaption>
    </figure>
  `;
}
```

## API Reference

### aspectRatioClass

`aspectRatioClass()` returns the classes for the box that holds content within a desired ratio. It takes no options: the ratio is the CSS `aspect-ratio` property, set inline or with a Tailwind class such as `aspect-video` or `aspect-[4/3]`. Position the content inside with `absolute inset-0` so it fills the box.

| Attribute | Type | Required |
| --- | --- | --- |
| `style="aspect-ratio: …"` | `string` | Yes |
| `class` | `string` | No |
