TypoScript Conditions Cheatsheet: Syntax, Examples and Migration

Modern TypoScript conditions help you write cleaner, safer, and more maintainable TYPO3 configuration. This ultimate guide is built as a practical cheatsheet, focused on real-world examples using Symfony Expression Language for fast copy-paste and immediate use.

Since TYPO3 v9.4, Symfony Expression Language powers modern TypoScript conditions and replaces legacy syntax. If you work with TYPO3 daily, you already know how critical conditions are for controlling rendering, environments, and behavior across projects.

Instead of theory, this guide focuses on how modern TypoScript conditions actually work, including variables, functions, custom conditions, and common pitfalls. 

In this guide, we will walk through everything you need to use TypoScript conditions correctly, confidently, and upgrade-safe.

Short answer: A TypoScript condition is a Symfony Expression Language expression in square brackets, such as [frontend.user.isLoggedIn]. The TypoScript below it applies only while the expression is true, until [ELSE], [END] or [GLOBAL]. Conditions read variables such as page and tree and functions such as site(), and work in TYPO3 9.4 and newer.

Key takeaways

• The legacy syntax such as [globalVar = ...] was deprecated in TYPO3 9.5 and removed in TYPO3 10.
• getTSFE() was removed in TYPO3 v14. Read the page ID with request?.getPageArguments()?.getPageId().
• loginUser() and usergroup() were deprecated in v12 and removed in v13. Use frontend.user and backend.user.
• Since TYPO3 v12, [END] and [GLOBAL] behave the same, and conditions can only be nested across separate files, for example with @import.
• TYPO3 v14 adds locale() as a shortcut to the site locale. ip() works only in frontend TypoScript since v13.
• Guard request checks with request && or the null-safe operator ?. so they cannot fail in CLI or TSconfig.

Tested with / valid for: TYPO3 v13.4 LTS and v14.3 LTS, checked against the official TypoScript reference on conditions and the TYPO3 Core changelog.
Updated: November 2026

Each condition below is copy-paste ready for frontend TypoScript setup. The "Works in" column names the first TYPO3 version that supports the syntax; every row was checked against the TypoScript reference for v13.4 and v14. FE means frontend TypoScript, BE means backend TSconfig.

Syntax in one block

[frontend.user.isLoggedIn]
   page.10.value = Welcome back
[ELSE]
   page.10.value = Please log in
[END]

Combine checks with && or and, || or or, and negate with !. Since TYPO3 v12, [END] and [GLOBAL] do the same thing (syntax reference).

Page and page tree

Site and language

Frontend and backend users

Request: host, HTTPS, parameters, device

Context, version, IP and date

Note: compatVersion("13.4") is also true on TYPO3 14, because it checks for "this version or newer". User agent checks are a rough signal; responsive CSS is the more reliable way to adapt layouts to devices.

TYPO3 provides a set of built-in variables that can be used directly in modern TypoScript conditions. These variables expose runtime information and are evaluated using Symfony Expression Language.

Each variable below represents a data source, not executable logic.

applicationContext - Application Environment

Returns the current TYPO3 application context as a string.

Common use cases

• Environment-based configuration
• Feature toggles per stage (Dev / Staging / Live)

[applicationContext == "Development"]
[applicationContext matches "#^Development#"]
[applicationContext matches "#^Production/Dev#"]
[applicationContext matches "#^Production/(Dev|Staging)#"]
[applicationContext matches "#^Production/Live#"]
[applicationContext == "Production/Live/ClusterServer1"]
[applicationContext matches "#^Production/Live#" && backend.user.isLoggedIn]
[not (applicationContext matches "#Production#")]

page - Page Properties

Provides access to the current page record as an array.

Common use cases

• Page-based rendering logic
• Template or layout switching

[page["pid"] == 2]
[page["uid"] == 17]
[page["backend_layout"] == 1]

TypoScript Constants - {$foo.bar}

All TypoScript constants are available inside conditions. Be mindful of data types when comparing values.

[{$foo.bar} == 4711]
["{$foo.bar}" == "4711"]

tree - Page Tree Information

Provides access to page tree and rootline data.

Common use cases

• Root page detection
• Section-based configuration

[tree.level == 0]
[tree.rootLine[0]["uid"] == 1]
[2 in tree.rootLineIds]
[30 in tree.rootLineParentIds]
[tree.pagelayout === "pagets__Home"]

backend - Backend User Context (FE and BE)

Exposes backend user information. Available in frontend TypoScript and in backend TSconfig.

[backend.user.isAdmin]
[backend.user.isLoggedIn]
[backend.user.userId == 5]
[2 in backend.user.userGroupIds]

frontend - Frontend User Context (FE Only)

Exposes frontend user authentication data. Available only in Frontend context.

[frontend.user.isLoggedIn]
[frontend.user.userId == 5]
[4 in frontend.user.userGroupIds]

typo3 - TYPO3 Environment Information

Provides TYPO3 system-level metadata.

[typo3.version == "14.3.5"]
[typo3.branch == "14.3"]
[typo3.devIpMask == "192.168.0.100"]

workspace - TYPO3 Workspace Context

Exposes workspace-related information. Primarily used in Backend context.

[workspace.workspaceId == 1]
[workspace.isLive]
[workspace.isOffline]

Important Notes

• Variables are read-only
• Availability depends on execution context (FE / BE)
• Prefer variables for simple, deterministic checks

A condition that never matches is usually evaluated in the wrong context, uses a function your TYPO3 version removed, or is served from cache. Most TypoScript condition issues fail silently. The following problems account for the majority of real-world bugs.

1. getTSFE() Always Returns false

What happens

Conditions using getTSFE() never match.

Why it happens

• TYPO3 v14 removed getTSFE(), so such conditions never evaluate to true
• In v13.4 and older: the condition is evaluated in Backend, CLI, or Scheduler context where TSFE is not initialized

How to avoid

• Replace it with request?.getPageArguments()?.getPageId() or the page variable
• Never rely on it in Backend logic

2. Frontend vs Backend Context Confusion

What happens

Conditions always evaluate to false.

Why it happens

• frontend.* used in Backend
• backend.* used in Frontend

How to avoid

• Keep FE and BE conditions in separate blocks
• Never mix contexts in the same condition

3. site() or  siteLanguage() Returns null

What happens

Language or site-based conditions do not match.

Why it happens

• Site configuration not resolved
• Condition evaluated too early or in CLI

How to avoid

• Use site-related conditions only in FE
• Always assume null is possible

4. Type Mismatch (String vs Integer)

What happens

Condition looks correct but never matches.

Why it happens

• Comparing "1" with 1
• TypoScript constants evaluated as strings

How to avoid

• Match data types explicitly
• Be careful with quoted constants

5. Request Data Not Available

What happens

Request-based conditions fail unexpectedly.

Why it happens

• Condition evaluated in CLI or BE
• No HTTP request exists

How to avoid

• Use request.* only in FE
• Guard with request && and avoid during cache warmup or builds

6. A Nested Condition Closes the Outer One

What happens

The inner block applies even when the outer condition is false.

Why it happens

• Opening a new condition automatically closes the previous one
• Conditions cannot be placed inside curly brace blocks

How to avoid

• Since TYPO3 v12, nest across files: put @import inside the outer condition and the inner condition in the imported file
• Or combine both checks with && in one condition

7. Changes in Included Files Do Not Show Up

What happens

You edit a condition in an imported .typoscript file and the frontend still shows the old result.

Why it happens

• Since TYPO3 v12, TypoScript from included files is cached and a file change does not trigger re-rendering

How to avoid

• While logged in to the backend, reload the frontend with shift-reload
• Use "Flush frontend caches" before you test as a normal visitor

8. Conditions Fail in Page TSconfig

What happens

A condition that works in TypoScript setup never matches in page TSconfig or user TSconfig, or ip() throws an exception.

Why it happens

• request always evaluates to false in page and user TSconfig
• ip() needs a request and is frontend-only since TYPO3 v13

How to avoid

• Use backend.user, tree or site settings in TSconfig conditions

A linter catches unclosed brackets and malformed conditions before they reach production. See our tutorial on TypoScript Lint in TYPO3. The full rules are in the TypoScript syntax reference for conditions.

One of the biggest advantages of modern TypoScript conditions is the ability to define custom conditions. Unlike legacy userFunc–based conditions, Symfony Expression Language allows clean, reusable, and upgrade-safe extensions.

Legacy vs Modern Approach (Quick Context)

TYPO3 ≤ 9.3 (Legacy)

[userFunc = \Vendor\Extension\UserFunc\MyUserFunc('foo')]

TYPO3 ≥ 9.4 (Modern)

[variableA === 'valueB']

Modern conditions are:

• Declarative
• Readable
• Fully integrated into TYPO3 Core

Step 1: Register the Expression Language Provider

Register your custom provider inside the extension configuration.

File: Configuration/ExpressionLanguage.php

<?php
return [
   'typoscript' => [
       \Vendor\ExtensionName\ExpressionLanguage\CustomTypoScriptConditionProvider::class,
   ]
];

This makes your variables or functions available to TypoScript conditions.

Step 2: Implement the Custom Condition Provider

Create a provider that exposes variables to the expression language.

File: Classes/ExpressionLanguage/CustomTypoScriptConditionProvider.php

<?php

namespace Vendor\ExtensionName\ExpressionLanguage;

use TYPO3\CMS\Core\ExpressionLanguage\AbstractProvider;

class CustomTypoScriptConditionProvider extends AbstractProvider
{
   public function __construct()
   {
       $this->expressionLanguageVariables = [
           'variableA' => 'valueB',
       ];
   }
}

Key points

• Variables are read-only
• Values should be deterministic
• Avoid runtime-heavy logic here

Step 3: Use the Custom Condition in TypoScript

Once registered, the variable can be used like any built-in condition.

[variableA === 'valueB']
   page >
   page = PAGE
   page.10 = TEXT
   page.10.value = Matched
[GLOBAL]

The condition is evaluated using Symfony Expression Language and behaves consistently across TYPO3 versions.

Best Practices for Custom Conditions

• Use custom conditions for configuration decisions only
• Keep logic simple and predictable
• Avoid database queries, API calls, or user-specific data
• Always re-test custom providers during TYPO3 upgrades

Why This Approach Is Preferred

• No deprecated APIs
• Same provider API in TYPO3 v13.4 and v14
• Cleaner than userFunc
• Easier to maintain in enterprise projects

• TypoScript tips and tricks
• Insert a TYPO3 plugin via TypoScript
• TYPO3 FlexForm vs TCA