--- title: "ViewHelpers" version: "2.0" source: "ViewHelpers/Index.rst" rendered: "2026-09-27T13:10:28+00:00" --- # ViewHelpers {#viewhelpers} **:local:** - [General](#general) - [ai:image](#ai-image) - [ai:picture](#ai-picture) - [ai:getCropVariants](#ai-getcropvariants) - [ai:getSrcSet](#ai-getsrcset) - [ai:ratioBox](#ai-ratiobox) - [ai:placeholder.image](#ai-placeholder-image) - [ai:placeholder.svg](#ai-placeholder-svg) ## General {#general} ### Add the fluid namespace declaration to fluid templates {#add-the-fluid-namespace-declaration-to-fluid-templates} Before version 0.1.5 registering of the global viewhelper namespace *ai* was not working. Even if you use a version >= 0.1.5 you might still want to add this namespace declaration to your templates and partials: ```html ... ``` ## ai:image {#ai-image-viewhelper} This viewHelper outputs a complete adaptive image *img* tag, optionally with ratio box and a placeholder image. Use this when you don't need art direction/different cropVariants. If you need art direction see [ai:picture](#ai-picture-viewhelper). ### Arguments {#arguments} This viewHelper has all arguments which are available to the [f:image viewHelper](https://docs.typo3.org/typo3cms/ExtbaseGuide/Fluid/ViewHelper/Image.html) including [fluids universal tag attributes](https://docs.typo3.org/typo3cms/ExtbaseGuide/Fluid/UniversalTagAttributes.html#universaltagattributes) plus the following: | argument | required | Default | Description | | --- | --- | --- | --- | | lazy | no | false | lazy load images and auto-sizes with lazysizes.js | | debug | no | false | Add debug output (width, height, ratio) to the generated images using IM/GM | | jsdebug | no | false | Add debug output (width, height, ratio) near the image using javascript | | srcsetWidths | no | \[320,640,1024,1440,1920\] | create srcset candidates with these widths | | cropVariant | no | default | select a cropping variant, in case multiple croppings have been specified or stored in FileReference | | sizes | no | 100vw | sizes attribute for the img tag. Takes precedence over additionalAttributes\["sizes"\] if both are given. | | placeholderInline | no | true | Include placeholder inline in HTML (base64 encoded) | | ratiobox | no | false | The image is wrapped in a ratio box if true. Nowadays browsers calculate the aspect ratio of the image and avoid page reflows, so you most likely don't need this option anymore for \ tags. | ### Examples {#examples} ```html ``` returns a complete image tag with lazysizes loading and a placeholder image. **Important** For lazysizes to work you have to add the class *lazyload* here. ## ai:picture {#ai-picture-viewhelper} This viewHelper outputs a complete adaptive image *picture* tag, optionally with ratio box and a placeholder image. If you need to show different cropVariants for different device widths you need to use this viewHelper. ### Arguments {#arguments-1} This viewHelper has all arguments which are available to the [f:image viewHelper](https://docs.typo3.org/typo3cms/ExtbaseGuide/Fluid/ViewHelper/Image.html) including [fluids universal tag attributes](https://docs.typo3.org/typo3cms/ExtbaseGuide/Fluid/UniversalTagAttributes.html#universaltagattributes) plus the following: | argument | required | Default | Description | | --- | --- | --- | --- | | lazy | no | false | lazy load images and auto-sizes with lazysizes.js | | debug | no | false | Add debug output (width, height, ratio) to the generated images using IM/GM | | jsdebug | no | false | Add debug output (width, height, ratio) near the image using javascript | | srcsetWidths | no | \[320,640,1024,1440,1920\] | create srcset candidates with these widths | | cropVariant | no | default | select a cropping variant, in case multiple croppings have been specified or stored in FileReference | | sizes | no | 100vw | sizes attribute for the img tag. Takes precedence over additionalAttributes\["sizes"\] if both are given. | | placeholderInline | no | true | Include placeholder inline in HTML (base64 encoded) | | ratiobox | no | false | The image is wrapped in a ratio box if true. | | sources | no | \[\['default' => ''\]\] | Array of arrays containing candidates for source tags | ### Examples {#examples-1} ```html ``` returns a complete picture tag with one source for the cropVariant mobile. With lazysizes loading and a placeholder image. **Important** For lazysizes to work you have to add the class *lazyload* here. ## ai:getCropVariants {#ai-get-crop-variants-viewhelper} Returns a CropVariantCollection as array for a FileReference. ### Arguments {#arguments-2} | argument | required | default | Description | | --- | --- | --- | --- | | file | yes | | FileReference to get the cropVariants from. | | asString | no | false | Return the result as string (instaed array) | ### Examples {#examples-2} ```html ``` will return (if the FileReference has two cropVariants): ```none array(2 items) default => array(7 items) id => 'default' (7 chars) title => '' (0 chars) cropArea => array(4 items) x => 0 (double) y => 0.09925 (double) width => 0.999 (double) height => 0.8991 (double) allowedAspectRatios => array(empty) selectedRatio => NULL focusArea => array(4 items) x => 0.33333333333333 (double) y => 0.33333333333333 (double) width => 0.33333333333333 (double) height => 0.33333333333333 (double) coverAreas => NULL mobile => array(7 items) ``` ## ai:getSrcSet {#ai-get-srcset-viewhelper} Get a srcset string for a given cropVariant and widths and generate images for srcset candidates ### Arguments {#arguments-3} | argument | required | Default | Description | | --- | --- | --- | --- | | file | yes | | FileReference to use | | cropVariant | no | default | select a cropping variant, in case multiple croppings have been specified or stored in FileReference | | widths | no | \[320,640,1024,1440,1920\] | create srcset candidates with these widths | | debug | no | 0 | Add debug output (width, height, ratio) to the generated images | ### Examples {#examples-3} ```html ``` returns ```none /fileadmin/_processed_/7/9/image_2269306f6a.jpg 360w,/fileadmin/_processed_/7/9/image_5f0de63291.jpg 720w ``` or for cropVariant mobile and widths as array ```html ``` returns ```none /fileadmin/_processed_/7/9/image_cbb4289869.jpg 0w,/fileadmin/_processed_/7/9/image_3e7a2d9258.jpg 720w ``` ## ai:ratioBox {#ai-ratiobox-viewhelper} Wraps an image or picture tag in a ratio box. This also adds generated css style to the header of the page to set the correct padding-bottom to always maintain the ratio and thus prevent page reflows. ### Arguments {#arguments-4} | argument | required | Default | Description | | --- | --- | --- | --- | | file | yes | | FileReference to use | | mediaQueries | no | \[\['default' => ''\]\] | Array of arrays containing ratio and media for cropVariants | ### Examples {#examples-4} ```html Your picture/image tag (f:image, ai:image etc.) ``` Assuming that the image has cropVariants default (16:9) and mobile (4:3) this will add css style to the head of the website and return: ```html

Your picture/image tag (f:image, ai:image etc.)

``` ## ai:placeholder.image {#ai-placeholder-image-viewhelper} Returns a placeholder image (base64 encoded data OR uri) width reduced quality and size, but original aspect ratio. ### Arguments {#arguments-5} | argument | required | Default | Description | | --- | --- | --- | --- | | file | yes | | FileReference to use | | cropVariant | no | default | select a cropping variant, in case multiple croppings have been specified or stored in FileReference | | width | no | 128 | create placeholder image with this width | | height | no | | create placeholder image with this height | | absolute | no | false | Force absolute URL | | dataUri | no | true | Returns the base64 encoded dataUri of the image (for inline usage) | ### Examples {#examples-5} ```html ``` returns the images as base64 encoded data-uri ```none data:image/jpeg;base64,/9j/4AAQSkZJ[...] ``` or return image uri instead: ```html ``` returns ```none /fileadmin/_processed_/7/9/image_702e24791e.jpg ``` ## ai:placeholder.svg {#ai-placeholder-svg-viewhelper} Returns a placeholder SVG image (base64 encoded data uri) keeping original aspect ratio by replacing the SVG's width/and height of that of the generated image. ### Arguments {#arguments-6} | argument | required | Default | Description | | --- | --- | --- | --- | | file | yes | | FileReference to use | | cropVariant | no | default | select a cropping variant, in case multiple croppings have been specified or stored in FileReference | ### Examples {#examples-6} ```html ``` returns the SVG as base64 encoded data-uri ```none data:image/svg+xml;base64,PHN2ZyB4bWxucz0naHR0[...] ```