Aspect Ratio

Displays content within a fixed width-to-height ratio.

import { LandmarkIcon } from 'lucide-react'
import { AspectRatio } from '@/components/ui/aspect-ratio'

export function AspectRatioDemo() {
  return (
    <figure className="flex w-full max-w-md flex-col gap-2">
      <AspectRatio ratio={16 / 9}
        role="img"
        aria-label="City hall seen from the main square"
        className="flex items-center justify-center overflow-hidden rounded-lg bg-linear-to-br from-primary/20 via-muted to-chart-2/20"
      >
        <LandmarkIcon aria-hidden="true" className="size-12 text-primary/60" strokeWidth={1.25} />
      </AspectRatio>
      <figcaption className="text-xs text-muted-foreground">
        City hall, Stora torget 1. Photo: Communications office.
      </figcaption>
    </figure>
  )
}

Installation

pnpm dlx shadcn@latest add https://rdf.dev.360online.com/r/aspect-ratio.json

Installs to @/components/ui/aspect-ratio.

Manual installation

Copy the source into your project:

components/ui/aspect-ratio.tsx

import type * as React from 'react'
import { cn } from '@/lib/utils'

function AspectRatio({ ratio = 1, className, style, ...props }: React.ComponentProps<'div'> & { ratio?: number }) {
	return (
		<div
			data-slot="aspect-ratio"
			style={{ '--ratio': ratio, ...style } as React.CSSProperties}
			className={cn('relative aspect-(--ratio)', className)}
			{...props}
		/>
	)
}

export { AspectRatio }

Displays content within a desired ratio. The Aspect Ratio component uses the CSS aspect-ratio property and keeps images, maps, video embeds and document previews at fixed proportions regardless of the available width.

Features

Any numeric ratio, e.g. 16 / 9, 4 / 3 or 1
Scales with its container width
Works with images, iframes and arbitrary content
Plain CSS aspect-ratio, no primitive dependency

Usage

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

export function CityHallImage() {
  return (
    <div className="w-full max-w-md">
      <AspectRatio ratio={16 / 9} className="rounded-lg bg-muted">
        <img src="/city-hall.jpg" alt="City hall seen from the main square" className="h-full w-full rounded-lg object-cover" />
      </AspectRatio>
    </div>
  )
}

ratio defaults to 1. The component is a single div with position: relative and the CSS aspect-ratio, so className styles the ratio box itself and children can be placed with absolute too.

Examples

Default

A 16:9 image slot with a caption. The examples use token-based placeholders where your app would show a photo.

import { LandmarkIcon } from 'lucide-react'
import { AspectRatio } from '@/components/ui/aspect-ratio'

export function AspectRatioDemo() {
  return (
    <figure className="flex w-full max-w-md flex-col gap-2">
      <AspectRatio ratio={16 / 9}
        role="img"
        aria-label="City hall seen from the main square"
        className="flex items-center justify-center overflow-hidden rounded-lg bg-linear-to-br from-primary/20 via-muted to-chart-2/20"
      >
        <LandmarkIcon aria-hidden="true" className="size-12 text-primary/60" strokeWidth={1.25} />
      </AspectRatio>
      <figcaption className="text-xs text-muted-foreground">
        City hall, Stora torget 1. Photo: Communications office.
      </figcaption>
    </figure>
  )
}

Square

1:1 thumbnails for a grid of municipal facilities.

import { BookOpenIcon, TreesIcon, WavesIcon } from 'lucide-react'
import { AspectRatio } from '@/components/ui/aspect-ratio'

const FACILITIES = [
  { name: 'City library', hours: 'Open until 20:00', icon: BookOpenIcon, tint: 'from-chart-1/25 to-chart-1/5' },
  { name: 'Fyrisbadet', hours: 'Open until 21:00', icon: WavesIcon, tint: 'from-chart-2/25 to-chart-2/5' },
  { name: 'Stadsparken', hours: 'Always open', icon: TreesIcon, tint: 'from-chart-3/25 to-chart-3/5' },
]

export function AspectRatioSquare() {
  return (
    <ul className="grid w-full max-w-md grid-cols-3 gap-3">
      {FACILITIES.map(({ name, hours, icon: Icon, tint }) => (
        <li key={name} className="flex flex-col gap-1.5">
          <AspectRatio ratio={1} className={`flex items-center justify-center rounded-lg bg-linear-to-br ${tint}`}>
            <Icon aria-hidden="true" className="size-8 text-foreground/60" strokeWidth={1.5} />
          </AspectRatio>
          <div>
            <p className="text-sm font-medium">{name}</p>
            <p className="text-xs text-muted-foreground">{hours}</p>
          </div>
        </li>
      ))}
    </ul>
  )
}

Portrait

An A4 ratio (1 / Math.SQRT2) for a preview of a scanned or generated document.

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

const PARAGRAPH_1 = ['w-full', 'w-11/12', 'w-full', 'w-4/5', 'w-full', 'w-2/3'].map((width, line) => ({
  id: `p1-${line}`,
  width,
}))

const PARAGRAPH_2 = ['w-full', 'w-5/6', 'w-3/4'].map((width, line) => ({ id: `p2-${line}`, width }))

export function AspectRatioPortrait() {
  return (
    <div className="w-[220px]">
      <AspectRatio ratio={1 / Math.SQRT2} className="overflow-hidden rounded-md border bg-card shadow-sm">
        <div className="flex h-full flex-col gap-3 p-4" aria-label="Preview of decision document, page 1 of 3" role="img">
          <div className="flex items-center justify-between">
            <div className="size-5 rounded-sm bg-primary/20" />
            <div className="h-1.5 w-12 rounded-full bg-muted" />
          </div>
          <div className="flex flex-col gap-1">
            <p className="text-[0.625rem] font-semibold">Decision – Building permit</p>
            <p className="text-[0.5rem] text-muted-foreground">Case 2026-04812 · 3 March 2026</p>
          </div>
          <div className="flex flex-col gap-1.5">
            {PARAGRAPH_1.map(({ id, width }) => (
              <div key={id} className={`h-1 rounded-full bg-muted ${width}`} />
            ))}
          </div>
          <div className="flex flex-col gap-1.5">
            {PARAGRAPH_2.map(({ id, width }) => (
              <div key={id} className={`h-1 rounded-full bg-muted ${width}`} />
            ))}
          </div>
          <div className="mt-auto flex items-end justify-between">
            <div className="h-3 w-16 border-b border-foreground/30" />
            <span className="text-[0.5rem] text-muted-foreground">1 / 3</span>
          </div>
        </div>
      </AspectRatio>
    </div>
  )
}

Map Embed

A 4:3 container for an embedded property map, with overlays positioned on top.

import { MapPinIcon } from 'lucide-react'
import { AspectRatio } from '@/components/ui/aspect-ratio'

export function AspectRatioMapEmbed() {
  return (
    <div className="w-sm max-w-full">
      <AspectRatio ratio={4 / 3}
        role="img"
        aria-label="Map showing the property Eken 4:12 at Storgatan 14"
        className="overflow-hidden rounded-lg border bg-muted/50"
      >
        <div className="absolute inset-0 bg-[linear-gradient(var(--border)_1px,transparent_1px),linear-gradient(90deg,var(--border)_1px,transparent_1px)] bg-size-[32px_32px]" />
        <div className="absolute top-0 left-[38%] h-full w-3 bg-background" />
        <div className="absolute top-[55%] left-0 h-3 w-full bg-background" />
        <div className="absolute top-[18%] left-[48%] h-[30%] w-[32%] rounded-sm border-2 border-dashed border-primary bg-primary/10" />
        <MapPinIcon
          aria-hidden="true"
          className="absolute top-[24%] left-[60%] size-6 fill-primary text-primary-foreground"
        />
        <div className="absolute bottom-2 left-2 rounded-md bg-background/90 px-2 py-1 text-xs shadow-sm">
          <span className="font-medium">Eken 4:12</span>
          <span className="text-muted-foreground"> · Storgatan 14</span>
        </div>
      </AspectRatio>
    </div>
  )
}

Video

A 16:9 frame for a recorded council meeting, with a play button and duration.

import { PlayIcon } from 'lucide-react'
import { Badge } from '@/components/ui/badge'
import { Button } from '@/components/ui/button'
import { AspectRatio } from '@/components/ui/aspect-ratio'

export function AspectRatioVideo() {
  return (
    <div className="flex w-full max-w-md flex-col gap-2">
      <AspectRatio ratio={16 / 9}
        className="flex items-center justify-center overflow-hidden rounded-lg bg-linear-to-br from-muted to-primary/15"
      >
        <Badge variant="secondary" className="absolute top-2 left-2">
          Recording
        </Badge>
        <Button size="icon-lg" className="rounded-full" aria-label="Play council meeting recording">
          <PlayIcon />
        </Button>
        <span className="absolute right-2 bottom-2 rounded bg-background/90 px-1.5 py-0.5 text-xs tabular-nums">
          2:41:08
        </span>
      </AspectRatio>
      <div>
        <p className="text-sm font-medium">Municipal council meeting, 23 March 2026</p>
        <p className="text-sm text-muted-foreground">Budget 2027 and the new preschool in Norrby</p>
      </div>
    </div>
  )
}

Accessibility

Purely presentational: it does not add any roles or semantics
Always provide meaningful alt text for images placed inside
Give embedded iframes a descriptive title attribute