Study guide · TypoScript

Understanding TypoScript: syntax, conditions, data sources and page TSconfig

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

TypoScript is the language you use to tell TYPO3 how to output a website. On this page you follow the integrator Mara at the Lindenau music school. She sets the page title, fetches data from the site and tidies up the backend for the editors. Afterwards you can read TypoScript, track down errors and you know what changed in TYPO3 14.

What TypoScript is

TypoScript is a configuration language. It describes how TYPO3 generates the output of a page. TYPO3 reads the text and converts it internally into a large PHP array. So TypoScript does not run in the browser. It is not a programming language with loops and your own functions either, and it does not query a database.

Mara works in a Composer project with TYPO3 14.3. Her site package is called lindenau_site, as a Composer package lindenau/site. It contains a site set with the TypoScript for the frontend. The music school website includes this set.

In the TypoScript tree you tell three things apart:

  • An object has a type, for example PAGE, TEXT, COA or IMAGE. These types are called content objects, or cObjects for short, because they produce output.
  • A property configures an object. For example, value is a property of the TEXT object.
  • A function such as stdWrap, typolink or parseFunc processes values. It has properties of its own, for stdWrap these include wrap and data.

You address properties with dots. There is no arrow like in PHP. You do not call functions with parentheses either. Parentheses after a function name only appear with the operator that modifies values, which you will meet further down.

The syntax: paths, values, brackets

Every line consists of a path, an operator and a value. Dots separate the levels of the path. The equals sign assigns the rest of the line as the value. The double equals sign, on the other hand, is a comparison and only belongs in conditions.

page = PAGE
page.10 = TEXT
page.10.value = Welcome to the music school
page.10.wrap = <p>|</p>

# Same effect, written shorter
page {
  10 = TEXT
  10.value = Welcome to the music school
}
TypoScript example. page becomes an object of type PAGE. page dot 10 becomes a TEXT with the value Welcome to the music school, wrapped in a paragraph tag. Below it, the same with curly braces, so you do not repeat the path on every line.

Curly braces group assignments under a common path. If the braces after page contain the line 10 equals TEXT, that is the same as the line page dot 10 equals TEXT.

Parentheses enclose multi-line values. Square brackets stand for conditions. Do not mix up these three kinds of brackets.

Comments for a single line start with a hash sign or with two slashes. A comment block across several lines sits between slash-asterisk and asterisk-slash. Careful: if these characters come after an equals sign, they are part of the value. That is why you write comments on a line of their own.

# Comment with a hash sign
// Comment with two slashes
/*
  Comment block across several lines
*/
page.20 = TEXT
page.20.value (
  Lessons for children and adults.
  Trial lessons at any time.
)
TypoScript example. Two single-line comments, one with a hash sign, one with two slashes. Then a comment block. Then a multi-line value in parentheses for page dot 20.

Constants are written in setup as a dollar sign with the name of the constant in curly braces. TYPO3 replaces them before evaluating the setup. If the constant is missing, nothing is replaced. The placeholder then shows up literally in the frontend. You will learn how to find such problems in the section on debugging.

lib.phone = TEXT
lib.phone.value = {$lindenau.telefon}
TypoScript example. The constant lindenau dot telefon is inserted into the value of lib.phone.

Copying, referencing, deleting, modifying

Besides assignment, TypoScript knows four more operators.

Copying with the less-than sign takes over a path with its value and all sub paths. The copy is made exactly at the line where it stands. Later changes to the original do not reach the copy.

Referencing with an equals sign followed by a less-than sign copies nothing. It points to the original instead. TYPO3 only resolves the reference when it renders a content object. That is why later changes to the original also reach the target. This happens for every content object in setup, for example below lib or tt_content, and also for parseFunc. Plain values such as a wrap, and constants, are not resolved.

Deleting with the greater-than sign removes a path with everything below it. This lets you remove, for example, an object that an included set brings along.

Modifying with a colon and an equals sign calls a function on the existing value. The function addToList adds an item to a comma-separated list. Other functions include removeFromList and replaceString.

lib.a = TEXT
lib.a.value = A
lib.b < lib.a
lib.c =< lib.a
lib.a.value = X

page.30 >
lib.list.value := addToList(new)
TypoScript example. lib.a becomes a TEXT with the value A. lib.b is a copy of lib.a, lib.c is a reference to lib.a. Then lib.a gets the value X. page dot 30 is deleted. Finally, addToList adds the item new to a list.
lib.a = TEXT value first A, later X Copy lib.b < lib.a copied when this line is parsed Output: A Reference lib.c =< lib.a resolved only when rendering Output: X References work for content objects in setup, not for plain values or constants.
The copy freezes the state of its line, the reference follows the original.

So if lib.b and lib.c are output as content objects, lib.b shows A and lib.c shows X.

# Wrong: read as a reference
lib.nav.wrap =<ul>|</ul>
# Right
lib.nav.wrap = <ul>|</ul>
TypoScript example. The first line without a space is read as a reference. The second line with a space assigns the wrap as intended.

Where TypoScript comes from: sets, site and imports

Since TYPO3 13, a site set ships its TypoScript as files. The files setup.typoscript and constants.typoscript sit next to the set's config.yaml. Not inside the config.yaml itself and not in composer.json. TYPO3 loads them for every site that uses the set. A sys_template record on the home page is then no longer needed, but still possible.

The site itself is also a source of TypoScript. If a setup.typoscript sits next to the site's config.yaml, TYPO3 loads it automatically. The site has its own scope. It does not inherit TypoScript from a parent site in the page tree.

1 Sets the site depends on in dependency order 2 Site settings override constants of the same name 3 TypoScript of the site files next to its config.yaml 4 sys_template records optional, applied last What is loaded later wins.
This is the order in which TYPO3 builds the TypoScript of a site. What comes later wins.

Site settings override constants of the same name from the sets. So every site can set a value such as the phone number differently, without changing the set.

Further files are included with @import, followed by the path in single quotes. Wildcards such as an asterisk before the file extension typoscript are allowed. The old syntax with INCLUDE_TYPOSCRIPT no longer exists in TYPO3 14.

@import 'EXT:lindenau_site/Configuration/TypoScript/setup.typoscript'
@import 'EXT:lindenau_site/Configuration/TypoScript/Parts/*.typoscript'
TypoScript example. The first line imports a file setup.typoscript from the site package lindenau_site. The second imports all files with the extension typoscript from a folder.

Other sets, however, are not pulled in by import. If Mara's set should bring along the TypoScript of Fluid Styled Content, she adds the Fluid Styled Content set as a dependency in her set's config.yaml. TYPO3 orders the dependencies and loads a set that several others need only once. This is the recommended way. Copying files or importing someone else's files makes the project hard to maintain. Import is meant for your own local files.

name: lindenau/site
label: Lindenau Music School
dependencies:
  - typo3/fluid-styled-content
YAML example. The config.yaml of the set lindenau slash site depends on the set fluid-styled-content.

Data types and top-level objects

Every property expects a certain data type. The TypoScript Reference lists it for each property. The most important ones:

  • string is plain text, such as the value of a TEXT object.
  • integer is a whole number.
  • boolean stands for true or false and is written as 1 or 0.
  • list is a comma-separated list.
  • wrap is an envelope with a vertical bar. TYPO3 inserts the content where the bar is. A wrap with a paragraph tag before and after the bar therefore puts a paragraph around the content.
  • getText is an expression that fetches values from a source, such as a field of the record, the page or the site. The data property of stdWrap expects this type.
  • imgResource describes an image including its processing, for example size and cropping.

Top-level objects, TLO for short, are the names on the top level of the TypoScript tree. Some have a fixed type and already exist, others you must create yourself:

  • You must create page explicitly by assigning it the type PAGE. Any other name does not turn into a page by itself.
  • config has the type CONFIG and already exists. It holds global output settings.
  • plugin is pre-initialized as well. It holds the settings of frontend plugins, for each extension under tx and its name.
  • lib is the place for reusable building blocks such as lib.mainMenu, which you include by copy or reference. It has nothing to do with PHP libraries.
  • module is meant for backend modules.
  • styles and the names starting with tt, such as tt_content, are reserved too.
  • resources and sitetitle are read-only according to the reference.

The config object and the page title

Below config you find settings that affect the whole output. Database connection, user permissions or Composer packages do not belong here. Typical properties are:

  • config.cache_period sets the lifetime of the page cache.
  • config.admPanel switches the Admin Panel in the frontend on or off.
  • config.additionalHeaders sets additional HTTP headers.
  • config.pageTitleProviders defines where the page title comes from.
  • config.contentObjectExceptionHandler controls what happens on errors in content objects.

You do not configure backend layouts or sitemaps below config, but elsewhere.

Additional headers are a numbered array. Each entry needs header and can have replace and httpResponseCode. Do not confuse this with headerData of the page object. That writes HTML into the head of the page, but no HTTP header.

config.additionalHeaders.10.header = X-Frame-Options: SAMEORIGIN
config.admPanel = 1
TypoScript example. Entry 10 of config.additionalHeaders sets the header X-Frame-Options to SAMEORIGIN. Below it, the Admin Panel is switched on.

Errors in plugins: If a content object throws an exception while rendering, usually a plugin, the contentObjectExceptionHandler steps in when the context is Production. It catches the error. Instead of the object, a short notice appears at this spot, and the rest of the page stays intact. Since TYPO3 13 the notice shows the request ID. TYPO3 writes the error to the log with the same request ID, so you can find it again. In the Development context the handler does not step in by default. There the whole page stops with the exception, so you see the error and can fix it. With the value 0 you also switch the handler off in Production.

The page title in the HTML title tag can come from several sources, for example from the SEO field of the page or from a record. Each source is a page title provider. TYPO3 asks them in order. The first one that delivers a title wins. You define the order in config.pageTitleProviders with the properties before and after. Extensions can ship their own providers.

config.pageTitleProviders {
  seo {
    provider = TYPO3\CMS\Seo\PageTitle\SeoTitlePageTitleProvider
    before = record, recordTitle
  }
}
TypoScript example. The provider seo is placed before the providers record and recordTitle. This gives the SEO title priority.

The music school has a detail page for its courses. There, the course name should appear in the page title. TYPO3 14 offers two ways. The new ViewHelper f:page.title sets the title directly in the Fluid template. It uses the new provider recordTitle and so respects the order of the providers. Or the extension registers its own provider, which Mara places with before and after. Hard-coding the title in the configuration or writing it into the navigation title field does not solve the problem.

Conditions

Conditions are written in square brackets. What follows only applies if the condition is true. With ELSE you write the other case, with END or GLOBAL you close the condition. Since TYPO3 9, conditions are evaluated with the Symfony Expression Language. It knows operators such as the double equals sign, logical and, and logical or, plus functions such as site(), date() or traverse().

For the English website Mara needs a different footer text, and she wants to show some things to logged-in members only.

[frontend.user.isLoggedIn]
  lib.memberHint.value = Hello member
[END]

[site("identifier") == "lindenau"]
  lib.footer.value = Lindenau Music School
[END]

[tree.pagelayout == "pagets__home"]
  page.10.value = Home page
[END]

[request && request.getNormalizedParams().getHttpHost() == "www.lindenau.example"]
  config.admPanel = 0
[END]
Conditions. The first is true when a frontend user is logged in. The second checks whether the site has the identifier lindenau. The third checks whether the page uses the backend layout pagets__home, also when inherited. The fourth checks the host of the request. Each one is closed with END.

What the conditions check:

  • frontend.user.isLoggedIn is true when a frontend user is logged in. You check groups with frontend.user.userGroupIds.
  • backend.user.isAdmin checks whether an admin is logged in to the backend.
  • The function site() returns values from the site configuration such as identifier, base or rootPageId. For the language there is siteLanguage().
  • tree.pagelayout also takes into account the backend layout that a parent page passes on to its subpages. The backend_layout field of the page itself, by contrast, only checks that page.
  • The function traverse() reads values from arrays such as page, for example the uid of the current page.
  • The function session() reads values from the frontend session. A vertical bar goes one level deeper into the stored structure.
  • The normalized parameters of the request return the host, the HTTPS status and more.

New in TYPO3 14: The function getTSFE() has been removed. Conditions using it never match anymore. You now get the page ID from the PageArguments of the request.

The old syntax from before the Expression Language, for example with globalVar, globalString, usergroup or loginUser, has not worked since TYPO3 10.

[request?.getPageArguments()?.getPageId() == 42]
[traverse(page, "uid") in [17,24]]
[session("foo|bar") == 1234567]
Conditions. The first uses the null-safe operator to check whether the page ID from the request's PageArguments is 42. The second uses traverse to check whether the uid of the page is 17 or 24. The third checks whether the session holds the value 1234567 under foo and bar.

Data sources with getText

The data property fetches a value from a data source. Its value is a getText expression made of a key, a colon and a code. The key page with the code title, for example, returns the title of the current page. Not the title of the website and not the one of the home page.

lib.pageTitle = TEXT
lib.pageTitle.data = page:title

lib.headline = TEXT
lib.headline.data = field:header // field:title

lib.phone = TEXT
lib.phone.data = siteSettings:lindenau.telefon

lib.userName = TEXT
lib.userName.data = request:frontend.user|username

lib.layout = TEXT
lib.layout.data = levelfield:-1, backend_layout_next_level, slide
TypoScript example. Five TEXT objects fetch values. They fetch the page title and the header with a fallback to the title. They also fetch the phone number from the site settings and the username of the logged-in frontend user. The last one fetches the backend layout, taken from pages further up if needed.

The most important keys:

  • field reads a field of the current record. That is the record being rendered right now, such as a content element or the page.
  • page reads a field of the current page.
  • DB reads a field of a specific record from any TCA table. The code names table, uid and field, for example tt_content, 12 and header. Deleted records return nothing.
  • levelfield fetches a field from the rootline. Minus one is the current page. With slide, TYPO3 goes up until a value is not empty. This way you take over, for example, a backend layout from parent pages. Similarly, leveltitle returns page titles from the rootline.
  • site returns values from the site configuration such as base or identifier.
  • siteLanguage returns values of the current language.
  • siteSettings reads a value from the site settings, such as Mara's phone number.
  • request reads attributes of the PSR-7 request.
  • asset returns the URL of a public file with cache busting.
  • applicationcontext returns the application context, such as Production.

Two slashes chain getText expressions as fallbacks. The first value that is not empty wins. In the example you get the header, and only if it is empty, the title. Here the two slashes are not a comment.

Field value or record? With data and field you fetch a single value. Whole records, by contrast, are fetched by content objects such as CONTENT and RECORDS or by a data processor.

parseFunc: outputting text from the editor

Text from the rich text editor, RTE for short, is HTML. Before it appears in the frontend, the function parseFunc processes it. The usual configuration for this is called lib.parseFunc_RTE. It converts links with typolink, for example internal links starting with t3 and a colon, into real URLs. It allows, removes or changes HTML tags, controlled by properties such as tags, allowTags, denyTags and externalBlocks. Finally it sends the text through the HTML Sanitizer. parseFunc does not execute PHP code, and it does not translate or upload anything.

New in TYPO3 14: Neither the frontend extension nor Fluid Styled Content presets allowTags anymore. All tags are allowed at first. The HTML Sanitizer decides which tags and attributes remain. The allowTags property still exists, though. If you set it, you restrict the output on purpose.

# Behaves differently in TYPO3 14: allows only wbr
lib.parseFunc_RTE.allowTags := addToList(wbr)
TypoScript example. The old line adds wbr with addToList and in TYPO3 14 thereby allows only this one tag.

Debugging: Active and Included TypoScript

TypoScript is assembled from many sources and conditions. To see what really applies on a page, you open the module “Sites” and there “TypoScript”. It has two important views.

  • Active TypoScript shows the constants and setup of a page as a tree. This is the result after all includes and conditions have been applied.
  • Included TypoScript shows the includes with their origin and order. Here you see which sets, files and records are loaded. This view also warns about syntax errors.
  1. In the frontend, the placeholder of a constant appears literally instead of the phone number.
  2. In Active TypoScript, Mara checks whether the constant is defined on this page at all and what exactly it is called.
  3. In Included TypoScript, she checks whether the file with the constant is loaded, in which order, and whether a syntax warning appears.
  4. She finds a typo in the name and fixes it.

Clearing the browser cache does not help here. A placeholder that was not replaced means TYPO3 does not know the constant.

Page TSconfig: adapting the backend

Page TSconfig has the same syntax as TypoScript, but a different job. It controls the backend per page or page tree, for example visible fields, default values or the wizard for new content elements. It does not control the frontend, the web server or the permissions of frontend users. Page TSconfig does not end up in the frontend page cache either.

There are three usual places:

  • A file page.tsconfig in the Configuration folder of an extension applies globally to the whole installation.
  • A file page.tsconfig in the folder of a site set only applies to the pages of the sites that use the set. The file for the frontend, by contrast, is called setup.typoscript.
  • The TSconfig field in the page properties applies to the page and is inherited by all subpages.

Mara wants to tidy up the form for the editors. With TCEFORM she adjusts form fields. The property disabled with the value 1 hides a field. Labels and selectable values can be changed this way too. TCEMAIN, by contrast, concerns saving, not the form.

She sets default values with TCAdefaults. Since TYPO3 14 this also works depending on the record type, through the sub key types. A type-specific value takes precedence over the general value of the field. Page TSconfig overrides User TSconfig here.

TCEFORM.tt_content.layout.disabled = 1
TCAdefaults.tt_content.header_layout = 2
TCAdefaults.tt_content.header_layout.types.textmedia = 3
Page TSconfig example. The layout field of tt_content is hidden. All new content elements get header level 2. Only text and media elements get level 3.

Key points

  • TypoScript is a configuration language and becomes a PHP array internally.
  • The equals sign assigns, less-than copies, equals followed by less-than references, greater-than deletes, colon followed by equals calls a function.
  • A copy freezes the state of its line. A reference is only resolved when a content object is rendered.
  • Sets ship their TypoScript in setup.typoscript next to their config.yaml. Sets the site depends on come first, site settings override constants.
  • Conditions use the Symfony Expression Language. The function getTSFE() no longer exists in TYPO3 14.
  • The data property fetches values with getText, for example from page, field, siteSettings or request.
  • allowTags is no longer preset in TYPO3 14.
  • Active TypoScript shows the result, Included TypoScript shows the includes.
  • Page TSconfig controls the backend and is inherited down the page tree.

Terms

Content object
Object that produces output, such as TEXT, COA or IMAGE.
getText
Expression made of a key and a code that fetches a value from a data source.
Constant
Placeholder that TYPO3 inserts into the setup before evaluating it.
Page title provider
Source for the page title, whose order config.pageTitleProviders defines.
Page TSconfig
Configuration of the backend per page or page tree.
Site set
Package of TypoScript, settings and page TSconfig that a site includes.
Top-level object
Name on the top level of the TypoScript tree, such as page, config or lib.

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

Sources:

  • TypoScript Reference 14.3, chapters Syntax, Operators, Conditions, Data and getText, Top-level objects, config, parseFunc and Debugging
  • TYPO3 Explained 14.3, chapters Site sets, PageTitle API and Page TSconfig
  • Changelog TYPO3 14 (getTSFE removed, parseFunc without preset allowTags, type-specific TCAdefaults, ViewHelper f:page.title, RecordTitleProvider)
  • Source code TYPO3 14.3 (typo3/cms-core, typo3/cms-frontend), checked for the reference operator, the loading order of sets and site, getText keys, contentObjectExceptionHandler and page title providers
  • Learning objectives TYPO3 CMS Certified Integrator 14 LTS, area TypoScript

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