codefast/ui

Command Palette

Search for a command to run...

Source
Display

Aspect Ratio

Locks content to a specific width-to-height ratio. Useful for images, videos, and embeds.

Examples

Square

A 1/1 square crop for avatars and thumbnails.

Photo
19 lines
import { AspectRatio } from "@codefast/ui/aspect-ratio";
import { Image } from "@unpic/react";

export function AspectRatioSquare() {
  return (
    <div className="w-full max-w-48">
      <AspectRatio ratio={1 / 1} className="overflow-hidden rounded-lg">
        <Image
          alt="Photo"
          className="size-full object-cover grayscale"
          height={480}
          layout="constrained"
          src="https://images.unsplash.com/photo-1494337480532-3725c85fd2ab?auto=format&fit=crop&w=640&q=80"
          width={480}
        />
      </AspectRatio>
    </div>
  );
}

Portrait

A 9/16 portrait box for vertical media.

Photo
19 lines
import { AspectRatio } from "@codefast/ui/aspect-ratio";
import { Image } from "@unpic/react";

export function AspectRatioPortrait() {
  return (
    <div className="w-full max-w-40">
      <AspectRatio ratio={9 / 16} className="overflow-hidden rounded-lg">
        <Image
          alt="Photo"
          className="size-full object-cover grayscale"
          height={640}
          layout="constrained"
          src="https://images.unsplash.com/photo-1494337480532-3725c85fd2ab?auto=format&fit=crop&w=640&q=80"
          width={360}
        />
      </AspectRatio>
    </div>
  );
}

RTL

Right-to-left layout support for languages such as Arabic and Hebrew.

Translations are AI-generated for demonstration and may be imperfect.

منظر طبيعي جميل
منظر طبيعي جميل
46 lines
import { AspectRatio } from "@codefast/ui/aspect-ratio";
import { Image } from "@unpic/react";

import type { Translations } from "#/features/components-catalog/components/detail/language";
import { useTranslation } from "#/features/components-catalog/components/detail/language-context";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      caption: "Beautiful landscape",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      caption: "منظر طبيعي جميل",
    },
  },
  he: {
    dir: "rtl",
    values: {
      caption: "נוף יפה",
    },
  },
};

export function AspectRatioRtl() {
  const { dir, t } = useTranslation(translations, "ar");

  return (
    <figure className="w-full max-w-sm" dir={dir}>
      <AspectRatio ratio={16 / 9} className="overflow-hidden rounded-lg">
        <Image
          alt={t.caption}
          className="size-full object-cover grayscale"
          height={360}
          layout="constrained"
          src="https://images.unsplash.com/photo-1494337480532-3725c85fd2ab?auto=format&fit=crop&w=640&q=80"
          width={640}
        />
      </AspectRatio>
      <figcaption className="mt-2 text-center text-sm text-ui-muted">{t.caption}</figcaption>
    </figure>
  );
}

Anatomy

How the parts nest — every slot the component exposes, in composition order.

AspectRatio

Features

  • A single ratio prop (width ÷ height) constrains the child — no manual padding-hack CSS needed.
  • Reserves space before the child loads, preventing layout shift for images, video, and embeds.

API reference

Props for each part of the component. All native element props are also forwarded.

AspectRatio

Constrains its child to a fixed width-to-height ratio.

rationumber

Width ÷ height, e.g. 16 / 9. The child fills the box.

Default1

Accessibility

Built to be keyboard-navigable and screen-reader friendly out of the box.

  • Purely a layout helper — give the inner media its own alt text.
  • Use object-cover (or contain) on images so they fill the locked box correctly.
  • Helps prevent layout shift by reserving space before media loads.

Guidelines

Conventions that keep usage consistent across an app.

Do

  • Use for images, video, embeds, and map tiles that must keep a shape.
  • Combine with overflow-hidden + rounded corners for media cards.

Don’t

  • Don’t use it for text content that should grow with its length.
  • Don’t forget object-fit on the inner image.

Explore further

Ready to integrate?

Follow the Getting Started guide to install @codefast/ui, or browse the full component gallery.

Getting StartedBrowse all components