TypoScript syntax

TypoScript is parsed in a very simple way; line by line. This means that abstractly said each line normally contains three parts based on this formula:

[Object Path] [Operator] [Value]


Extension examples, file Configuration/TypoScript/Syntax/General/setup.typoscript
myObject.myProperty = value 2

In this example we have the object myObject with the property myProperty and a value value 2.

Object path

The object path (in this case myObject.myProperty) is like the variable name in a programming language. The object path is the first block of non-whitespace characters on a line until one of the characters =<>{( or a white space is found. The dot (.) is used to separate objects and properties from each other creating a hierarchy.

Use only A-Z, a-z, 0-9, "-", "\_" and periods (.) for object paths!

Dots in the object path can be escaped using a backslash.

Escaping example:

Extension examples, file Configuration/TypoScript/Syntax/Escaping/setup.typoscript
my\.escaped\.key = test

This will result in an object named my.escaped.key with the value "test". Here we do not have three hierarchically structured objects my, escaped and key.


The operator (in the example it is =) can be one of the characters =<>{(. The various operators are described below.

Value assignment: The "=" operator

This assigns a value to an object path.


Everything after the = sign and up to the end of the line is considered to be the value. In other words: You don't need to quote anything!

Be aware that the value will be trimmed, which means stripped of whitespace at both ends.

Value modifications: The ":=" operator

This operator assigns a value to an object path by calling a predefined function which modifies the existing value of the current object path in different ways.

This is very useful when a value should be modified without completely redefining it again.


The portion after the := operator and to the end of the line is split in two parts: A function and a value. The function is specified right next to the operator (trimmed) and holding the value in parentheses (not trimmed).

This is the list of predefined functions:

Adds a string to the beginning of the existing value.
Adds a string to the end of the existing value.
Removes a string from the existing value.
Replaces old with new value. Separate these using |.
Adds a comma-separated list of values to the end of a string value. There is no check for duplicate values, and the list is not sorted in any way.
Removes a comma-separated list of values from an existing comma-separated list of values.
Removes duplicate entries from a comma-separated list of values.
Reverses the order of entries in a comma-separated list of values.

Sorts the entries in a comma-separated list of values. Optional parameters are:

Sort the items in ascending order: First numbers from small to big, then letters in alphabetical order. This is the default method.
Sort the items in descending order: First letters in descending order, then numbers from big to small.
Apply numeric sorting: Numbers from small to big, letters sorted after "0".

Multiple parameters are separated by comma.

There is a hook inside class \TYPO3\CMS\Core\TypoScript\Parser\TypoScriptParser which can be used to define more such functions.


Extension examples, file Configuration/TypoScript/Syntax/ValueModification/setup.typoscript
myObject = TEXT
myObject.value = 1,2,3
myObject.value := addToList(4,5)
myObject.value := removeFromList(2,1)

produces the same result as:

Extension examples, file Configuration/TypoScript/Syntax/ValueModification2/setup.typoscript
myObject = TEXT
myObject.value = 3,4,5

Code blocks: The { } signs

Opening and closing curly braces are used to assign many object properties in a simple way at once. It's called a block or nesting of properties.


  • Everything on the same line as the opening brace ({), but that comes after it is ignored.
  • The } sign must be the first non-space character on a line in order to close the block. Everything on the same line, but after } is ignored.
  • Blocks can be nested. This is actually recommended for improved readability.


Extension examples, file Configuration/TypoScript/Syntax/CodeBlock/setup.typoscript
myObject = TEXT
myObject.stdWrap.field = title
myObject.stdWrap.ifEmpty.data = leveltitle:0

could also be written as:

Extension examples, file Configuration/TypoScript/Syntax/CodeBlock2/setup.typoscript
myObject = TEXT
myObject {
   stdWrap {
      field = title
      ifEmpty {
         data = leveltitle:0

Multi-line values: The ( ) signs

Opening and closing parenthesis are used to assign a multi-line value . With this method you can define values which span several lines and thus include line breaks.


The end-parenthesis is extremely important. If it is not found, the parser considers the following lines to be part of the value and does not return to parsing TypoScript. This includes the [GLOBAL] condition which will not save you in this case! So don't miss it!


Extension examples, file Configuration/TypoScript/Syntax/MultiLine/setup.typoscript
myObject = TEXT
myObject.value (
   <p class="warning">
      This is HTML code.

Object copying: The "<" sign

The < sign is used to copy one object path to another. The whole object is copied - both value and properties - and it overrides any old objects and values at that position.


Extension examples, file Configuration/TypoScript/Syntax/ObjectCopying/setup.typoscript
myObject = TEXT
myObject.value = <p class="warning">This is HTML code.</p>

myOtherObject < myObject

The result of the above TypoScript is two independent sets of objects/properties which are exactly the same (duplicates). They are not references to each other but actual copies:

An object and its copy

Another example with a copy within a code block:

Extension examples, file Configuration/TypoScript/Syntax/ObjectCopying2/setup.typoscript
pageObj {
   10 = TEXT
   10.value = <p class="warning">This is HTML code.</p>
   20 < pageObj.10

Here also a copy is made, although inside the pageObj object. Note that the copied object is referred to with its full path (pageObj.10). When copying on the same level, you can refer to the copied object's name, prepended by a dot.

The following produces the same result as above:

Extension examples, file Configuration/TypoScript/Syntax/ObjectCopying3/setup.typoscript
pageObj {
   10 = TEXT
   10.value = <p class="warning">This is HTML code.</p>
   20 < .10

which – in tree view – translates to:

Another object and its copy

Object references: the equal smaller "=<" sign

In the context of TypoScript Templates it is possible to create references from one object to another. References mean that multiple positions in an object tree can use the same object at another position without making an actual copy of the object but by pointing to the objects full object path.

The obvious advantage is that a change of code to the original object affects all references. It avoids the risk mentioned above with the copy operator to forget that a change at a later point does not affect earlier copies. On the other hand there's the reverse risk: It is easy to forget that changing the original object will have an impact on all references. References are very convenient, but should be used with caution.

Note: Changing or adding attributes in the object holding a reference will not change the original object that was referenced.


Extension examples, file Configuration/TypoScript/Syntax/ObjectReference/setup.typoscript
someObject = TEXT
someObject {
   value = Hello world!
   stdWrap.wrap = <p>|<p>
anotherObject =< someObject
someObject.stdWrap.wrap = <h1>|<h1>

In this case, the stdWrap.wrap property of anotherObject will indeed be <h1>|<h1>. In tree view the properties of the reference are not shown. Only the reference itself is visible:

An object and a reference to it.


  • References are only available in TypoScript templates, not in TSconfig (user TSconfig or page TSconfig)
  • References are only resolved for Content Objects, otherwise references are not resolved. For example, you cannot use a reference < plugin.tx_example.settings.foo to find the value of foo. The value you get will be just < plugin.tx_example.settings.foo instead.

Object unsetting: The ">" Sign

This is used to unset an object and all of its properties.


Extension examples, file Configuration/TypoScript/Syntax/ObjectUnsetting/setup.typoscript
myObject = TEXT
myObject.value = <strong> HTML - code </strong>

myObject >

In this last line myObject is totally wiped out (removed).

Conditions: Lines starting with "["

Conditions break the parsing of TypoScript in order to evaluate the content of the condition line. If the evaluation returns true, parsing continues, otherwise the following TypoScript is ignored until the next condition is found, at which point a new evaluation takes place. The next section in this document describes conditions in more details.


Conditions apply only when outside of any code block (i.e. outside of any curly braces).


Extension examples, file Configuration/TypoScript/Syntax/Conditions/setup.typoscript
[date("j") == 9]
   page.10.value = It is the 9th day of the month!
   page.10.value = It is NOT the 9th day of the month!


The value (in case of the above example "value 2") is whatever characters follow the operator until the end of the line, but trimmed for whitespace at both ends. Notice that values are not encapsulated in quotes! The value starts after the operator and ends with the line break.


TypoScript support single line comments as well as multiline comment blocks.

Single line comments

When a line starts with // or # it is considered to be a comment and will be ignored.


Extension examples, file Configuration/TypoScript/Syntax/CommentsSingleLine/setup.typoscript
// This is a comment
myObject = TEXT
myObject.value = <strong>Some HTML code</strong>
# This line also is a comment.

Comment blocks

When a line starts with /* or */ it defines the beginning or the end of a comment section respectively. Anything, excluding imports, inside a comment section is ignored.


/* and */ must be the very first characters of a trimmed line in order to be detected.

Comment blocks are not detected inside a multi-line value block (see parenthesis operator below).


Extension examples, file Configuration/TypoScript/Syntax/CommentsBlock/setup.typoscript
/* This is a comment
.. and this line is within that comment which...
ends here:
*/  ... this is not parsed either though - the whole line is still within the comment
myObject = TEXT
myObject.value (
   Here is a multiline value which
    This is not a comment because it is inside a multi-line value block