<arc-aspect-ratio> Overview
Guidelines
When to use
- Use Aspect Ratio around images and videos to prevent layout shift during page load
- Choose standard ratios that match your media: `16/9` for video, `4/3` for photos, `1/1` for avatars or thumbnails
- Place Aspect Ratio inside grid or flex containers where the width is determined by the layout
- Use decimal ratios like `2.35/1` for cinematic or ultrawide content when needed
- Combine with lazy loading on images for optimal performance -- the space is reserved before the image loads
When not to use
- Do not use Aspect Ratio when the content has its own intrinsic dimensions and layout shift is not a concern
- Do not place text-heavy content inside Aspect Ratio -- it clips overflow and does not scroll
- Do not set both a fixed height and Aspect Ratio on the same element -- they will conflict
- Do not use ratio values with zero in the denominator (e.g. `16/0`) -- the component falls back to 16/9
- Avoid nesting multiple Aspect Ratio components -- the inner one will be constrained by both ratios unpredictably
Features
- Enforces a consistent aspect ratio using the CSS `aspect-ratio` property with a `W/H` string prop
- Slotted children automatically sized to fill with `width: 100%`, `height: 100%`, and `object-fit: cover`
- Prevents content layout shift (CLS) by reserving space before media loads
- Supports any valid ratio including standard formats (`16/9`, `4/3`, `1/1`) and decimals (`2.35/1`)
- Falls back to `16/9` if the ratio string is invalid or malformed
- Applies `border-radius: var(--radius-md)` with overflow clipping for rounded media corners
- Full-width container that fills its parent, making it ideal for responsive grid cells
- Lightweight wrapper with no JavaScript interaction -- purely CSS-driven layout
Preview
16 / 9
Usage
<arc-aspect-ratio ratio="16/9">
<img src="/hero.jpg" alt="Hero banner" />
</arc-aspect-ratio>
<!-- Square thumbnail -->
<arc-aspect-ratio ratio="1/1">
<img src="/avatar.jpg" alt="User avatar" />
</arc-aspect-ratio>import { AspectRatio } from '@arclux/arc-ui-react';
<AspectRatio ratio="16/9">
<img src="/hero.jpg" alt="Hero banner" />
</AspectRatio>
{/* Square thumbnail */}
<AspectRatio ratio="1/1">
<img src="/avatar.jpg" alt="User avatar" />
</AspectRatio><script setup>
import { AspectRatio } from '@arclux/arc-ui-vue';
</script>
<template>
<AspectRatio ratio="16/9">
<img src="/hero.jpg" alt="Hero banner" />
</AspectRatio>
<!-- Square thumbnail -->
<AspectRatio ratio="1/1">
<img src="/avatar.jpg" alt="User avatar" />
</AspectRatio>
</template><script>
import { AspectRatio } from '@arclux/arc-ui-svelte';
</script>
<AspectRatio ratio="16/9">
<img src="/hero.jpg" alt="Hero banner" />
</AspectRatio>
<!-- Square thumbnail -->
<AspectRatio ratio="1/1">
<img src="/avatar.jpg" alt="User avatar" />
</AspectRatio>import { Component } from '@angular/core';
import { AspectRatio } from '@arclux/arc-ui-angular';
@Component({
imports: [AspectRatio],
template: `
<AspectRatio ratio="16/9">
<img src="/hero.jpg" alt="Hero banner" />
</AspectRatio>
<!-- Square thumbnail -->
<AspectRatio ratio="1/1">
<img src="/avatar.jpg" alt="User avatar" />
</AspectRatio>
`,
})
export class MyComponent {}import { AspectRatio } from '@arclux/arc-ui-solid';
<AspectRatio ratio="16/9">
<img src="/hero.jpg" alt="Hero banner" />
</AspectRatio>
{/* Square thumbnail */}
<AspectRatio ratio="1/1">
<img src="/avatar.jpg" alt="User avatar" />
</AspectRatio>import { AspectRatio } from '@arclux/arc-ui-preact';
<AspectRatio ratio="16/9">
<img src="/hero.jpg" alt="Hero banner" />
</AspectRatio>
{/* Square thumbnail */}
<AspectRatio ratio="1/1">
<img src="/avatar.jpg" alt="User avatar" />
</AspectRatio><!-- Auto-generated by @arclux/prism — do not edit manually -->
<!-- arc-aspect-ratio — requires aspect-ratio.css + tokens.css (or arc-ui.css) -->
<div class="arc-aspect-ratio">
<div
class="aspect-ratio"
style="aspect-ratio: _aspect Ratio;"
>
<div class="aspect-ratio__inner">
Aspect Ratio
</div>
</div>
</div><!-- Auto-generated by @arclux/prism — do not edit manually -->
<!-- arc-aspect-ratio — self-contained, no external CSS needed -->
<div class="arc-aspect-ratio" style="display: block">
<div
style="position: relative; width: 100%; overflow: hidden; border-radius: 10px"
style="aspect-ratio: _aspect Ratio;"
>
<div style="width: 100%; height: 100%">
Aspect Ratio
</div>
</div>
</div>API
| Prop | Type | Default | Description |
|---|---|---|---|
ratio | string | '16/9' | Aspect ratio as a `W/H` string. Supports integers and decimals. Falls back to `16/9` if invalid. |