---
title: "New content element wizard"
manual: "TYPO3 Explained"
version: "13.4"
permalink: "https://docs.typo3.org/permalink/t3coreapi:content-element-wizard@13.4"
source: "ApiOverview/ContentElements/ContentElementsWizard.rst"
rendered: "2026-09-26T05:51:05+00:00"
---

# New content element wizard {#content-element-wizard}

<!-- TODO: no Markdown rendering for "versionchanged" -->

Custom content element types are auto-registered for the
New Content Element wizard. The listing can be configured using
TCA.

**Table of contents**

-   [Plain content elements or plugins](https://docs.typo3.org/permalink/t3coreapi:plain-content-elements-or-plugins@13.4)
-   [Plugins (Extbase) in the "New Content Element" wizard](https://docs.typo3.org/permalink/t3coreapi:plugins-extbase-in-the-new-content-element-wizard@13.4)
-   [Override the wizard with page TSconfig](https://docs.typo3.org/permalink/t3coreapi:override-the-wizard-with-page-tsconfig@13.4)
-   [Register a new group in the "New Content Element" wizard](https://docs.typo3.org/permalink/t3coreapi:register-a-new-group-in-the-new-content-element-wizard@13.4)
-   [Content elements compatible with TYPO3 v12.4 and v13](https://docs.typo3.org/permalink/t3coreapi:content-elements-compatible-with-typo3-v12-4-and-v13@13.4)

The content element wizard opens when a new content element is
created. It can be fully configured using ref:`Page TSconfig <t3tsref:pagetsconfig>`.

The wizard looks like this:

![](../../Images/ManualScreenshots/Backend/NewContentElementWizardAnnotated.png)

1.  The `title` can be a string or, recommended, a language reference.
1.  The `description` can be a string or, recommended, a language reference.
1.  The `group` can be one of the existing group identifiers or a new one.
1.  The `icon` can be one of the existing registered icon keys or a custom
    icon key registered in the [icon API](https://docs.typo3.org/permalink/t3coreapi:icon@13.4).

Any of these entries can be omitted. You **should** at
least define a title.

New content elements are usually added in extensions in file
`EXT:my_extension/Configuration/Overrides/tt_content.php`.

The following groups are available by default:

-   **default**

    <!-- TODO: no Markdown rendering for "versionchanged" -->

    Default group for commonly used content elements

-   **forms**

    Content elements representing forms like a contact form or a login form

lists

-   **menu**

    Menus that can be inserted as content elements like a sitemap or a menu
    of all subpages.

-   **plugins**

    Plugins provided by extensions

-   **special**

    Content elements that are used of special cases

All content element groups are listed in
`$GLOBALS['TCA']['tt_content']['columns']['CType']['config']['itemGroups']` you can
debug them in the TYPO3 backend using the backend module
**System > Configuration** if [`typo3/cms-lowlevel`](https://packagist.org/packages/typo3/cms-lowlevel) is installed
and you are an administrator.

Some third party extensions like [`bk2k/bootstrap-package`](https://packagist.org/packages/bk2k/bootstrap-package) are altering
the available groups.

## Plain content elements or plugins {#content-element-wizard-plain}

You can add a content element or plain plugin (no Extbase) using method
[ExtensionManagementUtility::addPlugin()](https://api.typo3.org/main/classes/TYPO3-CMS-Core-Utility-ExtensionManagementUtility.html#method_addPlugin):
of class `\TYPO3\CMS\Core\Utility\ExtensionManagementUtility`.

**EXT:my_extension/Configuration/Overrides/tt_content.php**

```php
<?php

declare(strict_types=1);

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addPlugin(
  [
    'label' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:myextension_myplugin_title',
    'value' => 'myextension_myplugin',
    'icon' => 'content-text',
    'group' => 'plugins',
    'description' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:myextension_myplugin_description',
  ],
  'CType',
  'my_extension',
);

```

The key `value` in the parameter `$itemArray` is used as key of the newly added
content element representing the plugin.

When you are using `CType` for parameter `$type` the content
element is added to the select item list of column `CType` in table `tt_content`.

<!-- TODO: no Markdown rendering for "deprecated" -->

Using the default list_type for the parameter is deprecated. All content
elements and plugins should be added with string CType for parameter $type.

This method supplies some default values:

-   **`group`**

    Defaults to `default`

-   **`icon`**

    Icon of the extension if defined

While it is still possible to use
[ExtensionManagementUtility::addTcaSelectItem()](https://api.typo3.org/main/classes/TYPO3-CMS-Core-Utility-ExtensionManagementUtility.html#method_addTcaSelectItem)
as is commonly seen in older extensions this method is not specific to content
elements and therefore sets not default values for group and icon.

## Plugins (Extbase) in the "New Content Element" wizard {#content-element-wizard-extbase}

To add an Extbase plugin you can use `ExtensionUtility::registerPlugin`
of class `\TYPO3\CMS\Extbase\Utility\ExtensionUtility`.

This method is only available for Extbase plugins defined via
`ExtensionUtility::configurePlugin` in file [`EXT:my_extension/ext_localconf.php`](../../ExtensionArchitecture/FileStructure/ExtLocalconf.md#file-extension-ext-localconf-php)

**EXT:my_extension/Configuration/Overrides/tt_content.php**

```php
<?php

declare(strict_types=1);

use TYPO3\CMS\Extbase\Utility\ExtensionUtility;

defined('TYPO3') or die();

ExtensionUtility::registerPlugin(
  'my_extension',
  'MyPlugin',
  'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:myextension_myplugin_title',
  'myextension_myplugin',
  'plugins',
  'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:myextension_myplugin_description',
);

```

## Override the wizard with page TSconfig {#content-element-wizard-page-tsconfig}

The TCA is always set globally for the complete TYPO3 installation. If you have
a multi-site installation and want to alter the appearance of content elements
in the wizard or remove certain content elements this can be done via
[page TSconfig](https://docs.typo3.org/m/typo3/reference-typoscript/13.4/en-us/UsingSettingTSconfig/PageTSconfig.html#setting-page-tsconfig).
This is commonly done on a per site basis so you can use the [Site set page TSconfig provider](https://docs.typo3.org/permalink/t3coreapi:site-sets-page-tsconfig@13.4)
in your [site package](https://docs.typo3.org/permalink/t3coreapi:site-package@13.4).

You can use the settings of [newContentElement.wizardItems](https://docs.typo3.org/m/typo3/reference-typoscript/13.4/en-us/PageTsconfig/Mod/Wizards.html#pagenewcontentelementwizard).

### Remove items from the "New Content Element" wizard {#content-element-wizard-page-tsconfig-remove}

Using [\[group\].removeItems](https://docs.typo3.org/m/typo3/reference-typoscript/13.4/en-us/PageTsconfig/Mod/Wizards.html#confval-mod-wizards-newcontentelement-wizarditems-group-removeitems)
you can remove a content element type from the wizard.

**EXT:my_sitepackage/Configuration/Sets/MySet/page.tsconfig**

```typoscript
mod.wizards.newContentElement.wizardItems {
  special.removeItems := addToList(html)
}

```

This removes the content element "Plain HTML" from the group `special`.

> [!NOTE]
> The affected content elements are only removed from the specified group and
> only in the wizard. Editors can still switch the `CType` selector to create
> such a content element. The content element might also appear in another tab.
>
> Use [User settings configuration](https://docs.typo3.org/permalink/t3coreapi:user-settings@13.4) to effectively ban
> usage for non-admin users.

You can also remove whole groups of content elements from the wizard:

**EXT:my_sitepackage/Configuration/Sets/MySet/page.tsconfig**

```typoscript
# This will remove the "menu" group
mod.wizards.newContentElement.wizardItems.removeItems := addToList(menu)

```

### Change title, description, icon and default values in the wizard {#content-element-wizard-page-tsconfig-change}

You can use the following page tsconfig properties to change the display
of the element in the wizard:

-   [iconIdentifier](https://docs.typo3.org/m/typo3/reference-typoscript/13.4/en-us/PageTsconfig/Mod/Wizards.html#confval-mod-wizards-newcontentelement-wizarditems-group-elements-name-iconidentifier)
-   [iconOverlay](https://docs.typo3.org/m/typo3/reference-typoscript/13.4/en-us/PageTsconfig/Mod/Wizards.html#confval-mod-wizards-newcontentelement-wizarditems-group-elements-name-iconoverlay)
-   [title](https://docs.typo3.org/m/typo3/reference-typoscript/13.4/en-us/PageTsconfig/Mod/Wizards.html#confval-mod-wizards-newcontentelement-wizarditems-group-elements-name-title)
-   [description](https://docs.typo3.org/m/typo3/reference-typoscript/13.4/en-us/PageTsconfig/Mod/Wizards.html#confval-mod-wizards-newcontentelement-wizarditems-group-elements-name-description)
-   [tt_content_defValues](https://docs.typo3.org/m/typo3/reference-typoscript/13.4/en-us/PageTsconfig/Mod/Wizards.html#confval-mod-wizards-newcontentelement-wizarditems-group-elements-name-tt-content-defvalues)
-   [saveAndClose](https://docs.typo3.org/m/typo3/reference-typoscript/13.4/en-us/PageTsconfig/Mod/Wizards.html#confval-mod-wizards-newcontentelement-wizarditems-group-elements-name-saveandclose)

**EXT:my_sitepackage/Configuration/Sets/MySet/page.tsconfig**

```typoscript
mod.wizards.newContentElement.wizardItems {
  special.html {
    title = Plain HTML(use with care!!)
    description (
      Attention: This HTML is output unsanized! The editor is responsible
      to only use safe HTML content.
    )
    icon = mysitepackage_htmlattention
  }
}

```

## Register a new group in the "New Content Element" wizard {#content-element-wizard-create-group}

New groups are added on the fly, however it is recommended to set a localized
header:

**EXT:my_extension/Configuration/Overrides/tt_content.php**

```php
<?php

declare(strict_types=1);

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
use TYPO3\CMS\Extbase\Utility\ExtensionUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTcaSelectItemGroup(
  'tt_content',
  'CType',
  'myextension_myplugingroup',
  'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:myextension_myplugin.group',
);

ExtensionUtility::registerPlugin(
  'my_extension',
  'MyPlugin',
  'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:myextension_myplugin_title',
  'myextension_myplugin',
  'myextension_myplugingroup',
  'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:myextension_myplugin_description',
);

```

The headers can also be overrriden on a per site basis using page TSconfig.

**EXT:my_sitepackage/Configuration/Sets/MySet/page.tsconfig**

```typoscript
mod.wizards.newContentElement.wizardItems {
  mygroup.header = LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:mygroup.header
}

```

## Content elements compatible with TYPO3 v12.4 and v13 {#content-element-wizard-v12}

If your extension supplies content elements or plugins and supports both TYPO3
v12.4 and v13 you can keep the [Page TsConfig for the New Content Element
Wizard](https://docs.typo3.org/m/typo3/reference-coreapi/12.4/en-us/ApiOverview/ContentElements/ContentElementsWizard.html#content-element-wizard) while you additionally supply
the TCA settings for TYPO3 v13.

You should use the same content element group for both definition ways or
the content element will be displayed twice, once in each group. Group `common`
is automatically migrated to `default` for TYPO3 v13.