suiss/ui · Component
Aspect Ratio
A container that keeps its content at a fixed width-to-height ratio.
Aspect Ratio is an open-source component from suiss/ui for React, React Native, SwiftUI and Jetpack Compose. The @esuiss/ui CLI copies its source into your project, so you own the code.
AspectRatio is a single div that sets the CSS aspect-ratio property from the ratio prop. Its width follows the parent, and its height is derived from the ratio. It is positioned relative, so children can be absolutely positioned inside it.
Use it to reserve space for images, video or embeds so the layout does not shift while media loads.
Installation
CLI
Works in any project with a components.json. See Installation for the one-line registry setup. Or use the suiss/ui CLI:
Manual
-
Add the
cnhelper. -
Copy the source into
components/ui/aspect-ratio.tsx:
- Update the import paths to match your project.
Usage
Pass ratio as a number, typically written as a division such as 16 / 9, 4 / 3 or 1. Give media inside it className="size-full object-cover" to fill the frame. Add overflow-hidden and a radius class to clip the content to rounded corners.
Examples
Square
A 1:1 frame using ratio={1}.
Portrait
A taller-than-wide frame using ratio={3 / 4}.
Placeholder
A 4:3 frame holding centered placeholder text instead of an image.
API Reference
AspectRatio
The ratio-locked container.
| Prop | Type | Default | Description |
|---|---|---|---|
ratio | number | Required | Width divided by height, for example 16 / 9. Required. |
Also accepts the props of React.ComponentProps<"div">.
Notes
- Styling hook:
data-slot="aspect-ratio". - The ratio is passed through the
--ratioCSS custom property and applied with the Tailwind classaspect-(--ratio).

AspectRatio is a View that sets the aspectRatio style from its ratio prop. Its height follows from the width it is given, so the content keeps its shape at any screen size.
Use it for images, video thumbnails and placeholders that must not stretch.
Installation
Manual
-
Add the pieces it builds on: the primitives
components/primitives/aspect-ratio.tsx. -
Copy the source into
components/ui/aspect-ratio.tsx:
- Update the import paths to match your project.
-
Add the pieces it builds on: the primitives
components/primitives/aspect-ratio.tsx. -
Copy the source into
components/ui/aspect-ratio.tsx:
- Update the import paths to match your project.
-
Add the pieces it builds on: the primitives
components/primitives/aspect-ratio.tsx. -
Copy the source into
components/ui/aspect-ratio.tsx:
- Update the import paths to match your project.
-
Target iOS 17 or later.
-
Copy the theme files every view uses:
- Copy the source:
- Add the files to your app target.
- Set
minSdkto 24 or higher and add the dependencies:
- Copy the theme files every view uses:
- Copy the source:
- Update the
com.esuiss.uipackage names to match your project.
Usage
Pass ratio as width divided by height, such as 16 / 9. It defaults to 1. Size the content inside with h-full w-full, and put rounding or clipping on a parent view.
Examples
Square
A square image with ratio={1}.

Portrait
A tall image with ratio={9 / 16}.

Placeholder
A placeholder surface with an icon instead of an image.

Accessibility
- The view adds no role; give images their own
accessibilityLabel.



