Image ViewHelper <f:image>

ViewHelper to resize, crop or convert a given image (if required) and render the corresponding HTML <img> tag showing the processed image.

Note that image operations (cropping, scaling, converting) on non-FAL files (i.e. extension resources) may be changed in future TYPO3 versions, since those operations are coupled with FAL metadata. Each non-FAL image operation creates a "fake" FAL record, which may lead to problems.

External URLs are not processed.

Go to the source code of this ViewHelper: ImageViewHelper.php (GitHub).

Table of contents

Argument src - displaying images from extension assets

Images used for design purposes and not content purposes are commonly shipped in an extension. These images cannot be edited by backend users. They can be displayed using the <f:image> ViewHelper using the src argument and EXT: syntax:

<f:image src="EXT:my_site_package/Resources/Public/images/typo3_logo.png" alt="alt text" />
Copied!

In the extension the assets must be stored under Resources/Public/ or a subfolder of this folder.

If you installed the extension via Composer before it had a folder of that exact name, reinstall it so that the symlinks in folder public/_assets are correctly created for you.

Argument image - display images from the folder fileadmin / from FAL

Folders from inside the folder fileadmin are usually accessed using the file abstraction layer (FAL).

For example, if you want to display an image that is attached to a content element, the content element typically stores a reference count of attached images in its media field. Intermediate tables are then used to attach the actual image to the content elements. This allows backend users to move or rename files, without the files connection being lost in the content element.

FLUIDTEMPLATE and data processors and images

In a TypoScript FLUIDTEMPLATE you can use the files data processor to display an image with the <f:image> ViewHelper.

See Example: Render the images stored in field image in the TypoScript reference.

You can then use the image argument to pass the File or FileReference provided by the TypoScript data processor to the ViewHelper.

<f:for each="{images}" as="image">
    <f:image image="{image}" class="something" height="250" alt="Description"/>
</f:for>
Copied!

The FAL will scale the image and convert it to a web format if necessary (for example from a pdf to a png).

The <f:image> ViewHelper generates a HTML <img> tag with the correct paths, etc.

Images from Extbase models in Fluid

In Extbase models you can use fields of type \TYPO3\CMS\Extbase\Persistence\ObjectStorage with the TCA type File.

When you are looping through the object storage, each element will be of type \TYPO3\CMS\Extbase\Domain\Model\FileReference . They can be used with the image argument:

<f:for each="{mymodel.images}" as="image">
    <f:image image="{image}" class="something" height="250"/>
</f:for>
Copied!

If the field should only contain a maximum of one image (maxitems=1), you can display the image simply by selecting the first array element:

<f:if condition="{mymodel.image.0}">
    <f:image image="{mymodel.image.0}" class="something" height="250"/>
</f:if>
Copied!

Using the UID of the database entry directly

If you have the UID of the sys_file_reference table (preferred) you have to set treatIdAsReference to true and pass the UID of the file reference to the src argument.

If only the UID of the sys_file table is available, you can pass this value to the src argument of the ViewHelper and treatIdAsReference can be kept as the default value (false). In this case no data from the file reference, such as default cropping or overrides for alt text and description, will be available.

<f:image src="{reference.uid}" treatIdAsReference="1" height="250"/>
<f:image src="{file.uid}" height="250" alt="My image description"/>

<!-- File with uid 42 -->
<f:image src="42" treatIdAsReference="1" class="something" height="250"/>
Copied!

Embedding SVG files with the base64 attribute

When the base64 argument is set to true, the resulting image tag will contain the source of the image in a base64 encoded form.

<f:image base64="true"
         src="EXT:backend/Resources/Public/Images/typo3_logo_orange.svg"
         class="pr-2"
/>
Copied!

This will result in the HTML tag providing the image encoded in base64.

<img class="pr-2"
     src="data:image/svg+xml;base64,PHN2...cuODQ4LTYuNzU3Ii8+Cjwvc3ZnPgo="
     alt=""
>
Copied!

This can be particularly useful inside FluidEmail or to prevent unnecessary HTTP calls.

Arguments of the <f:image> ViewHelper

absolute

absolute
Type
bool
Default
false
Force absolute URL

additionalAttributes

additionalAttributes
Type
array
Additional tag attributes. They will be added directly to the resulting HTML tag.

aria

aria
Type
array
Additional aria-* attributes. They will each be added with a "aria-" prefix.

base64

base64
Type
bool
Default
false
Adds the image data base64-encoded inline to the image‘s "src" attribute. Useful for FluidEmail templates.

crop

crop
Type
string|bool|array
overrule cropping of image (setting to FALSE disables the cropping set in FileReference)

cropVariant

cropVariant
Type
string
Default
'default'
select a cropping variant, in case multiple croppings have been specified or stored in FileReference

data

data
Type
array
Additional data-* attributes. They will each be added with a "data-" prefix.

fileExtension

fileExtension
Type
string
Custom file extension to use

height

height
Type
string
height of the image. This can be a numeric value representing the fixed height of the image in pixels. But you can also perform simple calculations by adding "m" or "c" to the value. See imgResource.height in the TypoScript Reference https://docs.typo3.org/permalink/t3tsref:confval-imgresource-height for possible options.

image

image
Type
object
a FAL object (\TYPO3\CMS\Core\Resource\File or \TYPO3\CMS\Core\Resource\FileReference)

maxHeight

maxHeight
Type
int
maximum height of the image

maxWidth

maxWidth
Type
int
maximum width of the image

minHeight

minHeight
Type
int
minimum height of the image

minWidth

minWidth
Type
int
minimum width of the image

src

src
Type
string
Default
''
a path to a file, a combined FAL identifier or an uid (int). If $treatIdAsReference is set, the integer is considered the uid of the sys_file_reference record. If you already got a FAL object, consider using the $image parameter instead

treatIdAsReference

treatIdAsReference
Type
bool
Default
false
given src argument is a sys_file_reference record

width

width
Type
string
width of the image. This can be a numeric value representing the fixed width of the image in pixels. But you can also perform simple calculations by adding "m" or "c" to the value. See imgResource.width in the TypoScript Reference on https://docs.typo3.org/permalink/t3tsref:confval-imgresource-width for possible options.