---
title: "Feature: #91008 - Item grouping for TCA select items"
manual: "TYPO3 Core Changelog"
version: "main"
permalink: "https://docs.typo3.org/permalink/changelog:changelog-feature-91008-itemgroupingfortcaselectitems"
source: "Changelog/10.4/Feature-91008-ItemGroupingForTCASelectItems.rst"
typo3-version: "10.4"
typo3-major: 10
type: "feature"
issue: 91008
forge: "https://forge.typo3.org/issues/91008"
tags: ["TCA", "ext:core"]
rendered: "2026-09-20T18:31:11+00:00"
---

# Feature: #91008 - Item grouping for TCA select items {#changelog-feature-91008-itemgroupingfortcaselectitems}

See [forge#91008](https://forge.typo3.org/issues/91008)

## Description {#description}

The TCA column type `select` now has a clean API to group items for dropdowns
in FormEngine. This was previously handled via placeholder `--div--` items,
which then rendered as `<optgroup>` HTML elements in a dropdown.

In larger installations or TYPO3 instances with lots of extensions, Plugins
(`tt_content.list_type`), Content Types (`tt_content.CType`) or custom
Page Types (`pages.doktype`) drop down lists could grow large and adding item groups
caused tedious work for developers or integrators.
Grouping can now be configured on a per-item
basis. Custom groups can be added via an API or when defining TCA for a new table.

### Adding Custom Select Item Groups {#adding-custom-select-item-groups}

Registration of a select item group takes place in `Configuration/TCA/tx_mytable.php`
for new TCA tables, and in `Configuration/TCA/Overrides/a_random_core_table.php`
for modifying an existing TCA definition.

The following two examples illustrate adding a new group to a field of
type "select":

```php
ExtensionManagementUtility::addTcaSelectItemGroup(
    'tt_content',
    'CType',
    'sliders',
    'LLL:EXT:my_slider_mixtape/Resources/Private/Language/locallang_tca.xlf:tt_content.group.sliders',
    'after:lists'
);
```

The TCA for `tt_content.CType` column configuration looks like this now:

```php
'items' => ...
'itemGroups' => [
    'default' => 'LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xlf:CType.div.standard',
    'lists' => 'LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xlf:CType.div.lists',
    'sliders' => 'LLL:EXT:my_slider_mixtape/Resources/Private/Language/locallang_tca.xlf:tt_content.group.sliders',
    'menu' => 'LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xlf:CType.div.menu',
    'forms' => 'LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xlf:CType.div.forms',
    'special' => 'LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xlf:CType.div.special',
 ],
```

When adding a new select field, itemGroups should be added directly in the
original TCA definition without using the API method. Use the API within
`TCA/Configuration/Overrides/` files to extend an existing TCA select field with
grouping.

### Attaching Select Items to Item Groups {#attaching-select-items-to-item-groups}

A select item now has a fourth array key to define a "Group ID" which group it
belongs to. In the example above, the group ID is named "sliders" and used
in the examples below to attach items to this group.

Grouping for select items can be used via API or in TCA configuration directly.

This is the example for a custom Content Type "slickslider" belonging to the
group from above:

```php
'items' => [
    ...,
    [
        // Label
        'LLL:EXT:my_slider_mixtape/Resources/Private/Locallang/locallang_tca.xlf:tt_content.CType.slickslider',
        // Value written to the database
        'slickslider',
        // Icon for the dropdown
        'EXT:my_slider_mixtape/Resources/Public/Icons/slickslider.png',
        // The group ID, if not given, falls back to "none" or the last used --div-- in the item array
        'sliders'
    ],
]
```

The item can be added via API like this:

```php
ExtensionManagementUtility::addTcaSelectItem(
    'tt_content',
    'CType',
    [
        'LLL:EXT:my_slider_mixtape/Resources/Private/Locallang/locallang_tca.xlf:tt_content.CType.slickslider',
        'slickslider',
        'EXT:my_slider_mixtape/Resources/Public/Icons/slickslider.png',
        'sliders'
    ]
);
```

The same approach applies to `ExtensionManagementUtility::addPlugin()` when
adding pi-based plugins.

When adding Extbase plugins, the API method now allows to specify a group ID
directly as additional parameter. This falls back to the "default" group ID,
which is available in `tt_content.CType` and `tt_content.list_type`.

```php
ExtensionUtility::registerPlugin(
    // Extension key
    'my_slider_mixtape',
    // Plugin value
    'slider_from_records',
    // Plugin label
    'LLL:EXT:my_slider_mixtape/Resources/Private/Locallang/locallang_tca.xlf:tt_content.plugin.slider_from_records',
    // Icon for plugin
    'EXT:my_slider_mixtape/Resources/Public/Icons/slickslider.png',
    // Group ID
    'sliders'
);
```

## Impact {#impact}

By default, Page Types (`pages.doktype`), Content Types (`tt_content.CType`) and
Plugins (`tt_content.list_type`) now have native grouping enabled.

The order of the `itemGroups` value is important when using groups, as this
is the order of the groups rendered in the dropdown of FormEngine.

The API methods can be used to build more groups without juggling with
TCA arrays.

It is possible now, and encouraged to remove the `--div--` items in custom
selects and use itemGroups instead. TYPO3 Core keeps the `--div--` for
backwards-compatible reasons in TYPO3 v10, but all items of the fields mentioned
above the grouping parameter has been added already.

Please note that this `--div--` is related to select items, and not the
"showItem" definition which fields should be shown.

Currently Item Groups are used in FormEngine DropDowns / single-select items
from TYPO3 Core, but can be used in multi-select fields as well.