---
title: TinyMCE configuration API
slug: cms-13/docs/tinymce-configuration-api
docTags: 
createdAt: 2026-07-30T20:22:05.208Z
---

The TinyMCE configuration API lets you modify editor settings dynamically based on content context. Use transformations to customize behavior per property or plugin, and enable setting inheritance across content type hierarchies.

## Set transformations

Modify the settings object based on the current content by registering a `SettingsTransform` callback for a given property or plugin. Remove registered transformations by specifying the key. The callback receives the current settings instance, content, and property name. The content item can be `NULL`.

### Add a setting transformation

```csharp
services.Configure<TinyMceConfiguration>(config => {
      var locator = ServiceLocator.Current;
      ...
      config.For<ArticlePage>(t => t.MainBody)
        .AddSettingsTransform("custom", (settings, content, propertyName) => {
          settings["preferred-culture"] = locator.GetRequiredService<LanguageResolver>().GetPreferredCulture().Name;
        });

      // Remove a specific transform
      config.For<ArticlePage>(t => t.MainBody)
        .RemoveSettingsTransform("custom");
      ...
    }
```

### Add a setting transformation for a plugin

Plugin developers that need custom initialization code based on the current content item register the transformation callback with the plugin.

```csharp
services.Configure<TinyMceConfiguration>(config => {
        ...
        
  config.Default()
    .AddPlugin("custom-plugin", (settings, content, propertyName) => {
      settings["custom-plugin-setting"] = content.Id;
     })
     .RemovePlugin("custom-plugin"); // Will remove the plugin and any registered transformations;
     
      config.Default()
        .AddExternalPlugin("custom-external-plugin", "http://url.js", (settings, content, propertyName) => {
           settings["custom-external-setting"] = content.Id;
        });
     ...
 }
```

### Exceptions

When your code throws an exception, the system handles and logs it, passes it to the client, and displays an error message to the user.

### Order of execution

Plugin transformations run before settings transformations. Site developers modify settings after plugin developers complete their changes.

```csharp
services.Configure<TinyMceConfiguration>(config => {
     ...

      config.Default()
      .AddPlugin("custom-plugin", (settings, content, propertyName) => {
        settings["custom-plugin-setting"] = "plugin value";
      });

      config.Default()
      .AddSettingsTransform("custom-settings", (settings, content propertyName) => {
        settings["custom-plugin-setting"] = "I have modified the plugins settings value";
      });

      ...
    }
```

## Inherit settings from ancestors

Setting inheritance lets you define a configuration on a base content type and have descendant types inherit it automatically, reducing duplicate configuration code.

To inherit settings from an ancestor, set the `InheritSettingsFromAncestor` property to true. It is set to false by default.

```csharp
config.InheritSettingsFromAncestor = true
```

This global setting applies to all configured types.

If `InheritSettingsFromAncestor` is true, Optimizely resolves the setting for a property starting with the leaf type. The system traverses upward in the inheritance hierarchy to find the closest ancestor with a setting for that property. When no match exists in the class hierarchy, `Default()` is used.

### Inheritance example

:::hint{type="info"}
**Note**
Do not change this property from plug-ins. Use it only when configuring the site.
:::

```csharp
abstract class ProductBase {
  public virtual XHtml ProductDescription {
    get;
    set;
  }
}

class ProductPage: ProductBase {}
class ShoeProductPage: ProductPage {}
class ShirtProductPage: ProductPage {}
class BlueShirtProductPage: ShirtProductPage {}
class VerySpecialProductPage: ProductPage {}
class AndEvenMoreSpecialProductPage: VerySpecialProductPage {}

// Init
services.Configure<TinyMceConfiguration>(config => {
      // Enable inheritance of settings
      config.InheritSettingsFromAncestor = true;

      config.Default()
        .Toolbar("epi-image");

      var baseSettings = config.Default().Clone();
      baseSettings
        .AddPlugin("product-selector")
        .Toolbar("product-selector cut paste");

      // Will be applied for every descendants unless they have set a specific setting
      config.For<ProductBase>(t => t.ProductDescription, baseSettings);

      // Will be based on Default() and not the setting configured on the ancestor
      config.For<BlueShirtProductPage>(t => t.ProductDescription)
        .AppendToolbar("color-picker");

      config.For<VerySpecialProductPage>(t => t.ProductDescription, baseSettings)
        .Toolbar("cut past | product-selector | spellchecker);
        });

    /**
     * Page                              Toolbar
     * ==========================================================================
     * ProductPage                       product-select cut paste
     * ShoeProductPage                   product-select cut paste
     * ShirtProductPage                  product-select cut paste
     * BlueShirtProductPage              epi-image | color-picker
     * VerySpecialProductPage            cut paste | product-select | spellchecker
     * AndEvenMoreSpecialProductPage     cut paste | product-select | spellchecker
     **/
```