Next.js Aspect Ratio — Server-Rendered, Zero JS

Drivn installs through a small CLI that writes component source files directly into your repository — there is no runtime npm package and no version to keep upgrading. Open a terminal at the root of your Next.js 16 project and run npx drivn add aspect-ratio. The CLI prompts for an install directory, defaulting to src/components/ui/, then copies aspect-ratio.tsx into place. Unlike most aspect-ratio helpers, this one pulls in no peer dependency at all — it is pure React and Tailwind, so there is nothing else to install. The CLI reference documents every flag, including targeting a custom path or adding several components in one command. After install you own the file; future Drivn releases never overwrite it, and you can edit the internals without forking a package.

App Router pages are server components by default, so any client-side hook inside one fails at build time. A surprising number of media-ratio packages still mark their root 'use client' because they measure the container with a resize observer. Drivn's Aspect Ratio measures nothing. It sets the proportion with the native CSS aspect-ratio property and lets the browser do the math, so the component is a pure function with no hooks and no directive. Render it directly inside a server page and Next.js streams the box as static HTML. The installation guide covers project bootstrapping; the Aspect Ratio docs list every prop the component accepts.

In production you usually want Next.js to optimize the image rather than serving a raw <img>. The next/image component does this, and it pairs naturally with Aspect Ratio: set fill on the image so it absolutely positions to the nearest positioned ancestor, and let the Aspect Ratio div — which already carries relative and overflow-hidden — be that ancestor. The box reserves the correct height from first paint, the optimized image fills it once decoded, and there is no layout shift in between. Add a sizes attribute so Next.js serves an appropriately scaled file for each breakpoint. Because the container clips overflow, object-cover crops cleanly to the ratio you chose.

Embedded video and third-party iframes are the most common cause of cumulative layout shift, because their intrinsic size is unknown until the frame loads. Wrapping the embed in an Aspect Ratio container fixes the height before the iframe arrives, so surrounding content never jumps. Pass the ratio that matches the source — 16/9 for most modern video, 4/3 for older footage — and stretch the iframe to fill with w-full h-full. The container's overflow-hidden trims any letterboxing the provider adds. This works identically for a YouTube embed, a Vimeo player, a map iframe, or a self-hosted <video> element, and all of it still renders on the server because the box itself ships no JavaScript. See the Aspect Ratio examples for portrait and square variants.

The ratio prop accepts three string presets — 16/9, 4/3, 1/1 — or any raw number for a custom proportion. Pass ratio={2.35} for a cinematic widescreen crop, ratio={3 / 4} for a portrait card, or compute the value from real dimensions with ratio={width / height}. Internally the component is deliberately small: a single div that merges your className over relative w-full overflow-hidden and sets the CSS aspectRatio property from the prop. There is nothing to theme in the usual sense, but because className is forwarded last you can add rounded corners, a border, or a background placeholder color without touching the source. The theming page covers the design tokens you would reference for that placeholder.