AspectRatio

Layout

A stable proportional container for media and previews.

16:9 landscape1:1 square

Responsive viewport — resize the window to explore. Direction and density apply only to this preview. Theme applies to the docs too.

aspect-ratio.tsx

"use client";

import { AspectRatio } from "@/components/ui/aspect-ratio";
import { Mountain } from "lucide-react";

export default function AspectRatioExample() {
  return (
    <div className="grid w-full max-w-lg grid-cols-2 items-start gap-4">
      {[
        { ratio: 16 / 9, label: "16:9 landscape" },
        { ratio: 1, label: "1:1 square" },
      ].map((item) => (
        <div key={item.label} className="space-y-2">
          <AspectRatio
            ratio={item.ratio}
            className="flex items-center justify-center border bg-primary/5"
          >
            <Mountain aria-hidden className="size-10 text-primary" />
          </AspectRatio>
          <p className="text-center text-xs text-muted-foreground">
            {item.label}
          </p>
        </div>
      ))}
    </div>
  );
}

Usage

Set ratio to width divided by height. Place an image or other media inside the container and size it to fill the available space. This preserves layout space before media loads.

Import

import { AspectRatio } from "@/components/ui/aspect-ratio";

Shipped as editable source in src/components/ui/aspect-ratio.tsx in both apps. Copy the implementation below when moving it to another project. Copy the complete example from Source code for all imports and state. Add "use client" when using hooks or event handlers. See installation and theming for project setup.

Component source

The complete implementation is included in both apps. It uses the React, Radix, Lucide, and shared-core dependencies already installed in Apex. Keep your project’s semantic theme tokens when reusing it.

src/components/ui/aspect-ratio.tsx

"use client";

import type { ComponentProps } from "react";
import { cn } from "@dashboardpack/core/lib/utils";

import { AspectRatio as Primitive } from "radix-ui";
export function AspectRatio({
  className,
  ...props
}: ComponentProps<typeof Primitive.Root>) {
  return (
    <Primitive.Root
      className={cn("overflow-hidden rounded-xl", className)}
      {...props}
    />
  );
}

API reference

Common props and defaults. Slot-specific props are named below; native elements also accept their standard HTML attributes. The component TypeScript definitions are the complete type reference.

AspectRatio props
Prop	Type / Default	Description
ratio	`number` Default: 1	Width divided by height; use a positive number.
children	`ReactNode` Default: —	Media or other proportional content.
className	`string` Default: —	Extend the rounded, clipped container.

Build with these too

Card Skeleton