Ouro HX

Layout

AspectRatio

A frame that keeps an image, video or map at a fixed shape while its width follows the layout, so the page does not jump when the media loads. The media fills it and is cropped to fit.

Short ribs in a dark pot

In Spoonjoy

Spoonjoy, a recipe app, is built with Ouro HX (how).

See it live, no sign-in needed: Test kitchen

In its source: app/routes/test-kitchen.tsx

Install

Once per app, with Tailwind CSS v4 and an @/* path alias (Ouro HX is built on Base UI, so --base base; skip -t in an existing app):

npx shadcn@latest init --base base --preset nova --yes --no-monorepo
npx shadcn@latest add ourostack/ouro-ui/ouro-base#v1.2.13

Then the component. From v0.8.0 it installs only the helpers it imports and never touches your stylesheet (Installing):

npx shadcn@latest add ourostack/ouro-ui/aspect-ratio#v1.2.13

Or, with the @ouro namespace set up:

npx shadcn@latest add @ouro/ouro-base @ouro/aspect-ratio

Its tests, stories and Playwright spec are optional. They need Vitest 4.1.11 or later, and from v0.8.0 never change a version your app has (Testing):

npx shadcn@latest add ourostack/ouro-ui/aspect-ratio#v1.2.13 ourostack/ouro-ui/aspect-ratio-tests#v1.2.13
import { AspectRatio } from "@/components/ouro/aspect-ratio/aspect-ratio";

Paths use shadcn's default @/ alias; the CLI rewrites them to yours.

Example

<AspectRatio ratio={16 / 9}>
  <img src={recipe.coverUrl} alt={recipe.title} />
</AspectRatio>

Use instead when

  • Use Card with media instead for a photo at the top of a card (put the AspectRatio in media), and Item with media for a thumbnail beside a row's title.

Props

Type: AspectRatioProps.

children (required)
Type: ReactNode
The media: one <img>, <video>, <iframe> or element, which fills the frame. Give an image alt text, or alt="" when it is decoration.
className
Type: string
Layout only: width, margins, grid placement (w-40). Appearance classes warn in development; put the frame in a Card for rounded corners.
fit
Type: "cover" | "contain"
Default: "cover"
How an image or video fills the frame: cover crops it to fill, contain shows all of it with bars.
ratio (required)
Type: number | (string & { "Use a number: ratio={16 / 9}": never })
Width divided by height, as a number: 16 / 9 for video, 4 / 3 for a photo, 1 for a square. The frame is as wide as its container and this much shorter.
ref
Type: Ref<HTMLDivElement>
Reaches the rendered element.

Native attributes

Also accepts the attributes in React's HTMLAttributes (id, aria-*, event handlers), passed to the rendered element, except those named on this page.

Don't use

These are not props. Passing one fails the type check with the fix in the error, and in development a console message names the fix.

  • aspectRatio: Not a prop. Ouro UI uses ratio: <AspectRatio ratio={16 / 9}>.

className is for layout only

Pass margins, width and grid placement (mt-4, w-full, col-span-2). Your classes always win over Ouro UI's: AspectRatio merges className last with cn (tailwind-merge), so a class that conflicts with its own replaces it.layout-classes

Appearance comes from props, not classes. In development, a class that sets appearance logs one warning per component instance, naming the prop to use instead. A class sets appearance when, after its variants (hover:, sm:) and any ! are removed, it starts with bg-, text-, border-, rounded-, shadow-, font-, ring-, from-, via-, to-, fill- or stroke-, or is border, rounded, shadow or ring, or has a dark: variant. Text wrapping, overflow and table layout classes (text-wrap, text-ellipsis, border-collapse) are layout and do not warn.

Alignment classes (text-center) warn too: set alignment on a parent element.

Claim sources

Source on GitHubThis page as Markdown