Skip to content
Shaken UI
Sign in

Aspect Ratio

Save

A box that keeps a width-to-height ratio as it resizes, so images, video, and embeds fill it without shifting the layout.

Category
Data display
Version
0.1.0
Frameworks
Next.js, Vite + React
Styling
Tailwind CSS v4

Preview

Aspect Ratio preview
Deploy preview, 16 by 9
Thumbnail, square crop

Installation

npx @shakenui/cli add aspect-ratio

Review the plan first. A dry run lists every file and package without changing anything:

npx @shakenui/cli add aspect-ratio --dry-run

Usage

aspect-ratio-example.tsx
import { AspectRatio } from "@/components/shaken/ui/aspect-ratio";

// A drawn preview stands in for a screenshot so the example has no network dependency.
function PreviewArt() {
  return (
    <svg viewBox="0 0 320 180" preserveAspectRatio="xMidYMid slice" aria-hidden="true" className="text-zinc-950 dark:text-white">
      <rect width="320" height="180" className="fill-zinc-50 dark:fill-black" />
      <rect x="0" y="0" width="320" height="22" className="fill-white dark:fill-black" />
      <line x1="0" y1="22.5" x2="320" y2="22.5" stroke="currentColor" strokeOpacity="0.1" />
      <circle cx="12" cy="11" r="3" fill="currentColor" fillOpacity="0.15" />
      <circle cx="22" cy="11" r="3" fill="currentColor" fillOpacity="0.15" />
      <circle cx="32" cy="11" r="3" fill="currentColor" fillOpacity="0.15" />
      <rect x="16" y="38" width="72" height="6" rx="3" fill="currentColor" fillOpacity="0.7" />
      <rect x="16" y="52" width="120" height="4" rx="2" fill="currentColor" fillOpacity="0.2" />
      <path d="M16 150 L56 128 L96 136 L136 104 L176 112 L216 80 L256 90 L304 58" fill="none" stroke="currentColor" strokeWidth="2" strokeLinejoin="round" strokeLinecap="round" />
      <path d="M16 150 L56 128 L96 136 L136 104 L176 112 L216 80 L256 90 L304 58 L304 164 L16 164 Z" fill="currentColor" fillOpacity="0.05" />
      <line x1="16" y1="164.5" x2="304" y2="164.5" stroke="currentColor" strokeOpacity="0.15" />
    </svg>
  );
}

export default function AspectRatioExample() {
  return (
    <div className="grid w-full max-w-xl gap-4 sm:grid-cols-[2fr_1fr]">
      <figure className="m-0 grid gap-2">
        <AspectRatio ratio={16 / 9} className="rounded-xl border border-zinc-950/10 dark:border-white/10">
          <PreviewArt />
        </AspectRatio>
        <figcaption className="text-xs text-zinc-500">Deploy preview, 16 by 9</figcaption>
      </figure>
      <figure className="m-0 grid content-start gap-2">
        <AspectRatio ratio={1} className="rounded-xl border border-zinc-950/10 dark:border-white/10">
          <PreviewArt />
        </AspectRatio>
        <figcaption className="text-xs text-zinc-500">Thumbnail, square crop</figcaption>
      </figure>
    </div>
  );
}

API

PropTypeDefaultDescription
rationumber | string16 / 9Width over height: 16 / 9, 1, or a CSS ratio string such as "4 / 3".
...propsComponentProps<"div">—Any div attribute. Direct img, video, picture, iframe, and svg children fill the box with object-cover.

Accessibility

  • Purely presentational: it adds no role, so the media inside keeps its own alt text or title.
  • Reserving the box's height before media loads prevents layout shift for every reader.

Files

Installed into src/components/shaken, or components/shaken when the project has no src directory.

  • src/components/shaken/ui/aspect-ratio.tsxaspect-ratio
  • npm packages: noneReact and Tailwind CSS v4 required

Source

The exact source the CLI installs, from /r/items/react/aspect-ratio/0.1.0.json.

ui/aspect-ratio.tsxShow
ui/aspect-ratio.tsx
import type { ComponentProps, CSSProperties } from "react";

function cx(...classes: (string | false | null | undefined)[]) {
  return classes.filter(Boolean).join(" ");
}

export interface AspectRatioProps extends ComponentProps<"div"> {
  /**
   * Width divided by height: a number (`16 / 9`, `1`) or a CSS ratio string (`"4 / 3"`).
   * Defaults to 16 / 9.
   */
  ratio?: number | string;
}

/**
 * A box that keeps its width-to-height ratio as it resizes, so media does not shift the layout
 * while it loads. Direct `img`, `video`, `iframe`, `picture`, and `svg` children fill the box
 * and crop with `object-cover`; anything else is laid out normally inside it.
 */
export function AspectRatio({ ratio = 16 / 9, className, style, ...props }: AspectRatioProps) {
  return (
    <div
      data-slot="aspect-ratio"
      style={{ aspectRatio: typeof ratio === "number" ? String(ratio) : ratio, ...style } as CSSProperties}
      className={cx(
        "relative w-full overflow-hidden",
        "[&>img]:absolute [&>img]:inset-0 [&>img]:size-full [&>img]:object-cover",
        "[&>video]:absolute [&>video]:inset-0 [&>video]:size-full [&>video]:object-cover",
        "[&>picture]:absolute [&>picture]:inset-0 [&>picture]:size-full [&>picture>img]:size-full [&>picture>img]:object-cover",
        "[&>iframe]:absolute [&>iframe]:inset-0 [&>iframe]:size-full [&>iframe]:border-0",
        "[&>svg]:absolute [&>svg]:inset-0 [&>svg]:size-full",
        className,
      )}
      {...props}
    />
  );
}