AspectRatio

Keeps a box at a fixed proportion, like 16:9 or 1:1, at any width. Use it for videos, embeds, maps and thumbnails, so the space is reserved before the media loads and every card in a row lines up.

InstallationCopy Anchor Link

Set up Camaleo once (Installation), then import it. It has no state, so it renders on the server.

import { AspectRatio } from "@camaleo/react";

AnatomyCopy Anchor Link

One box with position: relative and hidden overflow. A direct img, video or iframe fills it; anything else you lay on top with position: absolute.

ExamplesCopy Anchor Link

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

PreviewCode

minimal · light · #3fa34d

12:48

16:94:31:13:4

ratio={16 / 9}

Pick a ratio

Code

Switch the ratio. ratio is width divided by height, so write it as a fraction: 16 / 9 for video, 4 / 3 for photos, 1 for squares, 3 / 4 for portraits.

cover or contain

Code

cover, the default, fills the box and crops what doesn't fit. Set objectFit: "contain" on the image when every edge matters, like a product or a logo.

Pousada da Serra

Monte Verde, MG

$76 / night

Casa do Farol

Ilhabela, SP

$118 / night

Chalé Vista Mar

Ubatuba, SP

$94 / night

Cards with photos of any shape

Code

The three photos are 16:9, 4:3 and 3:4. Cut to the same ratio, the cards are the same height and the titles line up.

• 
• 
• 
• 
• 
• 

Thumbnail grid

Code

Square thumbnails make a tidy grid whatever was uploaded. object-position chooses which part of the photo survives the crop.

Rua Augusta 1200, São Paulo

Embeds need a title

Code

An iframe fills the box like an image does. Give it a title that says what's inside: it is the frame's name for screen readers.

Casa do Farol, Ilhabela. This line stays put while the photo loads.

Reload photo

Space kept while loading

Code

Reload the photo. The box has its height before the file arrives, so the text below never jumps, and a status message says when it's ready.

In contextCopy Anchor Link

Media rarely stands alone. These are whole pieces of UI you can copy, in the skin you picked.

12:48

Home Barista course · Module 2 · Lesson 4

How to roast coffee at home

Course progress9 of 15 lessons

x

Next lessonNotes

Course lessonAspectRatio · IconButton · Progress · ButtonCode

New

2-bedroom apartment in Pinheiros

68 m² · 2 bedrooms · 1 parking space

$540/month

Schedule a visit

Rental listingCard · AspectRatio · Badge · ButtonCode

Grão Coffee Co. · Augusta

Address

Rua Augusta 1200, São Paulo

Hours

Mon–Sat, 7 AM to 7 PM

Phone

+55 11 3256-4821

Get directions

Store locationCard · AspectRatio · DataList · LinkCode

GuidelinesCopy Anchor Link

Pousada da Serra

Casa do Farol

Chalé Vista Mar

DoOne ratio per row.

Photos of any shape end up the same size, and the titles line up.

Pousada da Serra

Casa do Farol

Chalé Vista Mar

Don’tEvery photo in its own shape.

The row goes ragged and the eye follows the gaps instead of the content.

Docontain for logos and products.

Their edges carry meaning; show all of it, with some padding.

Don’tcover on a wide logo.

The crop cuts off the brand name, which is the whole point.

PropsCopy Anchor Link

Styling hooksCopy Anchor Link

Restyle it without forking: target the slot, or set the custom property in your own CSS.

/* wider video on large screens, taller on phones */
.lesson [data-slot="aspect-ratio"] {
  --cml-aspect-ratio: 4 / 3;
}
@media (min-width: 48rem) {
  .lesson [data-slot="aspect-ratio"] {
    --cml-aspect-ratio: 16 / 9;
  }
}

AccessibilityCopy Anchor Link

• The box adds no role and no name. What's inside still needs one: alt on every image that means something, alt="" on decoration.
• Every iframe needs a title that says what it holds ("Map: Rua Augusta 1200"), or screen readers only announce "frame".
• A play button laid over a poster is an icon-only button: give it a name that includes the video's title.
• Cropping with cover can cut off text or faces. Don't put information in the edges of an image that might be cropped.

RelatedCopy Anchor Link