TYPO3: Using image crop variants with focus and cover areas

TYPO3’s image cropping supports multiple variants (e.g. default, mobile, hero) and offers powerful focus/cover area settings. Here’s a compact guide to configure crop variants in TCA and render them in Fluid.

1) Define cropVariants in TCA

Add (or extend) the fal_media/image column to define presets. Example for a content element with a default 16:9 and a square variant:

// Configuration/TCA/tt_content.php
$fields = [
  'assets' => [
    'exclude' => 1,
    'label' => 'Images',
    'config' => [
      'type' => 'file',
      'allowed' => 'common-image-types',
      'maxitems' => 5,
      'appearance' => [
        'createNewRelationLinkTitle' => 'Add image',
      ],
      'overrideChildTca' => [
        'columns' => [
          'crop' => [
            'config' => [
              'cropVariants' => [
                'default' => [
                  'title' => 'Default',
                  'allowedAspectRatios' => [
                    '16_9' => [ 'title' => '16:9', 'value' => 16/9 ],
                    'free' => [ 'title' => 'Free', 'value' => 0.0 ],
                  ],
                  'selectedRatio' => '16_9',
                ],
                'square' => [
                  'title' => 'Square',
                  'allowedAspectRatios' => [
                    '1_1' => [ 'title' => '1:1', 'value' => 1.0 ],
                  ],
                  'selectedRatio' => '1_1',
                ],
              ],
            ],
          ],
        ],
      ],
    ],
  ],
];

Focus/cover areas are available in the crop UI. Editors can set a focus point (to keep the important area visible) and a cover area (to ensure a minimum region stays inside the crop).

2) Fetch processed images in TypoScript (optional)

If you prefer DataProcessors for records:

# Configuration/TypoScript/Setup.typoscript
lib.contentElement = FLUIDTEMPLATE
lib.contentElement.dataProcessing {
  10 = TYPO3\CMS\Frontend\DataProcessing\FilesProcessor
  10 {
    references.fieldName = assets
    as = images
  }
}

This provides images including processed variants and crop information.

3) Render in Fluid with crop variants

Use f:image (or media ViewHelpers) and the cropVariant argument. TYPO3 will apply the editor-defined crop:

<f:for each="{images}" as="image">
  <figure>
    <f:image
      image="{image}"
      cropVariant="default"
      width="1200"
      alt="{image.properties.alternative}"
      title="{image.properties.title}"
    />
    <figcaption>{image.properties.title}</figcaption>
  </figure>
</f:for>

Switch to the square variant:

<f:image image="{image}" cropVariant="square" width="800" />

4) Responsive example with srcset

Let TYPO3 calculate responsive sizes:

<f:image
  image="{image}"
  cropVariant="default"
  srcset="600w, 900w, 1200w"
  sizes="(min-width: 1024px) 1200px, 100vw"
/>

5) Tips

Keep variant names consistent across elements (e.g., default, mobile, square).
Educate editors to use the focus point for better automated crops on tight aspect ratios.
Use free ratio for editorial freedom; enforce ratios where the layout requires it.
For backgrounds, you can still use the crop data to compute background-position with the focus point.

With crop variants and focus/cover areas, TYPO3 can deliver consistently framed images across breakpoints and layouts while giving editors excellent control.