Question 1

What is a shadcn aspect ratio component?

Accepted Answer

A shadcn aspect ratio is a layout container that forces its child content into a specific width-to-height ratio — 16:9 for widescreen video, 4:3 for traditional photography, 1:1 for social-square crops, 21:9 for ultrawide hero media. It's built on Radix UI's AspectRatio primitive and styled with shadcn/ui + Tailwind CSS. Each example in this gallery is a single self-contained TSX file — copy, paste, and ship.

Question 2

Are these aspect ratio examples free?

Accepted Answer

Yes. Every aspect ratio example on shadcn.io is free to copy and use in personal or commercial projects. There's no gated source, no attribution requirement, and no runtime dependency on shadcn.io. Browse any example, view the code, run the installer, and move on.

Question 3

How is this different from Tailwind's native aspect-ratio utility?

Accepted Answer

Tailwind's `aspect-video`, `aspect-square`, and `aspect-[16/9]` utilities use the CSS `aspect-ratio` property, which is supported in every modern browser. The Radix AspectRatio primitive uses the padding-bottom trick instead — slightly more markup, but works in older browsers and avoids subtle layout shifts when aspect-ratio support is patchy. For greenfield projects targeting modern browsers, Tailwind's utility is simpler; for component libraries that need broad compatibility, the primitive is safer.

Question 4

When should I use an aspect ratio container versus letting content size itself?

Accepted Answer

Use AspectRatio when the container must reserve space *before* content loads — images, videos, embedded iframes, skeleton placeholders. Letting the image dictate the height causes layout shift on load (bad CLS score). For content that's already known at render time (static icons, text), aspect-ratio is unnecessary overhead. Rule of thumb: if the content is async, async-rendered, or might fail to load, wrap it in an AspectRatio.

Question 5

Which aspect ratio should I use for embedded video?

Accepted Answer

Modern YouTube, Vimeo, and HTML5 video default to 16:9 widescreen. Use the widescreen example (`aspect-ratio: 16 / 9`) for single-video embeds. For landscape photography slideshows, 3:2 matches DSLR output; for portrait mobile video (TikTok, Reels, Stories), use 9:16 vertical. Cinematic content (trailers, showreels) often uses 21:9 ultrawide. Match your ratio to your content source to avoid letterboxing.

Question 6

When should I use a 1:1 square aspect ratio?

Accepted Answer

Square (1:1) works for product thumbnails, social-media preview cards, user avatars in a grid, and Instagram-style galleries where consistent tile size matters more than showing the full image. Pair with `object-cover` on the inner `<img>` so the image fills the square without distortion; the sides get cropped, which is usually the intent. For images where every pixel matters, use the native aspect ratio instead.

Question 7

How do I handle images that don't match the container ratio?

Accepted Answer

Two patterns. (1) `object-cover` — the image fills the container, cropping overflow. Best for decorative images where the subject sits near the center. (2) `object-contain` — the image fits inside, adding letterbox bars. Best when the full image matters (product shots, artwork). Pair `object-contain` with a matching background color on the AspectRatio container so the letterboxing looks intentional rather than accidental.

Question 8

Can I use aspect ratio for responsive hero sections?

Accepted Answer

Yes — pair an AspectRatio container with different ratios per breakpoint using Tailwind's responsive variants: a 21:9 ultrawide on desktop, 16:9 on tablet, 4:3 on mobile. This keeps the hero area proportionate to the viewport without requiring JavaScript-driven media queries. For full-viewport heroes (100vh), skip AspectRatio and use `h-screen` instead — aspect ratio is about content shape, not viewport shape.

Question 9

How do I install an aspect ratio example?

Accepted Answer

Run the `npx shadcn@latest add` command shown under the Installation heading on any example's detail page. The shadcn CLI copies the example's TSX source into your project at `components/examples/aspect-ratio/…`, plus the shadcn/ui AspectRatio primitive if you don't already have it. From there it's regular React — swap out the placeholder image for your own.

Question 10

How do I set a custom aspect ratio not shown in the gallery?

Accepted Answer

AspectRatio accepts a `ratio` prop as a number: `ratio={16 / 9}` for widescreen, `ratio={3 / 4}` for portrait, `ratio={1.618}` for the golden ratio. Any positive number works. The component renders the padding-bottom trick internally, so you don't need to calculate percentages yourself. Most common ratios are 1, 4/3, 3/2, 16/9, 21/9, and their inverses for portrait orientations.

Question 11

How do I make an aspect ratio container responsive?

Accepted Answer

The container's outer width is controlled by its parent — wrap AspectRatio in a div with responsive width classes (`w-full max-w-2xl`, or a grid cell). The height adjusts automatically based on the ratio. To change the ratio per breakpoint, render two or more AspectRatio components with CSS-only `hidden md:block` toggles, or pass a dynamically-computed `ratio` prop based on window size (via a resize observer or CSS container queries).

Question 12

Can I put videos, iframes, or canvas inside an AspectRatio?

Accepted Answer

Yes — any child element works. The child gets `className="absolute inset-0"` implicitly (via the AspectRatio layout), so it fills the container. For `

Question 13

Which libraries do aspect ratio examples depend on?

Accepted Answer

Radix UI AspectRatio (the padding-bottom primitive), shadcn/ui AspectRatio (the styled wrapper generated into your project by the CLI), and Tailwind CSS (styling). That's it — no state, no Lucide icons required. TypeScript is assumed. React 19 is the baseline. Images in the examples are placeholder URLs you'll replace with your own assets or a next/image optimizer.

Question 14

Are aspect ratio examples accessible for screen reader users?

Accepted Answer

The AspectRatio container itself has no semantic meaning for assistive tech — it's purely a layout wrapper. Accessibility comes from the child content: add meaningful `alt` text to images, caption videos, and label iframes with `title` attributes. For decorative images that carry no informational value, use `alt=""` (empty) so screen readers skip them rather than announcing "image" unnecessarily.

Question 15

Can I use these aspect ratio examples with React Server Components?

Accepted Answer

Yes — AspectRatio is render-only with no client state, so it renders cleanly as a Server Component. The inner `<img>` works either way too. The only client boundary you'd need is for interactive content inside the container (lazy-loading video players, hover-to-play previews, etc.).

Question 16

Do these examples work with Tailwind CSS v3 and v4?

Accepted Answer

Both. shadcn.io is authored on Tailwind v4, so the examples use v4 class names and design tokens. If you're on Tailwind v3, the classes still apply — AspectRatio's padding-bottom trick uses plain CSS and isn't affected by Tailwind version. If you prefer v4's native `aspect-ratio` utility over the Radix primitive, swap `` for `

` and drop the import.

React Aspect Ratio Examples for shadcn/ui

Browse every aspect ratio example

Frequently Asked Questions