TYPO3 Fluid Tutorial: How to Use Fluid (Beginner to Advanced Guide)

TYPO3 Fluid is a secure and flexible template engine used in TYPO3 to build frontend templates without heavy PHP. It helps developers and integrators create structured, maintainable UI components for TYPO3 projects.

If you work with TYPO3 as a developer or integrator, understanding Fluid is essential. It is used across TYPO3 projects for template rendering and extension development.

In this guide, you’ll learn what TYPO3 Fluid is, how it works, and how to use it effectively. We cover architecture, syntax, ViewHelpers, custom ViewHelpers, and practical best practices.

What's TYPO3 Fluid?

TYPO3 Fluid is a templating engine in TYPO3 used to build dynamic frontend output. It separates presentation from logic, allowing developers to create clean and maintainable templates without writing complex PHP.

“TYPO3 Fluid - A fast, secure and extendible template engine for PHP.”
 – typo3.org

TYPO3 Fluid is mainly used by frontend developers and integrators to combine HTML, CSS, and JavaScript into TYPO3 templates. It allows you to control how content is rendered without relying on heavy backend logic.

Real-world example:

When building a TYPO3 website, you can use Fluid to display dynamic content like blog posts, product listings, or multilingual content using simple template logic instead of writing PHP.

Why Use TYPO3 Fluid in TYPO3 Projects?

TYPO3 Fluid was created to provide a structured and secure way to handle frontend rendering in TYPO3 projects.

• Security: Built with TYPO3’s security standards, protecting against common issues like XSS
• Separation of logic & presentation: Keeps backend logic out of templates, making code cleaner and easier to maintain
• TYPO3-native advantage: Fully integrated into TYPO3, unlike external engines like Twig or Blade
• Extendibility: Highly flexible and can be extended with custom ViewHelpers
• Ease of use: Uses simple, XML-based syntax that works well within HTML templates
• Enterprise reliability: Stable and scalable for large TYPO3 projects, which is critical for enterprise and German-market use cases

History of TYPO3 Fluid (Quick Overview)

TYPO3 Fluid was introduced in 2008 as part of Extbase and TYPO3 Phoenix (now Neos CMS). It was later adopted into the core of TYPO3 as its default templating engine.

The codebase was refactored into a standalone package by Claus Due, making Fluid reusable as a library from TYPO3 v8 onwards and across frameworks like Neos/Flow.

TYPO3 Fluid Tutorial: Your First Template (Quick Start)

Let’s create a simple TYPO3 Fluid example to understand how rendering works.

TYPO3 Fluid Example: Basic Conditional Rendering

Fluid Template (Input)

<h2>Welcome Message</h2>

<f:if condition="{isLoggedIn}">
  <f:then>
      <p>Welcome back, user!</p>
  </f:then>
  <f:else>
      <p>Please log in to continue.</p>
  </f:else>
</f:if>

Output (Frontend)

If isLoggedIn = true:

<h2>Welcome Message</h2>
<p>Welcome back, user!</p>

If isLoggedIn = false:

<h2>Welcome Message</h2>
<p>Please log in to continue.</p>

Another Quick Example

Fluid Template

<h4>How easy to learn TYPO3 Fluid Template?</h4>
<p>
  <f:if condition="{myExpression}">
      <f:then>Indeed, it’s very easy!</f:then>
      <f:else>Hmm, seems a bit difficult</f:else>
  </f:if>
</p>

Output (if myExpression = true)

<h4>How easy to learn TYPO3 Fluid Template?</h4>
<p>Indeed, it’s very easy!</p>

How It Works

• <f:if> checks a condition (isLoggedIn, myExpression)
• <f:then> renders content when the condition is true
• <f:else> renders fallback content when false
• TYPO3 Fluid evaluates the condition, renders the appropriate block, and outputs final HTML to the frontend.

Key Takeaway

With TYPO3 Fluid, you control frontend output using simple template logic, without writing complex PHP.

How to Install TYPO3 Fluid

TYPO3 Fluid is included by default in TYPO3 as part of the core system extension (EXT:fluid). No separate installation is required in standard setups.

TYPO3 Fluid Installation with Composer (Important)

In Composer-based TYPO3 projects, a common issue is missing the required content rendering extension.

Make sure fluid_styled_content is installed:

composer require typo3/cms-fluid-styled-content

Common TYPO3 Fluid Installation Mistakes

• TYPO3 Fluid is available, but frontend rendering does not work as expected
• Cause: EXT:fluid_styled_content is not installed or activated

Ensure this extension is properly included to enable default content rendering in TYPO3.

TYPO3 Fluid Support & Resources

You can explore TYPO3 Fluid on GitHub for updates, issues, and contributions. For official documentation and best practices, refer to TYPO3 resources and community forums.

Who Should Learn TYPO3 Fluid?

TYPO3 relies on Fluid as its core templating engine, including backend rendering. TYPO3 extends Fluid through system extensions like ext:fluid to integrate it fully into the CMS.

TYPO3 Fluid is essential for:

• Frontend developers working with HTML, CSS, and JavaScript to build TYPO3 templates
• TYPO3 integrators responsible for implementing designs into TYPO3 projects
• TYPO3 agencies building scalable and reusable website solutions for clients
• Enterprise teams managing large, complex TYPO3 installations
• Freelance TYPO3 developers/integrators delivering custom TYPO3 projects

With Fluid, you can efficiently integrate and control frontend output in TYPO3 without relying heavily on PHP.

TYPO3 Fluid Basics (File Structure, Syntax & Expressions)

Let’s start with the core fundamentals of TYPO3 Fluid, file structure, syntax, and expressions.

TYPO3 Fluid File Structure Explained

TYPO3 Fluid follows a structured approach using Templates, Layouts, and Partials.

typo3conf/ext/extension_key

How this works in a real project:

• Templates → Define page-level structure (e.g., homepage, blog page)
• Layouts → Provide a common wrapper (header, footer, base structure)
• Partials → Reusable components (e.g., cards, buttons, navigation)

In a typical TYPO3 project, you’ll use:

• Templates for full page rendering
• Layouts for consistent design across pages
• Partials to avoid repeating UI code

TYPO3 Fluid Syntax (Tag vs Inline Notation)

TYPO3 Fluid supports two syntax formats:

1. Tag-based syntax (most commonly used)

<f:count>{arrVariable}</f:count>

2. Inline notation (used inside attributes or compact logic)

{arrVariable -> f:count()}

Tag vs Inline Mode (When to Use)

• Use Tag syntax
  • For clear structure and readability
  • When working with blocks (conditions, loops, formatting)
• Use Inline notation
  • Inside HTML attributes
  • For short expressions

Example

Bad usage (Tag inside attribute):

<ol class="item-count-<f:count>{arrVariable}</f:count>">
My List
</ol>

Correct usage (Inline notation):

<ol class="item-count-{arrVariable -> f:count()}">

 My List

</ol>

TYPO3 Fluid Expressions (Examples & Usage)

Expressions {} are the core of Fluid’s inline logic. They allow you to output values, perform operations, and apply conditions.

Examples:

{variable}
{myArray -> f:count()}
{myPossiblyArray as array}
{checkVariable ? thenVariable : elseVariable}
{myNumber + 3}

These expressions make it possible to handle dynamic data directly in templates without writing complex PHP.

This foundation is critical before moving into ViewHelpers and advanced Fluid concepts.

TYPO3 Fluid Architecture (Templates, Layouts, Partials)

TYPO3 Fluid is built on three core components: Templates, Layouts, and Partials. Together, they define how content is structured and rendered in TYPO3.

Core Components of TYPO3 Fluid

• Templates
  Main files that control page-level output. They are usually mapped to controllers and actions.
• Layouts
  Shared wrappers (e.g., header, footer, structure) used by multiple templates.
• Partials
  Reusable UI components (e.g., cards, buttons, sections) that can be used anywhere.

How TYPO3 Fluid Rendering Works (Step-by-Step Flow)

1. A controller selects a Template
2. The Template uses a Layout for overall structure
3. Inside the Template, Partials are rendered for reusable sections
4. Fluid processes everything and outputs final HTML

This separation keeps code clean and reusable across large projects.

1. Templates in TYPO3 Fluid

<!-- File: /typo3conf/ext/extension_key/Resources/Private/Templates/MyTemplate.html -→

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

<f:section name="MyTemplate">
  The main template’s section will render.
</f:section>

<f:render section="MyTemplate" />
</html>

When to use:

• Page-level structure
• Controller-based rendering
• Dynamic content output

3. Partials in TYPO3 Fluid

<!-- File: /typo3conf/ext/extension_key/Resources/Private/Partials/MyPartial.html -→

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

<p>My First Partial: {variable}</p>
</html>

Calling a Partial in Template

<f:section name="MyTemplate">

<f:render partial="MyPartial" arguments="{variable: 'my-value'}" />

</f:section>

<f:render section="MyTemplate" />

When to use:

• Reusable UI elements
• Components used across multiple templates
• Reducing duplicate code

Key Takeaway

• Templates = page structure
• Layouts = shared wrapper
• Partials = reusable components

This architecture is designed for scalability and maintainability, especially in large TYPO3 projects.

TYPO3 Fluid ViewHelpers (Complete Guide with Examples)

ViewHelpers are reusable building blocks in TYPO3 Fluid used to handle formatting, linking, rendering, and more. They help reduce custom code and speed up development.

Below are the most commonly used ViewHelpers, grouped by purpose.

Formatting ViewHelpers in TYPO3 Fluid

Used to format text, dates, and content output.

<!-- Date formatting -->
<f:format.date>{dateObject}</f:format.date>
<!-- Output: 1980-12-13 -→

<!-- Change case -->
<f:format.case>Some Text with miXed case</f:format.case>
<!-- Output: SOME TEXT WITH MIXED CASE -→

<!-- Line breaks -->
<f:format.nl2br>{text_with_linebreaks}</f:format.nl2br>
<!-- Output: Converts line breaks to <br /> -→

<!-- Strip HTML tags -->
<f:format.stripTags>Some Text with <b>Tags</b></f:format.stripTags>
<!-- Output: Some Text with Tags -→

Linking ViewHelpers in TYPO3 Fluid

Used to generate links dynamically within TYPO3.

<f:link.typolink parameter="{link}">
 Linktext
</f:link.typolink>

Output:

<a href="/page/path/name.html?X=y" title="testtitle with whitespace" target="_blank">
 Linktext
</a>

Media ViewHelpers (Images & Videos)

Used for rendering images, videos, and media assets.

<!-- Image rendering -->
<f:image src="EXT:myext/Resources/Public/typo3_logo.png" alt="alt text" />
<f:image image="{imageObject}" />
<!-- Inline notation -->
{f:image(src: 'EXT:viewhelpertest/Resources/Public/typo3_logo.png', alt: 'alt text', minWidth: 30, maxWidth: 40)}
<!-- Media rendering -->
<f:media file="{file}" width="400" height="375" />

Output:

• Image → <img ... />
• Video → <video ...>

Debugging ViewHelpers in TYPO3 Fluid

Used during development to inspect variables and data.

<f:debug>{testVariables.array}</f:debug>

Output:

• Displays structured debug information on screen

Other Useful ViewHelpers

<!-- Pagination -->
<f:widget.paginate objects="{blogs}" as="paginatedBlogs">
 <!-- Use inside loop -->
</f:widget.paginate>

<!-- TypoScript object rendering -->
<f:cObject typoscriptObjectPath="lib.customHeader" data="{article}" currentValueKey="title" />

<!-- Translation -->
<f:translate key="key1" />
{f:translate(key: 'someKey', arguments: {0: 'dog', 1: 'fox'}, default: 'default value')}

<!-- Forms -->
<f:form action="..." name="customer" object="{customer}">
  <f:form.hidden property="id" />
  <f:form.textfield name="myTextBox" value="default value" />
</f:form>

<!-- Comments (not rendered) -->
<f:comment>Some comment</f:comment>

Key Takeaway

• ViewHelpers reduce the need for custom logic
• They improve readability and maintainability
• They are essential for building scalable TYPO3 templates

TYPO3 Fluid Variables, Conditions & Loops (With Examples)

TYPO3 Fluid provides built-in ways to handle dynamic data using variables, conditions, and loops.

You can define and use variables directly inside templates.

{f:variable(name: 'FluidVariable', value: 'Assign Value')}
<f:variable name="FluidVariable">Assign Value</f:variable>

If Conditions

Used to control rendering based on conditions.

<f:if condition="{FluidVariable} > 100">
  <f:then>True</f:then>
  <f:else>False</f:else>
</f:if>

Loops (f:for)

Used to iterate over arrays or collections.

<f:variable name="FluidArray">
  {fruit1: 'apple', fruit2: 'pear', fruit3: 'banana', fruit4: 'cherry'}
</f:variable>

<f:for each="{FluidArray}" as="fruit" key="label">
  <li>{label}: {fruit}</li>
</f:for>

Switch Case

Used for multiple conditional branches.

<f:switch expression="{person.gender}">
  <f:case value="male">Mr.</f:case>
  <f:case value="female">Mrs.</f:case>
  <f:defaultCase>Mr. / Mrs.</f:defaultCase>
</f:switch>

Key Takeaway

These core features allow you to control how data is displayed in TYPO3 Fluid templates without writing complex backend logic.

Explore More

Real Use Cases of TYPO3 Fluid in Projects

TYPO3 Fluid is used in real projects to handle frontend rendering in a structured and scalable way. Below are the most common use cases in TYPO3 projects.

TYPO3 CMS Template Rendering

Fluid is used to build complete page templates in TYPO3.

• Render dynamic content from backend (text, images, content elements)
• Structure pages using Templates, Layouts, and Partials
• Control output using conditions and loops

Example: Homepage, blog pages, landing pages

TYPO3 Extension Development with Fluid

Fluid is widely used in custom TYPO3 extensions.

• Render data from controllers (Extbase)
• Display database-driven content
• Build custom modules and plugins

Example: Blog extension, product listing, custom forms

Multi-language Websites with TYPO3 Fluid

Fluid integrates with TYPO3’s localization system.

• Use <f:translate> for language labels
• Render multilingual content dynamically
• Maintain consistent templates across languages

Example: German-English enterprise websites

Reusable Components

Fluid enables component-based development.

• Use Partials for reusable UI blocks
• Maintain consistency across pages
• Reduce duplicate code

Example: Cards, headers, footers, content sections

Key Takeaway

TYPO3 Fluid is not just a template engine, it’s the foundation for building scalable, maintainable, and enterprise-ready TYPO3 frontend systems.

TYPO3 Fluid vs Other Template Engines

Here’s a practical comparison of TYPO3 Fluid with other popular template engines.

Why TYPO3 Fluid is Best for TYPO3 Projects

• Native integration → Works directly with TYPO3 core features
• No extra setup → Already included in TYPO3
• Optimized for TYPO3 rendering → Better performance within TYPO3 context
• ViewHelpers ecosystem → Built specifically for TYPO3 use cases
• Enterprise-ready → Stable and scalable for large TYPO3 projects

Key Takeaway

If you are working within TYPO3, TYPO3 Fluid is the most efficient and reliable choice. Other template engines like Twig or Blade are better suited for their own ecosystems, not TYPO3.

When to Use TYPO3 Fluid (and When Not To)

Choosing the right templating engine depends on your project requirements. Here’s when TYPO3 Fluid fits best, and when it doesn’t.

When to Use TYPO3 Fluid

TYPO3 Fluid is the best choice when working within the TYPO3 ecosystem and building structured, scalable frontend solutions.

• TYPO3-based enterprise websites
• CMS-driven structured projects
• Projects requiring strong separation of logic and presentation
• Long-term maintainable TYPO3 implementations

When Not to Use TYPO3 Fluid

TYPO3 Fluid is not ideal outside the TYPO3 ecosystem or for lightweight use cases.

• Non-TYPO3 PHP frameworks
• Lightweight applications without TYPO3
• Projects requiring minimal templating logic
• Environments where Twig or Blade are already deeply integrated

How to Create Custom TYPO3 Fluid ViewHelpers (Step-by-Step)

TYPO3 Fluid allows you to extend functionality by creating custom ViewHelpers when built-in ones are not enough.

Step 1. Create Custom ViewHelper (PHP Class)

<?php
// File: /typo3conf/ext/extension_key/Classes/ViewHelpers/MystyleViewHelper.php

namespace Vendor\Package\ViewHelpers;

class MystyleViewHelper extends \TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper
{
  public function initializeArguments()
  {
      $this->registerArgument('text', 'string', 'My custom argument', true);
  }

  public function render()
  {
      return '<div class="my-custom-style">' . $this->arguments['text'] . '</div>';
  }
}
?>

Step 2. Use ViewHelper in Template

{namespace ns=Vendor\Package\ViewHelpers}

<!-- Tag-based -->
<ns.mystyle text="Special content" />

<!-- Inline -->
{ns:mystyle(text:'Special content')}

When to Use Custom ViewHelpers vs Partials

• Use ViewHelpers
  • When logic or transformation is required
  • Reusable logic across multiple templates
  • Data formatting or manipulation
• Use Partials
  • For reusable UI components
  • Layout/HTML structure reuse
  • No heavy logic required

Best Practices

• Keep ViewHelpers focused and single-purpose
• Avoid embedding large HTML blocks in ViewHelpers
• Use them for logic, not layout
• Reuse existing ViewHelpers before creating new ones

Naming Conventions

• Use clear, descriptive names (e.g., PriceFormatterViewHelper)
• Follow TYPO3 extension namespace structure
• Keep naming consistent across the project

Common TYPO3 Fluid Mistakes & Debugging Guide

These are common issues developers face while working with TYPO3 Fluid.

Debugging with <f:debug>

<f:debug>{variable}</f:debug>

• Outputs structured variable data
• Useful during development and troubleshooting

Common Issues

Syntax Errors

• Missing {} or incorrect ViewHelper usage
• Incorrect nesting of Fluid tags

Fix:
Double-check syntax and ensure proper opening/closing of ViewHelpers.

Caching Issues

• Changes not reflecting in the frontend
• Old output still visible after updates

Fix:
Clear TYPO3 system cache and, if needed, browser cache.

Rendering Problems

• Incorrect template, layout, or partial path
• Expected data not showing

Fix:
Verify file paths and ensure variables are correctly passed from the controller.

Poor Template Structure

• Mixing business logic inside templates
• Overusing nested ViewHelpers

Fix:
Move logic to controllers or custom ViewHelpers. Keep templates focused on presentation.

Reusability Issues

• Not using partials for reusable UI components
• Duplicate code across templates

Fix:
Use partials to create reusable and consistent UI elements.

Performance Mistakes

• Ignoring TYPO3 caching mechanisms
• Excessive rendering logic inside templates

Fix:
Leverage TYPO3 caching and optimize template structure for better performance.

TYPO3 Fluid Performance Optimization Tips

For scalable TYPO3 projects, optimizing Fluid templates is important.

Best Practices to Improve TYPO3 Fluid Performance

• Avoid deeply nested ViewHelpers
  • Reduces rendering overhead
• Use Partials efficiently
  • Reuse components instead of duplicating code
• Minimize logic in templates
  • Move complex logic to controllers
• Reduce unnecessary rendering
  • Avoid repeated loops or conditions
• Cache smartly
  • Use TYPO3 caching mechanisms where possible

Key Takeaway

Efficient use of ViewHelpers and clean template structure directly impacts performance, especially in enterprise TYPO3 projects.

TYPO3 Fluid Tips & Best Practices for Developers

Here are practical tips to work efficiently with TYPO3 Fluid in real projects.

Use fluid_styled_content as Reference

Explore EXT:fluid_styled_content in TYPO3 core.

• Understand how TYPO3 structures templates
• Learn best practices for layouts, partials, and content rendering
• Reuse proven patterns instead of building from scratch

Reuse Partials for Consistency

• Break UI into reusable partials (cards, sections, headers)
• Avoid duplicating HTML across templates
• Helps maintain consistency across large projects

Keep Logic Out of Templates

• Avoid complex conditions and calculations in Fluid
• Move logic to controllers or ViewHelpers
• Keep templates focused on presentation

Use Inline Notation Efficiently

• Use inline notation for small expressions inside attributes
• Avoid mixing tag-based syntax inside HTML attributes

Use Debugging During Development

• Use <f:debug> to inspect variables
• Helps quickly identify missing or incorrect data

Follow a Consistent Structure

• Maintain clear separation: Templates, Layouts, Partials
• Stick to naming conventions across the project
• Makes collaboration easier in teams

Use IDE Snippets

• Use TYPO3 Fluid snippets in VS Code or PHPStorm
• Speeds up development and reduces syntax errors

Key Takeaway

Focus on clean structure, reuse, and minimal logic in templates to build scalable TYPO3 Fluid implementations.

Conclusion

TYPO3 Fluid is a core part of working with TYPO3. Whether you’re building templates or developing extensions, a solid understanding of Fluid helps you create clean, scalable, and maintainable frontend output.

If you're working as a TYPO3 developer or integrator, mastering Fluid is not optional, it’s part of the job.

If you have questions or face issues while working with TYPO3 Fluid, feel free to share them. Practical challenges are common, and solving them improves your workflow over time.

If you're exploring how AI is being used in TYPO3 projects, you can also look into the TYPO3 AI ecosystem to understand how workflows are evolving.