AspectRatio

The AspectRatio component constrains its children to a specified width-to-height ratio. It is built on React Native's View component and uses the native aspectRatio style property, making it perfect for images, videos, maps, and other media that need consistent proportions.

Preview

Installation

npx novaui-cli add aspect-ratio

Import

import { AspectRatio } from 'novaui-components'

Basic Usage

Wrap content in AspectRatio and set the desired ratio prop:

import { Image } from 'react-native'
import { AspectRatio } from 'novaui-components'

export function BasicAspectRatio() {
  return (
    <AspectRatio ratio={16 / 9} className="rounded-lg overflow-hidden bg-muted">
      <Image
        source={{ uri: 'https://example.com/photo.jpg' }}
        className="h-full w-full"
        resizeMode="cover"
      />
    </AspectRatio>
  )
}

Common Ratios

16:9 — Widescreen

Standard widescreen ratio for videos and hero images:

16:9

<AspectRatio ratio={16 / 9} className="rounded-lg bg-muted">
  <Image source={{ uri: 'https://example.com/video-thumb.jpg' }} className="h-full w-full" resizeMode="cover" />
</AspectRatio>

4:3 — Classic

Traditional photo and document ratio:

4:3

<AspectRatio ratio={4 / 3} className="rounded-lg bg-muted">
  <Image source={{ uri: 'https://example.com/photo.jpg' }} className="h-full w-full" resizeMode="cover" />
</AspectRatio>

1:1 — Square

Perfect for avatars, thumbnails, and profile images:

1:1

<AspectRatio ratio={1} className="rounded-lg bg-muted">
  <Image source={{ uri: 'https://example.com/avatar.jpg' }} className="h-full w-full" resizeMode="cover" />
</AspectRatio>

21:9 — Ultra-wide

For cinematic banners and panoramic content:

21:9

<AspectRatio ratio={21 / 9} className="rounded-lg bg-muted">
  <Image source={{ uri: 'https://example.com/panorama.jpg' }} className="h-full w-full" resizeMode="cover" />
</AspectRatio>

With Different Content

With Map Placeholder

Map View

import { View, Text } from 'react-native'
import { AspectRatio } from 'novaui-components'
import { MapPin } from 'lucide-react-native'

export function MapContainer() {
  return (
    <AspectRatio ratio={16 / 9} className="rounded-lg overflow-hidden border border-border">
      <View className="flex-1 items-center justify-center bg-muted">
        <MapPin className="text-muted-foreground" size={24} />
        <Text className="text-sm text-muted-foreground">Map View</Text>
      </View>
    </AspectRatio>
  )
}

Image Gallery Item

import { View, Image } from 'react-native'
import { AspectRatio } from 'novaui-components'

const images = [
  'https://example.com/photo1.jpg',
  'https://example.com/photo2.jpg',
  'https://example.com/photo3.jpg',
]

export function ImageGallery() {
  return (
    <View className="flex-row gap-2">
      {images.map((uri, i) => (
        <AspectRatio key={i} ratio={1} className="flex-1 rounded-md overflow-hidden bg-muted">
          <Image source={{ uri }} className="h-full w-full" resizeMode="cover" />
        </AspectRatio>
      ))}
    </View>
  )
}

Props API

AspectRatioProps

Extends React.ComponentPropsWithoutRef<typeof View> and includes:

Prop	Type	Default	Description
`ratio`	`number`	`1`	The width-to-height ratio (e.g., `16/9`, `4/3`, `1`)
`className`	`string`	-	Additional CSS classes. Base class is `w-full`
`style`	`ViewStyle`	-	Additional inline styles, merged with the aspect ratio style
`children`	`React.ReactNode`	-	Content to render inside the ratio container

Best Practices

Use for media: AspectRatio is ideal for images, videos, and embeds where consistent proportions matter.
Set a background: Add bg-muted as a placeholder background so the space is visible before content loads.
Combine with overflow-hidden: Use overflow-hidden with rounded-* for clean clipped corners on child content.
Responsive widths: The component uses w-full by default — control the width with a parent container or max-w-* classes.
Common ratios: Use standard ratios for familiarity — 16/9 for video, 4/3 for photos, 1/1 for thumbnails, 21/9 for banners.

Pair with Image for responsive image containers
Use inside Card for media-rich card layouts
Combine with Skeleton for loading placeholders with correct aspect ratios

Continue reading

Getting Started Components Overview Popular: Dialog SEO Playbook

AspectRatio

Continue reading

On this page