---
title: "New content element wizard"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:content-element-wizard@main"
source: "ApiOverview/ContentElements/ContentElementsWizard.rst"
modified: "2026-09-16T13:05:25+00:00"
---

# New content element wizard

**Table of contents**

-   [Plain content elements or plugins](https://docs.typo3.org/permalink/t3coreapi:plain-content-elements-or-plugins@main)
-   [Plugins (Extbase) in the "New Content Element" wizard](https://docs.typo3.org/permalink/t3coreapi:plugins-extbase-in-the-new-content-element-wizard@main)
-   [Override the wizard with page TSconfig](https://docs.typo3.org/permalink/t3coreapi:override-the-wizard-with-page-tsconfig@main)
-   [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@main)

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@main).

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**

    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

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' => 'my_extension.messages:myextension_myplugin_title',
    'value' => 'myextension_myplugin',
    'icon' => 'content-text',
    'group' => 'plugin',
    'description' => 'my_extension.messages:myextension_myplugin_description',
  ],
);

```

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

> [!NOTE]
> **Changed in version 14.0**
>
> The method's second and third parameter have been dropped. This method can
> only be used with the field `CType` of table `tt_content`.

This method supplies some default values:

-   **`group`**

    Defaults to `plugins`

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

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

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',
  'my_extension.messages:myextension_myplugin_title',
  'myextension_myplugin',
  'plugins',
  'my_extension.messages:myextension_myplugin_description',
);

```

## Override the wizard with 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/main/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@main)
in your [site package](https://docs.typo3.org/permalink/t3coreapi:site-package@main).

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

### Remove items from the "New Content Element" wizard

Using [\[group\].removeItems](https://docs.typo3.org/m/typo3/reference-typoscript/main/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@main) 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

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/main/en-us/PageTsconfig/Mod/Wizards.html#confval-mod-wizards-newcontentelement-wizarditems-group-elements-name-iconidentifier)
-   [iconOverlay](https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/PageTsconfig/Mod/Wizards.html#confval-mod-wizards-newcontentelement-wizarditems-group-elements-name-iconoverlay)
-   [title](https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/PageTsconfig/Mod/Wizards.html#confval-mod-wizards-newcontentelement-wizarditems-group-elements-name-title)
-   [description](https://docs.typo3.org/m/typo3/reference-typoscript/main/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/main/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/main/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

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',
  'my_extension.messages:myextension_myplugin.group',
);

ExtensionUtility::registerPlugin(
  'my_extension',
  'MyPlugin',
  'my_extension.messages:myextension_myplugin_title',
  'myextension_myplugin',
  'myextension_myplugingroup',
  'my_extension.messages:myextension_myplugin_description',
);

```

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

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

```typoscript
mod.wizards.newContentElement.wizardItems {
  mygroup.header = my_extension.messages:mygroup.header
}

```