Aspect Ratio
A box that holds a width-to-height ratio at any width and eases between ratios when you change it, for media, embeds and placeholders.
- Category: React Card, Accordion and Display Components
- Licence: Free, MIT
- Built with: React 19, Tailwind CSS 4, Motion
- Dependencies: motion, clsx, tailwind-merge
Examples
Aspect Ratio
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
ratio | number | 16 / 9 | |
children | ReactNode | — | Filled to the box. |
className | string | — |
About Aspect Ratio
Aspect Ratio holds a width-to-height ratio at any width, so images, videos and embeds never collapse or stretch. Change the ratio and the box eases to the new shape instead of snapping.
Aspect Ratio is a display component for React 19, styled with Tailwind CSS 4 and animated with Motion. It drops into Next.js, Vite, Remix or Astro through the shadcn CLI as a single file you own.
When to use Aspect Ratio
- Responsive images and video.
- Embeds and iframes.
- Card media and placeholders.
- Crop and layout previews.
How it works
It animates the CSS aspect-ratio property with Motion, and its first child is stretched to fill the box. Reduced motion changes the ratio without the ease.
Interactive parts are buttons or links with accessible names, decorative layers are hidden from assistive tech, and everything is reachable by keyboard. With prefers-reduced-motion on, it holds still or settles instantly instead of animating.
Customizing Aspect Ratio
Every prop is documented in the API reference above with its type and default. The ones you will reach for first are listed here.
Style it with className like any other element. It only uses your theme's tokens, so it follows light and dark mode without extra work.
- ratio (number, default 16 / 9).
Goes well with Aspect Ratio
These display pieces share its tokens and motion language, so they sit together on one page without clashing.
- Accordion: An animated React accordion: height springs open, the chevron flips, content fades in
- Number Ticker: An animated React number ticker: each digit rolls on its own wheel
- Marquee: A CSS-only infinite React marquee with faded edges and pause on hover
- Avatar Group: Overlapping React avatars that fan apart on hover with names that spring up
- Theme Toggle: A React dark mode toggle: the sun eclipses into a moon and the theme spreads out
Install Aspect Ratio
npx shadcn@latest add https://charcoalui.com/r/aspect-ratio.jsonAspect Ratio is free and MIT licensed. The command copies aspect-ratio.tsx into components/ui and installs clsx, tailwind-merge; you can also copy the source from the Code tab by hand.
Charcoal UI Pro adds 393 more showpiece components, 112 sections and 100 templates built the same way.
Frequently asked questions
- How do I install Aspect Ratio?
- Run npx shadcn@latest add https://charcoalui.com/r/aspect-ratio.json. The shadcn CLI copies aspect-ratio.tsx into components/ui and installs motion, clsx, tailwind-merge. You can also copy the source from this page by hand.
- Is Aspect Ratio free for commercial use?
- Yes. Aspect Ratio is MIT licensed: use it in any personal or commercial project and change it however you like.
- Does Aspect Ratio work with Next.js?
- Yes. It is a client component for React 19 styled with Tailwind CSS 4, so it works in the Next.js App Router and Pages Router, Vite, Remix and Astro.
- Can an AI coding agent install Aspect Ratio?
- Yes. Connect the Charcoal UI MCP server (https://charcoalui.com/mcp) to Claude Code, Cursor or any MCP client; get_component returns Aspect Ratio's props and source and get_install_command returns the exact command.