# AspectRatio

> Holds images, video and embeds to a fixed width-to-height ratio so layouts never shift.

Category: Layout · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/aspect-ratio

AspectRatio reserves space for images, video and embeds before they load, so the layout does not shift. Its single child fills the box; images and video default to object-fit: cover.

## Import

```tsx
import { AspectRatio } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### 16:9

```tsx
import { AspectRatio } from '@bindshq/stance-react';

const art = (label: string) => (
  <svg viewBox="0 0 160 90" preserveAspectRatio="xMidYMid slice" role="img" aria-label={label}>
    <rect width="160" height="90" fill="var(--st-color-bg-muted)" />
    <circle cx="120" cy="30" r="40" fill="var(--st-color-bg-emphasis)" />
    <rect x="16" y="56" width="64" height="8" rx="4" fill="var(--st-color-fg-subtle)" />
    <rect x="16" y="70" width="40" height="6" rx="3" fill="var(--st-color-border-strong)" />
  </svg>
);

export function Basic() {
  return (
    <div style={{ width: '100%', maxWidth: 480 }}>
      <AspectRatio ratio={16 / 9}>{art('Product walkthrough poster')}</AspectRatio>
    </div>
  );
}
```

### Square

```tsx
import { AspectRatio } from '@bindshq/stance-react';

const art = (label: string) => (
  <svg viewBox="0 0 160 90" preserveAspectRatio="xMidYMid slice" role="img" aria-label={label}>
    <rect width="160" height="90" fill="var(--st-color-bg-muted)" />
    <circle cx="120" cy="30" r="40" fill="var(--st-color-bg-emphasis)" />
    <rect x="16" y="56" width="64" height="8" rx="4" fill="var(--st-color-fg-subtle)" />
    <rect x="16" y="70" width="40" height="6" rx="3" fill="var(--st-color-border-strong)" />
  </svg>
);

export function Square() {
  return (
    <div style={{ width: 180 }}>
      <AspectRatio ratio={1}>{art('Team avatar')}</AspectRatio>
    </div>
  );
}
```

### Portrait 3:4

```tsx
import { AspectRatio } from '@bindshq/stance-react';

const art = (label: string) => (
  <svg viewBox="0 0 160 90" preserveAspectRatio="xMidYMid slice" role="img" aria-label={label}>
    <rect width="160" height="90" fill="var(--st-color-bg-muted)" />
    <circle cx="120" cy="30" r="40" fill="var(--st-color-bg-emphasis)" />
    <rect x="16" y="56" width="64" height="8" rx="4" fill="var(--st-color-fg-subtle)" />
    <rect x="16" y="70" width="40" height="6" rx="3" fill="var(--st-color-border-strong)" />
  </svg>
);

export function Portrait() {
  return (
    <div style={{ width: 180 }}>
      <AspectRatio ratio={3 / 4}>{art('Contract cover page')}</AspectRatio>
    </div>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| AspectRatio | `ratio` | `number` | `16 / 9` | Width divided by height. |

## Accessibility

- AspectRatio adds no semantics. Give the media inside it a text alternative.

## Guidelines

**Do**

- Use for any media whose size is known in advance.

**Don’t**

- Put text content inside; it may be clipped.

## Related

- https://stanceui.com/components/image
