AspectRatio

A box that keeps a proportion whatever width it is given. It draws nothing of its own: it reserves the space and holds what is inside it to the shape.

import { AspectRatio } from 'neba';

<AspectRatio ratio={16 / 9} rounded>
  <img src={src} alt="A still alpine lake at dawn" />
</AspectRatio>;

Props

Prop	Type	Default	Description
ratio	number | string	1	The proportion the box holds, written the way CSS writes it: a number (1.5) or a ratio ('16 / 9'), reaching aspect-ratio untouched
fit	'cover' | 'contain' | 'fill' | 'none'	'cover'	How a single piece of media inside is fitted. Applies to an img, video, canvas, svg or iframe that is a direct child; anything else is laid out normally
rounded	boolean	false	Rounds the corners to the size step of the radius ladder. Off by default, because a layout component draws nothing
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Which step of the radius ladder rounded uses. As on Box, it never touches a height or the type scale
render	useRender.RenderProp	—	Renders something other than a div (render={<figure />}). Base UI's own escape hatch
children	ReactNode	—	What is held to the proportion

Native <div> attributes pass through, and render swaps the element. The shared axes are described in prop conventions.

Examples

ratio

ratio is CSS's own aspect-ratio, so a number (1.5) or a ratio ('16 / 9') both reach it untouched and there is nothing to translate.

import { AspectRatio } from 'neba';

const RATIOS: Array<{ label: string; ratio: string }> = [
  { label: '1 / 1', ratio: '1 / 1' },
  { label: '4 / 3', ratio: '4 / 3' },
  { label: '16 / 9', ratio: '16 / 9' },
  { label: '21 / 9', ratio: '21 / 9' }
];

export default function AspectRatioRatios() {
  return (
    <div className="grid w-full max-w-2xl grid-cols-2 gap-4 sm:grid-cols-4">
      {RATIOS.map(({ label, ratio }) => (
        <div key={label} className="flex flex-col gap-2">
          <AspectRatio
            ratio={ratio}
            rounded
            className="border border-(--neba-border) bg-(--neba-panel-hover)"
          >
            <div className="flex size-full items-center justify-center text-[0.75rem] text-(--neba-muted-fg)">
              {label}
            </div>
          </AspectRatio>
        </div>
      ))}
    </div>
  );
}

fit

fit is object-fit applied to a single piece of media that is a direct child: an img, a video, a canvas, an svg or an iframe. The media is stretched to the box first, which is the pair of declarations every use of this component would otherwise start with. cover crops, contain letterboxes, fill squashes.

import { AspectRatio, type NebaAspectFit } from 'neba';

const FITS: NebaAspectFit[] = ['cover', 'contain', 'fill'];

export default function AspectRatioFit() {
  return (
    <div className="grid w-full max-w-2xl grid-cols-1 gap-4 sm:grid-cols-3">
      {FITS.map((fit) => (
        <div key={fit} className="flex flex-col gap-2">
          <span className="text-[0.75rem] text-(--neba-muted-fg)">{fit}</span>
          {/* The source is 2:3 and the box is square, so each value has to give
              something up: `cover` crops, `contain` letterboxes, `fill` squashes. */}
          <AspectRatio ratio={1} fit={fit} rounded className="bg-(--neba-panel-hover)">
            <img
              src="/samples/photos/red-umbrella-autumn-path.jpg"
              alt="A red umbrella lying on a wet path of fallen leaves"
            />
          </AspectRatio>
        </div>
      ))}
    </div>
  );
}

Reserving the space

The proportion holds whether or not the content has arrived, so a Skeleton inside an AspectRatio occupies exactly the box the image will. Nothing below it moves when the image loads.

import { useState } from 'react';
import { AspectRatio, Button, Card, Skeleton } from 'neba';

export default function AspectRatioReserving() {
  const [loaded, setLoaded] = useState(false);

  return (
    <div className="flex w-full max-w-80 flex-col gap-3">
      {/* The box is the same height either way, so the card does not jump when
          the image arrives and nothing below it moves under the reader. */}
      <Card title="Alpine lake, dawn" subtitle="Uploaded 4 minutes ago">
        <AspectRatio ratio={16 / 9} rounded>
          {loaded ? (
            <img
              src="/samples/photos/alpine-lake-dawn.jpg"
              alt="A still alpine lake with the first light on the far ridge"
            />
          ) : (
            <Skeleton shape="rect" className="size-full" label="Loading the photograph" />
          )}
        </AspectRatio>
      </Card>

      <Button size="sm" variant="outline" onClick={() => setLoaded((value) => !value)}>
        {loaded ? 'Unload the image' : 'Load the image'}
      </Button>
    </div>
  );
}

rounded

rounded cuts the corners to the size step of the house radius ladder. It is off by default (a layout component draws nothing), and it is the one exception, because a photograph in a card almost always wants it.

<AspectRatio ratio={4 / 3} rounded size="lg">
  <img src={src} alt="" />
</AspectRatio>

Accessibility

• The box adds no role and no name. It is a shape, and what a reader hears is whatever is inside it.
• An img inside still needs its own alt. A decorative image takes alt="".