Layout

AspectRatio

Generic media box that enforces a fixed aspect ratio for arbitrary embedded content using the native CSS aspect-ratio property.

import { AspectRatio } from '@lostgradient/cinder/aspect-ratio';
layoutmedia
01

Overview

Generic wrapper that preserves a fixed aspect ratio for arbitrary embedded content using the native CSS aspect-ratio property.

Usage

svelte 
<script lang="ts">
  import AspectRatio from '@lostgradient/cinder/aspect-ratio';
</script>

<AspectRatio>
  <div>Media content</div>
</AspectRatio>

For iframe and video embeds, make the child fill the positioned wrapper:

svelte 
<AspectRatio ratio="16 / 9">
  <iframe
    title="Example video"
    src="https://example.com/embed"
    style="position: absolute; inset: 0; inline-size: 100%; block-size: 100%; border: 0;"
  ></iframe>
</AspectRatio>
Live preview
02

When to use

Use when
  • Reserving stable space for embedded media, previews, or art-directed content before it loads.
  • You need a generic ratio wrapper for iframe, video, canvas, or custom content rather than an image-specific primitive.
Avoid when
  • The child already owns its sizing contract and should determine its own height naturally.
  • Supporting legacy browsers that lack native aspect-ratio support.
03

Examples

Basic 16:9 media box

The default ratio reserves a responsive widescreen box.

Embedded media composition

Children can fill the box by absolutely positioning themselves inside the relative wrapper.

Numeric 4:3 ratio

Finite numeric values serialize directly onto the native CSS property.

Square ratio

String ratios pass through unchanged, including human-readable forms like 1 / 1.

04

Props

Props for aspect-ratio
Name Type Default Required Bindable Description
ratio string | number '16/9' Aspect ratio to apply. Accepts any valid native CSS aspect-ratio value.
overflow 'hidden' | 'visible' 'hidden' Overflow behavior for content that bleeds outside the ratio box.
as 'object''a''abbr''address''article''aside''audio''b''bdi''bdo''blockquote''body''button''canvas''caption''cite''code''colgroup''data''datalist''dd''del''details''dfn''dialog''div''dl''dt''em''fieldset''figcaption''figure''footer''form''h1''h2''h3''h4''h5''h6''head''header''hgroup''html''i''iframe''ins''kbd''label''legend''li''main''map''mark''menu''meter''nav''noscript''ol''optgroup''option''output''p''picture''pre''progress''q''rp''rt''ruby''s''samp''script''search''section''select''slot''small''span''strong''style''sub''summary''sup''table''tbody''td''template''textarea''tfoot''th''thead''time''title''tr''u''ul''var''video' 'div' Element tag to render. Defaults to 'div'.
children snippet req Required content rendered inside the ratio box.