---
title: Placeholder API
slug: cms-12/docs/placeholder-api
docTags: 
createdAt: 2026-08-10T15:55:58.000Z
---

:::hint{type="info"}
**Note**
[Optimizely Forms](docId:3SbSlJZIS_3iFmghfQA3J) is only supported by MVC-based websites and HTML5-compliant browsers.
:::

Two built-in features, [Email Actor](https://world.optimizely.com/documentation/developer-guides/forms/implementing-a-customized-actor/email-actor/) and `RichTextElement`, let an editor compose a template with placeholders inside. Placeholders are replaced with an actual value from form-submitted values.

The placeholder groups are as follows:

- **FormElements of current Form**, such as `::NAME::` (or `#NAME#`) and `::EMAIL::` (or `#EMAIL#`), are field names of a form. They are replaced with actual form submission values (for example, *John Doe* and [JDoe@example.com](mailto:_JDoe@example.com_)).

:::hint{type="info"}
**Note**
Forms 5.5.0 replaced placeholder syntax from hash (#) to double colons (\::), but Forms 5.5.1 added support for either hash (#) or double colons (\::). You should use double colons (\::) because they do not clash with some behaviors in TinyMCE.
:::

- **Predefined placeholder**, such as `::SUMMARY::` (or `#SUMMARY#`), outputs the values of all fields on a form.
- **Extra placeholder** by third-party developers (provided by custom `PlaceHolderProvider`).

You can list available placeholders in the **Insert placeholder** combobox so an editor can select a placeholder. The `EmailActor` and the `RichTextElement` has this combo box.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/KLbeYXHuDBQFHiAVp5yDL-20260722-170226.png "pasted-image-0.png")

:::hint{type="info"}
**Note**
The combobox Dojo widget has `FieldMappingTokenListViewModel;` it calls `FormsDataStore.GetAvailableReplacablePlaceHolders()` on server-side to get a list of placeholders.
:::

## Customized placeholder API

Placeholder processing is put in `PlaceHolderService`. You can replace `PlaceHolderService` with your own implementation with Dependency Injection. By default, it activates all instances of `IPlaceHolderProvider` interface and calls `ProcessPlaceHolders()`. `PlaceHolderService` calls available `IPlaceHolderProviders` in a chain of processing, through the `IPlaceHolderProviders.Order` property. The latter provider can alter the previous provider result.

`DefaultPlaceHolderProvider` is the default implementation of `IPlaceHolderProvider`, which replaces `FormElementPlaceHolders` with an actual value and provides an extra `::SUMMARY::`  (or `#SUMMARY#`) placeholder.