Study guide · Fluid ViewHelpers

ViewHelpers at work: text, images, links and head data

As of November 15, 2026 · TYPO3 14.3 LTS · about 27 min read

With Fluid alone, data sits in the template in its raw form. ViewHelpers turn it into a readable date, a properly scaled photo, a link or a meta tag. On this page you help Mara extend the website of a music school. Along the way you get to know the most important ViewHelpers for text, dates, images, crops, links, head data and assets. Afterwards you know which ViewHelper is meant for what, and where its traps are.

The example: Lindenau Music School

Mara is an integrator. She builds the website of Lindenau Music School. Everything lives in her site package lindenau_site, the Composer package lindenau/site, in a Composer project with TYPO3 14.3. The website has course pages for instruments, a page with the teachers and a concert calendar. The teachers' photos should look sharp and load fast. Every course page and every concert should have its own meta tags.

A ViewHelper is a Fluid tag with logic behind it. The namespace f is predefined everywhere, so you do not need to import it. You can call most ViewHelpers in two ways: as a tag, or inline in curly braces. Inline, you can pass a value on to the ViewHelper with an arrow.

<f:format.crop maxCharacters="40">{course.title}</f:format.crop>

{course.title -> f:format.crop(maxCharacters: 40)}
Fluid example. The same thing twice. The course title is cut to 40 characters, once as the tag f:format.crop. The second time it is inline, passing course dot title to f:format.crop with an arrow.

The basics of variables, escaping and conditions are covered in the course “Fluid-Grundlagen”. This page is about the ViewHelpers themselves.

Formatting text

The format group holds many small helpers. For the course descriptions, Mara mainly needs these:

  • The ViewHelper f:format.crop cuts a text to the number of characters in maxCharacters. If it cut something, it appends an ellipsis by default. It does not cut in the middle of a word.
  • The ViewHelper f:format.nl2br turns every line break into an HTML line break. This suits multi-line text fields without an editor.
  • The ViewHelper f:format.currency outputs a number as an amount of money, with a decimal separator and a thousands separator. You set the currency sign with currencySign. That way the course fee appears as 45,00 €.
  • The ViewHelper f:format.number formats numbers without a currency.
  • The ViewHelper f:format.bytes shows file sizes in a readable way, for example for the registration form download.
  • The ViewHelper f:format.trim removes spaces at the edges. The ViewHelper f:format.padding pads a text to a length. The ViewHelper f:format.case changes upper and lower case.

Rich text: You output text from the rich text editor with the ViewHelper f:format.html. It sends the text through a parseFunc, by default through lib.parseFunc_RTE. This turns internal TYPO3 links that start with t3 into real URLs and cleans up the HTML.

Be careful with two ViewHelpers: Fluid normally escapes variables. The ViewHelper f:format.raw switches this escaping off. The ViewHelper f:format.htmlentitiesDecode turns escaped characters back into real HTML. Both can lead to cross-site scripting if visitor input passes through them. The ViewHelpers f:format.htmlspecialchars and f:format.stripTags, on the other hand, make the output safer. The first escapes, the second removes tags.

Date and time

Mara outputs the concert dates with the ViewHelper f:format.date. It accepts an object with DateTimeInterface or a text that PHP understands as a date. That can be a timestamp or a relative value such as “plus one week”.

Two ways to set the format:

  • The argument format takes the PHP date characters. The letter d stands for the day, m for the month and capital Y for the four-digit year. With dots in between, that gives 31.12.2026.
  • The argument pattern takes the ICU notation, such as two small d, a dot, four capital M, a space and four small y. Together with the argument locale, for example de-DE, you get translated month names such as “31. Dezember 2026”.
<f:format.date format="d.m.Y">{concert.date}</f:format.date>
<f:format.date pattern="dd. MMMM yyyy" locale="de-DE">{concert.date}</f:format.date>
<f:format.date pattern="FULLDATE" locale="de-DE">{concert.date}</f:format.date>
<f:format.date format="d.m.Y" base="{concert.date}">+1 week</f:format.date>
<f:format.date format="H:i" timezone="Europe/Berlin">{concert.date}</f:format.date>
Fluid examples. The first line outputs the concert date with the format d dot m dot Y. The second uses the pattern dd dot MMMM yyyy with the locale de-DE. The third uses the preset FULLDATE with the locale de-DE. The fourth outputs the date one week after the concert, with the relative value plus one week and the concert date as base. The last converts the time to Europe Berlin.
Which format does f:format.date use? pattern set? yes ICU pattern + locale 31 December 2026 wins even against format no format set? yes PHP characters, no locale d.m.Y → 31.12.2026 no SYS ddmmyy (default) Y-m-d → 2026-12-31 timezone converts, base is the anchor for +1 week. FULL · LONG · MEDIUM · SHORT · FULLDATE
Which format f:format.date uses.

The key rules:

  • If format and pattern are both set, pattern takes precedence. The description of the argument says so.
  • If neither is set, the ViewHelper takes the setting ddmmyy under SYS in the global TYPO3 configuration. The default is Y-m-d, for example 2026-12-31.
  • The argument locale only works together with pattern. With format you get the PHP characters without translation.
  • For a fully localized date without your own pattern, pattern knows the presets FULL, LONG, MEDIUM and SHORT. There are also variants such as FULLDATE for the date only and FULLTIME for the time only. FULLDATE with de-DE gives, for example, “Donnerstag, 31. Dezember 2026”.
  • The argument timezone converts the date into a time zone before output. A concert stored in UTC appears in Berlin time with Europe Berlin.
  • The argument base is the reference point for relative values such as plus one week or minus one year. Without base, the current time applies.

Text fields with f:render.text

Since TYPO3 14.2 there is the ViewHelper f:render.text for text fields of records. It reads the TCA configuration of the field and picks the right output by itself. That way it replaces three earlier approaches:

  • For a simple input field it replaces outputting the variable directly. The text is escaped.
  • For a multi-line text field it replaces the ViewHelper f:format.nl2br. Line breaks become HTML line breaks.
  • For a rich text field it replaces the ViewHelper f:format.html.

Translations from XLIFF files and images are not text fields. They keep their own ViewHelpers.

The argument field is required. It names the database field. You pass the record with the argument record or as the content of the ViewHelper.

{record -> f:render.text(field: 'header')}
<f:render.text record="{record}" field="bodytext" />
<f:render.text record="{teacher}" field="sub_title" optional="true" />
Fluid examples. First, record is passed inline to f:render.text with the field header. Second, f:render.text outputs the field bodytext of the record. Third, an Extbase model teacher gets the field sub_title with an underscore, which is the name from the database, and optional set to true.

Requirement in the content element: For the variable record in the template to be a record object with TCA information, the content element needs the data processor record-transformation. Without it there is only raw data, and the ViewHelper cannot classify the field.

The ViewHelper can also handle Extbase models. But it expects the field name from the database, not the property name. If the teacher model has the property subTitle from the field sub_title, you write sub_title. If the field is missing, you get an error. With optional set to true, you get null instead. This also applies to record objects. The model must also map every field you output, and the type field too if the TCA has one.

Images with f:image

The ViewHelper f:image resizes, crops or converts an image if needed. In the end it outputs a finished img tag. If you only need the URL of the processed image, you use the ViewHelper f:uri.image.

There are two ways to pass the image:

  • The argument image expects an object from the file abstraction layer FAL, that is a File or a FileReference. This is how the teachers' photos get into the template.
  • The argument src takes a path with EXT:, a combined FAL identifier or a UID. This is how Mara includes the logo from the site package.

The ViewHelper does not process external URLs. An image from another address is neither downloaded nor scaled.

<f:image image="{teacher.photo}" width="800c" cropVariant="default" loading="lazy" alt="{teacher.name}" />
<f:image src="EXT:lindenau_site/Resources/Public/Images/logo.png" width="200" fileExtension="webp" />
<f:image src="EXT:lindenau_site/Resources/Public/Images/logo.png" width="200" base64="true" />
Fluid example. f:image gets the teacher's photo, the width 800c, the crop variant default and the attribute loading lazy. A second f:image outputs the logo from the site package as WebP. A third embeds the logo for an email with base64 set to true.

The important arguments:

  • For width and height you give pixels. The suffix c crops. A width of 800c gives an image cropped to exactly 800 pixels wide. With the suffix m, the value is an upper limit. The image is scaled proportionally and gets no larger than that.
  • With cropVariant you choose a stored crop, for example mobile. The default is default.
  • Setting crop to false removes the stored crop. Then the whole image is used.
  • fileExtension sets the target format, for example webp. The image is converted if needed. This works no matter whether you use image or src.
  • Setting base64 to true writes the image data as a data URI directly into the src attribute. This is meant for HTML emails, for example in FluidEmail templates.
  • The tag-based ViewHelper simply copies other attributes, such as loading with the value lazy, or alt, into the img tag.

Default target formats: The setting imageFileConversionFormats under GFX in the global TYPO3 configuration controls which format is produced on conversion. Web formats such as jpg, png, gif, svg and webp are kept by default. Everything else becomes png. If the setting consists only of the key default with the value webp, TYPO3 converts everything to WebP. If the entries for jpg and png stay in place, those formats are still passed through.

Responsive images with f:image.srcset

The teachers' photos should be small on a phone and sharp on a large screen. For that, the img or source tag needs a srcset attribute with several image sizes. In the past you wrote many calls of f:uri.image by hand. Since TYPO3 14.2 there is the ViewHelper f:image.srcset.

From a single setting it creates all image variants and returns the finished list of URLs and descriptors. There are two kinds of descriptors:

  • Widths such as 400w and 800w refer to the width of the image file.
  • Pixel densities such as 1x and 2x refer to the pixel density of the screen.

You must not mix the two kinds. TYPO3 stops with an error if you do. For pixel densities, TYPO3 needs a base width for 1x, from which it calculates 2x and 3x. You set it with referenceWidth. For width descriptors, referenceWidth has no meaning.

You still steer which image the browser finally picks with the HTML attributes sizes and media. The ViewHelper does not make them unnecessary.

Picture with crops: On the desktop the photo should be wide, on a phone square. For that, each source element in the picture element gets its screen range through media and its own crop through cropVariant. The img inside is the fallback for old browsers.

<picture>
  <source media="(min-width: 1000px)" sizes="100vw"
    srcset="{f:image.srcset(image: teacher.photo, srcset: '1000w, 1400w', cropVariant: 'desktop')}" />
  <source
    srcset="{f:image.srcset(image: teacher.photo, srcset: '1x, 2x', referenceWidth: 400, cropVariant: 'mobile')}" />
  <f:image image="{teacher.photo}" width="400" cropVariant="mobile" alt="{teacher.name}" />
</picture>
Fluid example. A picture element with two source elements. The first applies from a screen width of 1000 pixels, uses the crop variant desktop and the widths 1000w and 1400w. The second uses the variant mobile with the pixel densities 1x and 2x and the base width 400. Finally comes f:image as the fallback.
One photo, two crops picture source · from 1000 px cropVariant desktop 1000w, 1400w 16:9 source · mobile cropVariant mobile 1x, 2x (referenceWidth 400) 1:1 img · fallback f:image Never mix w and x in the same list. sizes and media still steer the choice.
Each source has its own crop variant.

Crops with crop variants

Crop variants are several stored crops of the same image, each with its own aspect ratio. The music school's editors crop a photo in the backend once wide for desktop and once square for mobile. In the template you choose the variant with cropVariant.

Where are they defined? The variants live in the TCA of the field crop in the table sys_file_reference. The field has the type imageManipulation. Alternatively you set them with TCEFORM in page TSconfig. For each variant you define a title, the allowed aspect ratios with allowedAspectRatios, and three areas:

  • The cropArea is the initial crop.
  • The focusArea marks the important part of the image, for example the face. It helps with responsive crops.
  • The coverAreas show areas that will be covered later, for example by text on top of the image.

You give all areas in relative values between 0 and 1.

$GLOBALS['TCA']['tt_content']['types']['textpic']['columnsOverrides']['image']['config']['overrideChildTca']['columns']['crop']['config']['cropVariants'] = [
    'mobile' => [
        'title' => 'Mobil',
        'allowedAspectRatios' => ['1:1' => ['title' => '1:1', 'value' => 1.0]],
    ],
    'default' => ['disabled' => true],
];
PHP example from the TCA. In the type textpic of tt_content, the field image gets two variants for the field crop through columnsOverrides and overrideChildTca. The variant mobile has the title Mobil and only allows the aspect ratio 1 to 1. The variant default is switched off with disabled set to true.

Only for one content type: With overrideChildTca on the field image of tt_content, a change applies to all content types. If only the type textpic should get an extra variant, you put overrideChildTca into the columnsOverrides of that type.

Switching variants off: overrideChildTca is merged with the TCA of sys_file_reference. So simply leaving out a key does not remove a variant. That is what the keyword disabled is for. If you set it to true for the variant default, it disappears for that field.

Cropping all at once: Since TYPO3 14.2 the image editor shows a checkbox that lets editors crop all variants at the same time. It only appears if the variants are configured identically apart from the title, that is with the same aspect ratios. You exclude a different variant, for example one for a list view, with excludeFromSync.

Links and URLs

There are two families for links. The ViewHelpers in the link group create the whole a tag. The ViewHelpers in the uri group only return the address, for example for an attribute. So the ViewHelper f:uri.page only outputs the URL, while the ViewHelper f:link.page outputs a finished link.

  • The ViewHelper f:link.page links to a page in the page tree through pageUid. With additionalParams you add parameters. With language you link to another language. Setting absolute to true creates a full URL with the domain.
  • The ViewHelper f:link.typolink passes the argument parameter to typolink. That way it understands the values from link fields: internal links starting with t3, and short forms such as “12 _blank” with target, class and title. The ViewHelper f:uri.typolink returns only the URL for it.
  • The ViewHelper f:link.email creates a mailto link. It knows the arguments email, cc, bcc, subject for the subject line and body. The argument title only sets the title attribute of the link.
  • The ViewHelper f:link.external is for other websites, the ViewHelper f:link.file for files, and the ViewHelper f:link.action for Extbase actions.
<f:link.page pageUid="12" language="1" absolute="true">Piano course</f:link.page>
<f:link.typolink parameter="{record.link}">Learn more</f:link.typolink>
<f:link.email email="office@example.org" subject="Anmeldung">Write to us</f:link.email>
<f:link.page pageUid="12" addQueryString="untrusted">Keep filters</f:link.page>
Fluid examples. A link to page 12 in language 1 as an absolute URL. A typolink with the value from a link field. An email link to the office with the subject Anmeldung, which means registration. A link to page 12 that keeps all current query parameters, with addQueryString set to untrusted.

Spam protection: The ViewHelper f:link.email does not protect addresses on its own. It follows the TypoScript setting spamProtectEmailAddresses.

Keeping current parameters: If addQueryString is set, the current query parameters stay in the link. With the value untrusted, all parameters are added explicitly, including untrusted ones. According to the description, this can cause problems with cached links.

Head area and meta tags

Since TYPO3 14.0 there are two ViewHelpers that write any markup into the page. Both use the PageRenderer API internally.

  • The ViewHelper f:page.headerData adds its content to the head of the page, for example preload, preconnect or dns-prefetch links.
  • The ViewHelper f:page.footerData writes its content right before the closing body tag, for example a tracking script.

For stylesheets and scripts you are better off with the asset ViewHelpers from the next section. They use an identifier and prevent duplicates. The head data ViewHelpers are meant for other markup and have no identifier.

Meta tags from Fluid: Also since TYPO3 14.0, the ViewHelper f:page.meta sets meta tags right in the template. It uses the MetaTagManager, just like TypoScript and PHP. So the same rules and priorities apply. It works in every Fluid context: in Extbase templates, in Fluid-based content elements, in components and in the page template of the site package.

  • The argument property is the only required argument, for example description, og:title or og:type.
  • With type you force name, property or http-equiv. Without type, the responsible manager decides, for example property for og tags.
  • With subProperties you add extra details such as width, height or alt. For og:image, the manager turns them into og:image:width and og:image:height.
  • Setting replace to true overwrites a meta tag that is already set. Without replace, the existing tag with the same property stays.
<f:page.meta property="description" replace="true">{concert.teaser}</f:page.meta>
<f:page.meta property="og:title">{concert.title}</f:page.meta>
<f:page.meta property="og:image" subProperties="{width: 1200, height: 630}">{imageUrl}</f:page.meta>
Fluid example from the detail page of a concert. f:page.meta sets the description with replace set to true, because TypoScript has already set one. Then follow og:title and an og:image with subProperties for a width of 1200 and a height of 630.

Including CSS and JavaScript

The ViewHelpers f:asset.css and f:asset.script register CSS and JavaScript from Fluid with the AssetCollector. TYPO3 outputs everything collected in the right place of the page. You can give a file, with href for CSS and with src for JavaScript, or inline code as the content.

The identifier: The argument identifier is always required. If an asset with the same identifier is registered several times, for example because the slider sits in three content elements, TYPO3 outputs it only once. The same identifier means the same asset. So if two content elements register two different files under the identifier slider, only one of them appears, namely the one registered last. That is why each independent file needs a unique identifier.

<f:asset.css identifier="lindenau-main" href="EXT:lindenau_site/Resources/Public/Css/main.css" media="screen" />
<f:asset.script identifier="lindenau-slider" src="EXT:lindenau_site/Resources/Public/JavaScript/slider.js" defer="true" />
<div style="{f:asset.styleAttr(value: 'background-color: {instrument.color}')}">…</div>
Fluid examples. f:asset.css registers the site package stylesheet with the identifier lindenau-main and the attribute media screen. f:asset.script registers the slider script with the identifier lindenau-slider and defer. Finally a div gets a style attribute from f:asset.styleAttr with the background color of the instrument.

More arguments:

  • Setting priority to true puts a stylesheet before the other CSS files. Included CSS files always go into the head. For a script, priority decides whether it goes into the head. Without priority, scripts end up at the end of the body. Watch out: TYPO3 also puts inline CSS without priority at the end of the body, although the argument description says CSS always goes into the head. This applies to code given as content and to files with inline set to true.
  • Setting inline to true embeds the content of a file given with href or src directly into the page.
  • The ViewHelper f:asset.css knows HTML attributes such as media, integrity and crossorigin.
  • The ViewHelper f:asset.script knows async, defer, nomodule and type. With defer, the script only runs after the document has been parsed. With async, it is loaded in parallel and runs as soon as it arrives. With nomodule, it only runs in browsers without ES modules.
  • Since TYPO3 14.2, the former argument useNonce is called csp. It controls whether a hash or a nonce for the Content Security Policy is collected for the asset.
Where does the output go? head f:asset.css, file or priority f:asset.script with priority f:page.headerData f:page.meta body page content right before the closing body tag f:asset.script without priority f:asset.css inline, no priority f:page.footerData Only f:asset.* prevents duplicates via identifier. headerData and footerData: no escaping.
Where the ViewHelpers put their output.

Values in style attributes: The ViewHelper f:asset.styleAttr exists since TYPO3 14.2. It returns the value for the style attribute of an HTML tag and collects a hash for the CSP directive style-src-attr. That way a single inline style stays allowed under a strict Content Security Policy. You still include external stylesheets with the ViewHelper f:asset.css.

Key points

  • The ViewHelpers in the link group create an a tag, those in the uri group only the URL.
  • The ViewHelpers f:format.raw and f:format.htmlentitiesDecode can lead to cross-site scripting. The ViewHelper f:format.html uses lib.parseFunc_RTE.
  • For dates, pattern wins over format. Without either, SYS ddmmyy applies, by default Y-m-d. The locale only works with pattern.
  • The ViewHelper f:render.text needs field with the database field name, and the content element needs record-transformation.
  • The ViewHelper f:image takes image for FAL objects and src for paths, and it does not process external URLs.
  • The ViewHelper f:image.srcset exists since TYPO3 14.2. It knows w or x, and for x it needs referenceWidth.
  • Crop variants live in the TCA of the field crop. For a single content type you use columnsOverrides, to switch one off you use disabled.
  • The ViewHelpers f:page.headerData and f:page.footerData are new in TYPO3 14 and output unfiltered content.
  • The ViewHelper f:page.meta uses the MetaTagManager. It only overwrites tags that are already set when you use replace.
  • Asset ViewHelpers always need an identifier. The same identifier means only one asset.

Terms

AssetCollector
Collects CSS and JavaScript and outputs each asset only once per identifier.
Crop variant
A stored crop of an image with its own aspect ratio.
Descriptor
The value after each image URL in a srcset, either a width with w or a pixel density with x.
FAL
File Abstraction Layer, the file management of TYPO3 with File and FileReference objects.
ICU
A library for localized formats whose patterns the argument pattern uses.
MetaTagManager
The TYPO3 API that manages meta tags from TypoScript, PHP and Fluid.
PageRenderer
Builds the frame of the HTML page and takes in head and footer data.
record-transformation
A data processor that turns raw data into a record object that knows the TCA.

As of: November 15, 2026 (TYPO3 14.3 LTS)

Sources:

  • ViewHelper Reference TYPO3 14.3 (format, render.text, image, image.srcset, link, uri, page, asset)
  • TYPO3 Explained 14.3, chapter Crop variants, and imageManipulation in the TCA Reference
  • Changelog TYPO3 14.0 to 14.3 (f:page.headerData, f:page.footerData, f:page.meta, f:image.srcset, f:render.text, synchronized cropping, argument csp, f:asset.styleAttr)
  • Source code TYPO3 14.3 (typo3/cms-fluid, typo3/cms-core, typo3/cms-backend) and Fluid 5, checked for dates, render.text, images, crops, links, meta tags and the AssetCollector
  • Learning objectives TYPO3 CMS Certified Integrator 14 LTS, course Fluid ViewHelpers

This study guide was written with AI and checked against the sources.

Certifications & exams

Which exam comes next?

You can already practise for 51 exams, and 16 are up for a vote. See all certifications with their official information, cast your vote or suggest your exam.

See all certifications