---
title: "Aspect Ratio Field"
manual: "Imaginator"
version: "1.0"
permalink: "https://docs.typo3.org/permalink/schliesser/imaginator:editor@1.0"
source: "Usage/AspectRatioField.rst"
rendered: "2026-10-13T11:21:40+00:00"
---

# Aspect Ratio Field {#editor}

Imaginator adds an **Aspect ratios** field to the content element's
**mediaAdjustments** palette. It appears only on content types that
render images.

![The Aspect ratios field in a content element's Media Adjustments palette](../Images/AspectRatioField.png)

The field stores a per-breakpoint ratio map as a JSON string, for example:

**Stored aspect_ratio value**

```json
{"xs": "1:1", "md": "4:3", "lg": "16:9"}
```

Keys are [breakpoint aliases](https://docs.typo3.org/permalink/schliesser/imaginator:confval-conf-breakpoints@1.0) (`md`, `lg`, …) or
literal min-widths in pixels (`768`; `0` is the base). A breakpoint that is
absent or set to `auto` inherits the next-smaller ratio.

A value may also be a fixed CSS height (`"600px"`) instead of a `"W:H"`
ratio: that tier pins the height while the width climbs the ladder. Use for e.g.
a full-width hero. See [Fixed-height tiers](https://docs.typo3.org/permalink/schliesser/imaginator:usage-fixed-height@1.0).

## Binding the field {#binding-the-field}

The raw column can be passed straight into the ViewHelper; no DataProcessor is
needed:

**Fluid template**

```html
<i:image image="{ref}" aspectRatio="{ce.data.aspect_ratio}"
         alt="{ce.data.header}"/>
```

The ViewHelper decodes the JSON map and resolves it to per-breakpoint
`<source>` tiers using the configured
[breakpoints](https://docs.typo3.org/permalink/schliesser/imaginator:confval-conf-breakpoints@1.0).

## Content Blocks {#editor-content-blocks}

When [EXT:content_blocks](https://extensions.typo3.org/extension/content_blocks) is installed, the
same field is available as a field type so block authors can declare it in YAML:

**ContentBlocks field definition**

```yaml
- identifier: aspect_ratio
  type: AspectRatio
  allowedRatios: '16:9,21:9'   # optional; defaults to the full set
```

`allowedRatios` is a comma-separated list of the ratios offered in the editor.
Omit it to expose the full default set.

> [!NOTE]
> The Content Blocks integration is optional. The field type class only loads
> when `EXT:content_blocks` is present.