Aspect Ratio

A box that keeps its shape, whatever goes in it. The reason to reach for one is layout shift: the frame occupies its final size before the media has downloaded a byte, so a picture that arrives half a second later lands in space that was already there instead of shoving the rest of the page down.

PreviewCode

aspect-ratio/basic.tsx

Cais do Sodré, 19:40

◐AutoRTLReduced motionReset

Import

import { AspectRatio } from "@forte-ui/react";

Built on the property, not the trick

Radix — and therefore shadcn — draws an aspect box with the padding hack: a wrapper with padding-bottom: 56.25% and a single child pinned to position: absolute; inset: 0. That predates the aspect-ratio property, and it costs three things:

• The child has to leave flow. A second one — a caption, a play button, a gradient — needs its own absolute positioning and its own stacking order.
• A percentage padding always resolves against the container's inline size. So the box can only ever turn a width into a height; a height-constrained parent is not expressible at all.
• The ratio arrives as a pre-computed percentage. Restating it at another breakpoint means working out 9 / 16 * 100 by hand.

This component uses the property. Three of its features fall straight out of that: children stack without leaving flow, basis="block" measures on the other axis, and the ratio stays a CSS value a media query can restate.

Examples

Named ratios

ratio takes a number (16 / 9), a CSS ratio string ("16 / 9"), the spoken form ("16:9"), or one of seven names. Prefer a name where one fits: "story" says what the box is for, where 0.5625 says only what it measures.

Fitting the media

An <img> at its intrinsic size inside a fixed-shape box is either letterboxed or overflowing, so AspectRatio sizes direct media children to the frame and applies object-fit for you. Without that, every caller writes the same width: 100%; height: 100%; object-fit: cover on the child, forever.

cover is the default and what a media slot almost always wants. contain is right when the subject must not be cut — a logo, a diagram, a product shot on white.

PreviewCode

aspect-ratio/fit.tsx

cover — fills the frame, crops the rest

contain — whole image, bars at the sides

fill — stretched to the frame

none — intrinsic size, cropped by the frame

◐AutoRTLReduced motionReset

Choosing what survives the crop

cover has to throw something away. --forte-aspect-position is how you say which something — it is an object-position value, and its 50% 50% default is the one choice guaranteed to behead a portrait.

PreviewCode

aspect-ratio/focal.tsx

50% 0%

50% 50% (default)

50% 100%

◐AutoRTLReduced motionReset

Stacking, without position: absolute

The box is a one-cell grid and every direct child is placed in that cell, in source order. So a caption over a photo is two elements and an alignment — nothing leaves flow, nothing needs a z-index, and each layer still positions itself with place-self.

PreviewCode

aspect-ratio/overlay.tsx

◐AutoRTLReduced motionReset

Variants

variant is how much chrome the box carries. plain is pure layout. outlined adds a hairline frame, which gives light-on-light media an edge. filled adds a recessed panel — and because that panel is visible while the box is still empty, it is also the loading placeholder.

That last one is the anti-layout-shift story finished rather than started: the space is reserved and it looks reserved.

Measuring on the block axis

basis="block" takes a definite height and derives the width, which is the case a percentage padding cannot express. A fixed-height row of thumbnails is the usual reason to want it.

PreviewCode

aspect-ratio/basis.tsx

square

video

portrait

The row sets the height. Each frame derives its own width.

◐AutoRTLReduced motionReset

A ratio that changes with the layout

ratio does not set --forte-aspect-ratio. It seeds it: the prop writes --forte-aspect-ratio-seed as an inline style, and the stylesheet reads that into the knob from inside @layer forte.components.

The indirection exists because a ratio cannot be enumerated the way fit or variant can — there is no [data-ratio="…"] rule to write — so the value has to arrive inline, and an inline declaration outranks every author rule short of !important. ratio would then be the one prop in this library that plain CSS could not override. Seeding instead keeps the knob in a layer, where an ordinary class beats it:

.hero {
  --forte-aspect-ratio: 3 / 4;
}

@media (width >= 48rem) {
  .hero {
    --forte-aspect-ratio: 16 / 9;
  }
}

Which is a container query away from being the right thing in a component library:

PreviewCode

aspect-ratio/responsive.tsx

◐AutoRTLReduced motionReset

Letting something break the frame

clip is on by default — media overflowing its own frame is a bug, not a feature. Turn it off for the decoration that is meant to escape: a badge on a corner, a focus ring on a child, a tooltip anchored inside.

PreviewCode

aspect-ratio/unclipped.tsx

New

clip={true}

New

clip={false}

◐AutoRTLReduced motionReset

Changing the element

render swaps the <div> for whatever the box actually is — a <figure> around a caption, or the <a> that wraps a whole thumbnail.

PreviewCode

aspect-ratio/link.tsx

Sunset from the ferry

◐AutoRTLReduced motionReset

A focusable box rings: AspectRatio carries .forte-focus-ring, which costs a plain <div> nothing — the class only paints on :focus-visible, which a non-focusable element never matches. And the component declares no cursor at all, precisely so that a linked frame keeps the pointer the anchor already earns. Both are cases of doing less rather than more.

The UA's own defaults are left alone for the same reason: <figure> keeps its margin and <a> its colour, because a box that quietly stripped the element it was handed would be the harder thing to work around. Set them where you use them.

Accessibility

The box is layout. It renders no role, takes no focus, and adds nothing to the accessibility tree — which is correct, and means the accessibility of what you put in it is unchanged by putting it there.

Two things are still yours:

• alt on the image. An empty alt="" where the caption beside the frame already says it; real text where the picture carries information nothing else does. A decorative frame does not make its contents decorative.
• Contrast for anything laid over media. Text on a photograph has no guaranteed background, so SC 1.4.3 cannot be met by the text colour alone. Put it on a band or a scrim, as the overlay example does, rather than trusting the image to stay dark where the words are.

Theming

Every visual decision is a --forte-aspect-* custom property.

Nothing in the file transitions. The box has no states — no hover, no focus, no open or closed — so there is nothing to animate, and a colour transition on the placeholder would only make it lag the rest of the page on a theme switch.

State is on data-variant, data-fit, data-basis and data-clip, so a consumer can reach all four from plain CSS or a Tailwind arbitrary variant (data-[variant=filled]:...) without wrapping the component.

API reference