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>
`;
}
View Code
Installation
Copy and paste the following code into your project.
/**
* 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
import { aspectRatioClass } from '#components/ui/aspect-ratio.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.
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>
`;
}
View Code
Portrait
A portrait aspect ratio component using style="aspect-ratio: 9 / 16". This is useful for displaying images in a portrait format.
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>
`;
}
View Code
RTL
To enable RTL support, see the RTL configuration guide.
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>
`;
}
View Code
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.