Shadcn Aspect Ratio
React aspect ratio component for consistent image and video proportions. Built with TypeScript and Tailwind CSS for Next.js applications with responsive design.
Aspect ratio not responsive?
Join our Discord community for help from other developers.
Ever uploaded a perfect product photo only to watch it get squashed into a pancake on mobile? Or had a client complain their logo looks "stretched weird"? Yeah, aspect ratios are the unsung heroes that prevent these design disasters in your Next.js applications.
Widescreen ratio
Standard 16:9 ratio for modern videos and images:
This shadcn/ui component leverages Radix UI's AspectRatio primitive with modern CSS and TypeScript types. Styled with Tailwind CSS utilities for easy customization.
npx shadcn@latest add aspect-ratioWhy aspect ratios actually matter
Here's the thing—aspect ratios aren't just about preventing stretched images. They're about creating predictable layouts that don't shift around while content loads. You know that annoying jump when an image finally loads and pushes everything down? Aspect ratios eliminate that.
Think of it like reserving a parking space. Your React component knows exactly how much space that image will take before it even loads. No layout shift, no jumpy scrolling, no frustrated users losing their reading position.
This free shadcn component handles the complexity with a simple ratio prop. Whether you're building image galleries, video players, or card layouts in your JavaScript apps, consistent proportions make everything feel more polished.
Common aspect ratio patterns you'll actually use
Square ratio
Perfect 1:1 ratio for profile pictures and thumbnails:
Portrait ratio
3:4 ratio for vertical content and mobile layouts:
Video player ratio
Multiple video ratios for different platforms:
YouTube embed
Real video embed that maintains 16:9 ratio:
Features
This free open source aspect ratio component includes everything you need:
- TypeScript-first design - Full type safety with ratio calculations
- Tailwind CSS integration - Style with utility classes, not inline styles
- Radix UI foundation - Battle-tested primitive with accessibility built-in
- CSS aspect-ratio support - Uses native CSS with JavaScript fallback
- Responsive by default - Maintains proportions across all breakpoints
- Works everywhere - Next.js, Remix, or vanilla React apps
- No more jumpy layouts - Reserves space before content loads
API Reference
AspectRatio
The container that maintains a consistent width-to-height ratio.
| Prop | Type | Default | Description |
|---|---|---|---|
ratio | number | 1 | The desired aspect ratio (width divided by height) |
className | string | - | Additional CSS classes for styling |
children | React.ReactNode | - | Content to display within the ratio container |
asChild | boolean | false | Render as child component using Radix UI Slot |
Common Ratios
| Ratio | Value | Use Case |
|---|---|---|
| Square | 1 / 1 or 1 | Profile pictures, app icons, thumbnails |
| Portrait | 3 / 4 or 0.75 | Vertical photos, phone screens |
| Landscape | 4 / 3 or 1.333 | Traditional photos, old TVs |
| Widescreen | 16 / 9 or 1.778 | YouTube videos, modern screens |
| Cinematic | 21 / 9 or 2.333 | Ultra-wide monitors, movie clips |
| Golden | 1.618 / 1 or 1.618 | Aesthetically pleasing layouts |
Browser Support
| Feature | Support |
|---|---|
| CSS aspect-ratio | Modern browsers (Chrome 88+, Firefox 89+, Safari 15+) |
| JavaScript fallback | All browsers via Radix UI |
| Mobile browsers | Full support on iOS and Android |
| Smart fallbacks | Works even in ancient browsers |
Production tips
Prevent layout shift with aspect ratios. This free shadcn/ui component reserves space before images load, eliminating the jarring content jumps users hate. Critical for Core Web Vitals scores.
Combine with Next.js Image for best results. Use fill prop with object-cover to let the Image component handle optimization while aspect ratio maintains proportions. Your TypeScript types will thank you.
Consider skeleton loaders. While aspect ratio prevents layout shift, combine with Skeleton components to show loading state. Users know content is coming instead of staring at empty boxes.
Test with slow connections. Aspect ratios shine when images load slowly. Throttle your network in dev tools to see how your React components behave under real conditions.
Use semantic ratios for content types. Profile pictures? Square. YouTube embeds? 16:9. Product photos? 4:3 or 3:4. Users recognize these patterns instinctively.
Integration with other components
Aspect ratio works brilliantly with Avatar components for consistent profile pictures in your React applications. Combine with Card components to create uniform grid layouts that don't shift as images load.
For loading states, wrap aspect ratio content with Skeleton components. This open source pattern gives users visual feedback while maintaining layout stability. When building galleries, aspect ratio ensures your Dialog previews match their thumbnails perfectly.
Questions you might have
Shadcn Alert
React alert component for success messages, errors, and notifications. Built with TypeScript and Tailwind CSS for Next.js with accessibility support.
Shadcn Avatar
React avatar component for user profiles with automatic image fallbacks. Built with TypeScript and Tailwind CSS for Next.js using Radix UI.