---
title: "replacement"
manual: "TypoScript Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3tsref:replacement@main"
source: "Functions/Replacement.rst"
rendered: "2026-09-19T06:55:14+00:00"
---

# replacement {#replacement}

This object performs an ordered search and replace operation on the
current content with the possibility of using [PCRE regular expressions](https://www.php.net/manual/en/reference.pcre.pattern.syntax.php).
An array with numeric indices defines the order of actions and thus
allows multiple replacements at once.

-   [Properties](https://docs.typo3.org/permalink/t3tsref:properties@main)
-   [Examples](https://docs.typo3.org/permalink/t3tsref:examples@main)

## Properties {#replacement-properties}

### search {#replacement-search}

-   **search**

    -   *Type:* [string](https://docs.typo3.org/permalink/t3tsref:data-type-string@main) / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@main)

    Defines the string that shall be replaced.

### replace {#replacement-replace}

-   **replace**

    -   *Type:* [string](https://docs.typo3.org/permalink/t3tsref:data-type-string@main) / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@main)

    Defines the string to be used for the replacement.

### useRegExp {#replacement-useregexp}

-   **useRegExp**

    -   *Type:* [boolean](https://docs.typo3.org/permalink/t3tsref:data-type-boolean@main) / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@main)
    -   *Default:* 0

    Defines that the search and replace strings are considered as PCRE
    regular expressions.

    **Example**

    **EXT:site_package/Configuration/Sets/Main/setup.typoscript**

    ```typoscript
    10 {
      search = #(a )CAT#i
      replace = \1cat
      useRegExp = 1
    }

    ```

### useOptionSplitReplace {#replacement-useoptionsplitreplace}

-   **useOptionSplitReplace**

    -   *Type:* [boolean](https://docs.typo3.org/permalink/t3tsref:data-type-boolean@main) / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@main)
    -   *Default:* 0

    This property allows to use [optionSplit](https://docs.typo3.org/permalink/t3tsref:optionsplit@main) for the replace
    property. That way the replace property can be different depending on the
    occurrence of the string (first/middle/last part, ...). This works for
    both normal and regular expression replacements. For examples see below.

## Examples {#replacement-examples}

**EXT:site_package/Configuration/Sets/Main/setup.typoscript**

```typoscript
10 = TEXT
10 {
  value = There_are_a_cat,_a_dog_and_a_tiger_in_da_hood!_Yeah!
  stdWrap.replacement {
    10 {
      search = _
      replace.char = 32
    }
    20 {
      search = in da hood
      replace = around the block
    }
    30 {
      search = #a (Cat|Dog|Tiger)#i
      replace = an animal
      useRegExp = 1
    }
  }
}

```

This returns: "There are an animal, an animal and an animal around the
block! Yeah!".

The following examples demonstrate the use of [optionSplit](https://docs.typo3.org/permalink/t3tsref:optionsplit@main):

**EXT:site_package/Configuration/Sets/Main/setup.typoscript**

```typoscript
20 = TEXT
20.value = There_are_a_cat,_a_dog_and_a_tiger_in_da_hood!_Yeah!
20.stdWrap.replacement.10 {
  search = _
  replace = 1 || 2 || 3
  useOptionSplitReplace = 1
}

```

This returns: "There1are2a3cat,3a3dog3and3a3tiger3in3da3hood!3Yeah!"

**EXT:site_package/Configuration/Sets/Main/setup.typoscript**

```typoscript
30 = TEXT
30.value = There are a cat, a dog and a tiger in da hood! Yeah!
30.stdWrap.replacement.10 {
  search = #(a) (Cat|Dog|Tiger)#i
  replace = ${1} tiny ${2} || ${1} midsized ${2} || ${1} big ${2}
  useRegExp = 1
  useOptionSplitReplace = 1
}

```

This returns: "There are a tiny cat, a midsized dog and a big tiger in da hood! Yeah!"