What does it do? 

Media Utils provides responsive image rendering for TYPO3 and bundles reusable Fluid partials and ViewHelpers for working with image and media files.

It can render classic responsive img markup with srcset and sizes or picture markup with breakpoint-specific source tags. The output is configured through TYPO3 site sets and TypoScript settings.

Main features 

• Responsive image rendering with srcset and sizes.
• Optional picture tag rendering with configurable breakpoints.
• Native lazy loading via loading="lazy".
• JavaScript lazy loading support via data-src and data-srcset.
• Optional placeholder images, including inline base64 placeholders.
• Configurable output file extension, for example WebP.
• Configurable ignored file extensions, for example SVG and GIF.
• Width limits to avoid unnecessary image upsizing.
• TYPO3 v14 batch image processing when available.
• Reusable Utils/Media partial for images and videos.
• Own Fluid ViewHelpers under the Madj2k\MediaUtils namespace.
• File helper ViewHelpers for FAL properties, relations and crop-variant CSS classes.
• Default and Bootstrap site sets.
• Backend-editable settings via settings.definitions.yaml.
• Compatibility with projects migrating from EXT:sms_responsive_images.

Rendering concept 

The extension separates the rendering into small services:

• the ViewHelpers collect arguments and settings,
• the responsive image service prepares image options,
• generators create srcset candidates and placeholders,
• renderers build img, source and picture tags,
• TYPO3's renderer registry is used for non-image media files.

This keeps Fluid templates concise while still allowing detailed control over individual images or media elements.

Requirements 

Composer installation 

Install the extension with Composer:

composer require madj2k/t3-media-utils

Site set 

Include one of the shipped site sets in your site package configuration.

Default configuration:

name: your/site-package
label: 'Site Package'
dependencies:
  - madj2k/media-utils

Bootstrap-oriented picture configuration:

name: your/site-package
label: 'Site Package'
dependencies:
  - madj2k/media-utils-bootstrap

The Bootstrap set depends on the default set and provides breakpoint-oriented picture configuration for common Bootstrap breakpoints.

Allow WebP output 

When you want to render processed images as WebP, add webp to the allowed TYPO3 image file extensions in config/system/settings.php or the respective project configuration:

$GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext'] =
    'gif,jpg,jpeg,tif,tiff,bmp,pcx,tga,png,pdf,ai,svg,webp';

Template paths 

The extension ships reusable partials under:

EXT:media_utils/Resources/Private/Partials/

The site sets register the default TypoScript configuration. For custom extensions or manually configured Fluid templates, add the partial root path explicitly when necessary.

From EXT:sms_responsive_images 

Media Utils is designed to be compatible with projects that previously used EXT:sms_responsive_images. The Composer package declares a replacement for sitegeist/sms-responsive-images and the TYPO3 extension metadata declares a conflict with the old extension key.

Obsolete sitegeist/sms-responsive-images ViewHelper references 

Do not use the old namespace anymore:

xmlns:sms="http://typo3.org/ns/Sitegeist/SmsResponsiveImages/ViewHelpers"

Use the Media Utils namespace instead:

xmlns:mediaUtils="http://typo3.org/ns/Madj2k/MediaUtils/ViewHelpers"

Old direct usage:

<sms:media file="{file}" />

New direct usage:

<mediaUtils:responsiveImages.media file="{file}" settings="{settings}" />

Recommended migration path 

1. Include the madj2k/media-utils or madj2k/media-utils-bootstrap site set.
2. Configure the responsive image defaults in the backend under Settings > MediaUtils.
3. Keep existing lib.txMediaUtils.responsiveImages integrations. This is the documented global TypoScript object for Media Utils.
4. Replace old sitegeist/sms-responsive-images ViewHelper namespaces with the Media Utils namespace when templates are touched.
5. Prefer the bundled Utils/Media partial for new implementations.
6. Keep compatibility aliases only for existing templates that cannot be migrated immediately.

Compatibility with older sitegeist/sms-responsive-images-based implementations 

Version 14 is compatible with older implementations that previously used Media Utils together with sitegeist/sms-responsive-images, for example projects based on version 13 plus sitegeist/sms-responsive-images. Existing settings below lib.txMediaUtils.responsiveImages and the legacy tx_smsresponsiveimages settings are still considered during rendering, so projects can be upgraded first and templates can be migrated step by step.

For new code, use the Media Utils ViewHelpers and namespace directly:

xmlns:mediaUtils="http://typo3.org/ns/Madj2k/MediaUtils/ViewHelpers"

Deprecated Mask usage 

The extension still adds partial paths to lib.maskContentElement for legacy projects. New implementations should prefer EXT:content-blocks or direct Fluid template integration.

README audit notes 

During documentation creation, the README was checked against the current extension source. The following points were updated in this manual:

• sitegeist/sms-responsive-images ViewHelper examples were removed and replaced with Media Utils ViewHelpers.
• Direct ViewHelper examples now use Madj2k\MediaUtils namespaces.
• The documented global TypoScript object remains lib.txMediaUtils.responsiveImages.
• Features visible in the source but not fully described in the README were added, including placeholder generation, focus-area metadata, TYPO3 renderer registry usage for non-image media and file helper ViewHelpers.

Configuration sources 

The extension ships TYPO3 site sets with ready-to-use responsive image configuration. These sets expose their options through settings.definitions.yaml, so project defaults can be adjusted in the TYPO3 backend.

Available site sets 

Backend settings 

After including one of the shipped site sets, the responsive image configuration can be adjusted in the TYPO3 backend under Settings > MediaUtils.

Use these backend settings for project-wide defaults such as lazy loading, placeholder handling, srcset values, breakpoint definitions, ignored file extensions and the target image file extension.

Available responsive image options 

Default set 

The default set renders classic responsive image markup using srcset and sizes. Its default srcset is:

400, 600, 800, 1000, 1200

SVG and GIF files are ignored by default because responsive image processing is usually not useful for these formats.

Bootstrap set 

The Bootstrap set is configured for picture markup. It defines desktop, tablet and mobile breakpoints and can render WebP output by default.

Example structure:

settings.txMediaUtils.responsiveImages {
    loading = lazy
    breakpoints {
        0 {
            cropVariant = default
            media = (min-width: 992px)
            srcset = 1200, 1400, 1920, 2800, 3840
            sizes = (min-width: %1$dpx) %1$dpx, 100vw
        }
        1 {
            cropVariant = default
            media = (min-width: 576px)
            srcset = 768, 992
            sizes = (min-width: %1$dpx) %1$dpx, 100vw
        }
        2 {
            cropVariant = default
            media = (min-width: 0px)
            srcset = 390, 576
            sizes = (min-width: %1$dpx) %1$dpx, 100vw
        }
    }
}

Reusable TypoScript lib 

The extension provides the responsive image configuration as a TypoScript lib object:

lib.txMediaUtils.responsiveImages

This is not a separate global settings API. It is a reusable TypoScript library that can be copied into the settings of a custom Fluid template, content element or extension.

Example for a custom extension or Fluid template:

tx_myextension.settings.txMediaUtils.responsiveImages < lib.txMediaUtils.responsiveImages

Example for a content element:

tt_content.vendor_element {
    settings.txMediaUtils.responsiveImages < lib.txMediaUtils.responsiveImages
}

Other 

Crop variants per breakpoint 

Responsive images can use different TYPO3 crop variants for different breakpoints. This is useful when the same image should be cropped differently on desktop, tablet and mobile viewports.

The responsive image configuration is passed through settings.txMediaUtils.responsiveImages. Each entry below breakpoints can select a TYPO3 crop variant with the cropVariant option.

tt_content.vendor_element {
    settings {
        txMediaUtils.responsiveImages {
            loading = eager
            breakpoints {
                0 {
                    cropVariant = default
                }
                1 {
                    cropVariant = tablet
                }
                2 {
                    cropVariant = mobile
                }
            }
        }
    }
}

In this example the generated responsive image output uses:

The crop variant names must exist in the TCA crop configuration of the used field. Media Utils does not create the crop variants automatically; it reads the crop information stored on the FAL reference and applies the variant configured for the current breakpoint.

Call the bundled media partial as usual:

<f:render partial="Utils/Media"
          arguments="{file: image, maxWidth: 1000, settings: settings}" />

If maxWidth or width is passed directly to the partial, that explicit argument has priority. If no explicit dimension is passed, the partial falls fall back to dimensions configured in the selected settings group below settings.media. The responsive image configuration from settings.txMediaUtils.responsiveImages is applied automatically.

Settings variants 

A content element often has more than one visual style, for example a compact small variant and a full-width big variant. In this case you can group media-related settings below sub-keys in settings.media and select the desired group with the settingsVariant argument.

tt_content.vendor_element {
    settings {
        media {
            small {
                image {
                    dimensions {
                        maxWidth = 650
                    }
                }
                video {
                    dimensions {
                        width = 1370
                        height = 771
                    }
                    additionalConfig {
                        autoplay = 1
                        mute = 1
                        loop = 0
                        modestbranding = 1
                    }
                }
            }

            big {
                image {
                    dimensions {
                        maxWidth = 1200
                    }
                }
                video {
                    dimensions {
                        width = 1920
                        height = 1080
                    }
                    additionalConfig {
                        autoplay = 1
                        mute = 1
                        loop = 0
                        modestbranding = 1
                    }
                }
            }
        }
    }
}

Render the small variant like this:

<f:render partial="Utils/Media"
          arguments="{file: image, maxWidth: 1000, settings: settings, settingsVariant: 'small'}" />

Render the big variant like this:

<f:render partial="Utils/Media"
          arguments="{file: image, settings: settings, settingsVariant: 'big'}" />

The selected settingsVariant only changes the selected settings group below settings.media. The responsive image configuration below settings.txMediaUtils.responsiveImages is still used for breakpoint, srcset, sizes, lazy-loading and crop-variant handling.

Explicit partial arguments 

Values passed directly to the partial have priority over values from the selected settings variant.

Example:

<f:render partial="Utils/Media"
          arguments="{file: image, maxWidth: 1000, settings: settings, settingsVariant: 'small'}" />

In this case, the explicit maxWidth value is used for the rendered image. If maxWidth or width is omitted, the partial can use the configured value from settings.media.small.image.dimensions.

Combining variants and crop variants 

You can combine both concepts: use settingsVariant for the semantic style of the content element and use breakpoints.*.cropVariant for the image crop used inside the generated responsive image sources.

tt_content.vendor_element {
    settings {
        media {
            teaser.image.dimensions.maxWidth = 720
            hero.image.dimensions.maxWidth = 1600
        }

        txMediaUtils.responsiveImages {
            loading = lazy
            breakpoints {
                0 {
                    cropVariant = default
                }
                1 {
                    cropVariant = tablet
                }
                2 {
                    cropVariant = mobile
                }
            }
        }
    }
}

<f:render partial="Utils/Media"
          arguments="{file: image, settings: settings, settingsVariant: 'hero'}" />

In this example, hero selects the default dimensions from settings.media.hero. The final image sources still use the configured crop variants default, tablet and mobile for the generated breakpoints.

Usage in Fluid templates 

When using a manually configured FLUIDTEMPLATE, add the partial path and merge the responsive image settings:

lib.siteDefault.stage = FLUIDTEMPLATE
lib.siteDefault.stage {
    file = EXT:site_default/Resources/Private/Templates/Stage.html
    partialRootPaths.10 = EXT:site_default/Resources/Private/Partials/
    partialRootPaths.1712245685 = {$plugin.tx_mediautils.view.partialRootPath}

    dataProcessing {
        10 = TYPO3\CMS\Frontend\DataProcessing\FilesProcessor
        10 {
            references {
                table = pages
                data = levelfield: -1, media, slide
            }
            as = media
        }
    }

    settings.txMediaUtils.responsiveImages < lib.txMediaUtils.responsiveImages
    settings.txMediaUtils.responsiveImages.loading = eager
}

Usage in custom extensions 

Add the Media Utils partial path:

tx_myextension {
    view {
        partialRootPaths {
            1712245685 = {$plugin.tx_mediautils.view.partialRootPath}
        }
    }
}

Merge the global defaults into your extension settings:

tx_myextension.settings.txMediaUtils.responsiveImages < lib.txMediaUtils.responsiveImages

Render the partial:

<f:render partial="Utils/Media"
          arguments="{file: image, width: 1000, settings: settings}" />

Direct ViewHelper usage 

Use the extension's own ViewHelpers. Do not use the old namespace of sitegeist/sms-responsive-images.

<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
      xmlns:mediaUtils="http://typo3.org/ns/Madj2k/MediaUtils/ViewHelpers"
      data-namespace-typo3-fluid="true">

<mediaUtils:responsiveImages.media
    file="{file}"
    width="{dimensions.width}"
    height="{dimensions.height}"
    alt="{file.alternative}"
    title="{file.title}"
    srcset="{settings.txMediaUtils.responsiveImages.srcset}"
    lazyload="{settings.txMediaUtils.responsiveImages.lazyload}"
    placeholderSize="{settings.txMediaUtils.responsiveImages.placeholder.size}"
    placeholderInline="{settings.txMediaUtils.responsiveImages.placeholder.inline}"
    sizes="{settings.txMediaUtils.responsiveImages.sizes}"
    breakpoints="{settings.txMediaUtils.responsiveImages.breakpoints}"
    ignoreFileExtensions="{settings.txMediaUtils.responsiveImages.ignoreFileExtensions}"
    fileExtension="{settings.txMediaUtils.responsiveImages.fileExtension}"
    loading="{settings.txMediaUtils.responsiveImages.loading}"
    decoding="async"
/>

</html>

Namespace 

Use the Media Utils namespace in Fluid templates:

<html xmlns:mediaUtils="http://typo3.org/ns/Madj2k/MediaUtils/ViewHelpers"
      data-namespace-typo3-fluid="true">

Responsive image ViewHelpers 

<mediaUtils:responsiveImages.image
    image="{image}"
    width="1000"
    alt="{image.alternative}"
    title="{image.title}"
    settings="{settings}"
/>

<mediaUtils:responsiveImages.media
    file="{file}"
    width="1370"
    height="771"
    additionalConfig="{autoplay: 1, muted: 1, loop: 0, playsinline: 1}"
    settings="{settings}"
/>

Common responsive arguments 

File helper ViewHelpers 

<mediaUtils:file.getProperty file="{file}" property="mime_type" />

<f:for each="{mediaUtils:file.getReference(table: 'pages', field: 'media', uid: pageUid)}"
       as="file">
    <f:render partial="Utils/Media" arguments="{file: file, settings: settings}" />
</f:for>

<mediaUtils:file.cropVariantClass file="{file}" />

<mediaUtils:file.cropVariantClass file="{file}" bootstrap="true" />

Unit tests 

Run all unit tests:

ddev exec vendor/bin/phpunit -c vendor/madj2k/t3-media-utils/phpunit.xml

Run a single unit test file:

ddev exec vendor/bin/phpunit -c vendor/madj2k/t3-media-utils/phpunit.xml \
    vendor/madj2k/t3-media-utils/Tests/Unit/Whatever/Whatever.php

Run a single unit test method:

ddev exec vendor/bin/phpunit -c vendor/madj2k/t3-media-utils/phpunit.xml \
    vendor/madj2k/t3-media-utils/Tests/Unit/Whatever/Whatever.php \
    --filter MethodName

Functional tests 

Run all functional tests:

ddev exec vendor/bin/phpunit -c vendor/madj2k/t3-media-utils/phpunit.functional.xml

Run a single functional test file:

ddev exec vendor/bin/phpunit -c vendor/madj2k/t3-media-utils/phpunit.functional.xml \
    vendor/madj2k/t3-media-utils/Tests/Functional/Whatever/Whatever.php

Run a single functional test method:

ddev exec vendor/bin/phpunit -c vendor/madj2k/t3-media-utils/phpunit.functional.xml \
    vendor/madj2k/t3-media-utils/Tests/Functional/Whatever/Whatever.php \
    --filter MethodName