selectSingle 

Single select fields display a select field from which only one value can be chosen.

The according database field is generated automatically.

The renderType selectSingle creates a drop-down box with items to select a single value. Only if size is set to a value greater than one, a box is rendered containing all selectable elements from which one can be chosen.

Table of contents:

Examples for select fields with renderType selectSingle 

Simple select drop down with static and database values 

The location of a conference

The location of a conference

EXT:my_extension/Configuration/TCA/Overrides/110-tx_myextension_conference-location.php 
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'location' => [
    'label' => 'my_extension.db:conference.location',
    'config' => [
      'type' => 'select',
      'renderType' => 'selectSingle',
      'foreign_table' => 'tx_myextension_location',
      'items' => [
        ['label' => '', 'value' => 0],
      ],
      'fieldWizard' => [
        'selectIcons' => [
          'disabled' => false,
        ],
      ],
      'relationship' => 'manyToOne',
      // Venues only, not their halls
      'foreign_table_where' => 'AND {#tx_myextension_location}.{#parent} = 0 ORDER BY tx_myextension_location.name',
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  'location',
  '',
  'after:conference_date',
);
Copied!

Select foreign rows with icons 

The location of a conference, with the images of the locations

The location of a conference, with the images of the locations

EXT:my_extension/Configuration/TCA/Overrides/110-tx_myextension_conference-location.php 
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'location' => [
    'label' => 'my_extension.db:conference.location',
    'config' => [
      'type' => 'select',
      'renderType' => 'selectSingle',
      'foreign_table' => 'tx_myextension_location',
      'items' => [
        ['label' => '', 'value' => 0],
      ],
      'fieldWizard' => [
        'selectIcons' => [
          'disabled' => false,
        ],
      ],
      'relationship' => 'manyToOne',
      // Venues only, not their halls
      'foreign_table_where' => 'AND {#tx_myextension_location}.{#parent} = 0 ORDER BY tx_myextension_location.name',
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  'location',
  '',
  'after:conference_date',
);
Copied!

Select a single value from a list of elements 

'size' => 6,
Copied!

Properties of the TCA column type select with renderType selectSingle 

Name Type Scope
allowNonIdValues
 boolean Proc.
authMode
 string (keyword) Display / Proc.
autoSizeMax
 integer Display
behaviour
allowLanguageSynchronization
 boolean Proc.
dbFieldLength
 integer Proc.
default
 string Display / Proc.
disableNoMatchingValueElement
 boolean Display
fieldControl
fieldInformation
fieldWizard
defaultLanguageDifferences
 array
localizationStateSelector
 array
otherLanguageContent
 array
selectIcons
 array Display
fileFolderConfig
allowedExtensions
 string Display / Proc.
depth
 integer Display / Proc.
folder
 string Display / Proc.
foreign_table
 string (table name) Display / Proc.
foreign_table_item_group
 string (column name) Display / Proc.
foreign_table_prefix
 plain text label or label reference Display
foreign_table_where
 string (SQL WHERE) Display / Proc.
itemGroups
 array Display / Proc.
items
 array Display / Proc.
itemsProcessors
 array Display / Proc.
itemsProcFunc
 string (class->method reference) Display / Proc.
maxitems
 integer > 0 Display / Proc.
minitems
 integer > 0 Display
MM
 string (table name) Proc.
MM_match_fields
 array Display / Proc.
MM_opposite_field
 string (field name) Proc.
MM_oppositeUsage
 array Proc.
MM_table_where
 string (SQL WHERE) Proc.
multiple
 boolean Display / Proc.
readOnly
 boolean Display
relationship
 string Proc.
showIfEmpty
 boolean Display
size
 integer Display
sortItems
 array Display
allowNonIdValues
Type
boolean
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['allowNonIdValues']
Scope
Proc.
RenderType
all

Only useful if foreign_table is enabled.

If set, then values which are not integer ids will be allowed. May be needed if you use itemsProcFunc or enter additional items in the items array to produce some string-value elements for the list.

authMode
Type
string (keyword)
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['authMode']
Scope
Display / Proc.
RenderType
all

Authorization mode for the selector box. The only possible option is:

explicitAllow
All static values from the "items" array of the selector box will be added to a matrix in the backend user configuration where a value must be explicitly selected if a user (other than admin) is allowed to use it!)
autoSizeMax
Type
integer
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['autoSizeMax']
Scope
Display

The maximum size (height) of the select field.

The size of the select field will be automatically adjusted based on the number of selected items. The select field will never be smaller than the specified size and never larger than the value of autoSizeMax.

behaviour
allowLanguageSynchronization
Type
boolean
Default
false
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['behaviour']['allowLanguageSynchronization']
Scope
Proc.

Allows an editor to select in a localized record whether the value is copied over from default or source language record, or if the field has an own value in the localization. If set to true and if the table supports localization and if a localized record is edited, this setting enables FieldWizard LocalizationStateSelector: Two or three radio buttons shown below the field input. The state of this is stored in a json encoded array in the database table called l10n_state. It tells the DataHandler which fields of the localization records should be kept in sync if the underlying default or source record changes.

EXT:my_extension/Configuration/TCA/Overrides/121-tx_myextension_conference-timezone.php 
<?php

use MyVendor\MyExtension\Backend\ItemsProcessor\TimezoneItemsProcessor;
use MyVendor\MyExtension\Backend\TimezoneSorter;
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'timezone' => [
    'label' => 'my_extension.db:conference.timezone',
    'config' => [
      'type' => 'select',
      'renderType' => 'selectSingle',
      'items' => [
        ['label' => '', 'value' => ''],
      ],
      'itemsProcessors' => [
        100 => [
          'class' => TimezoneItemsProcessor::class,
          'parameters' => [
            'regions' => 'Europe,America',
          ],
        ],
      ],
      'itemGroups' => [
        'Europe' => 'my_extension.db:conference.timezone.europe',
        'America' => 'my_extension.db:conference.timezone.america',
      ],
      'sortItems' => [
        'label' => 'asc',
        // Then by the offset to UTC, the time zones with the same offset
        // stay sorted by label
        'offset' => TimezoneSorter::class . '->sortByOffset',
      ],
      'dbFieldLength' => 64,
      'behaviour' => [
        'allowLanguageSynchronization' => true,
      ],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  'timezone',
  '',
  'after:location',
);
Copied!
dbFieldLength
Type
integer
Default
255
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['dbFieldLength']
Scope
Proc.

New in version 13.0

The TCA config option dbFieldLength contains an integer value that is applied to varchar fields (not text ) and defines the length of the database field. It will not be respected for fields that resolve to an integer type. Developers who wish to optimize field length can use dbFieldLength for type=select fields to increase or decrease the default length.

Example: A shorter column for the identifier of a time zone
EXT:my_extension/Configuration/TCA/Overrides/121-tx_myextension_conference-timezone.php 
<?php

use MyVendor\MyExtension\Backend\ItemsProcessor\TimezoneItemsProcessor;
use MyVendor\MyExtension\Backend\TimezoneSorter;
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'timezone' => [
    'label' => 'my_extension.db:conference.timezone',
    'config' => [
      'type' => 'select',
      'renderType' => 'selectSingle',
      'items' => [
        ['label' => '', 'value' => ''],
      ],
      'itemsProcessors' => [
        100 => [
          'class' => TimezoneItemsProcessor::class,
          'parameters' => [
            'regions' => 'Europe,America',
          ],
        ],
      ],
      'itemGroups' => [
        'Europe' => 'my_extension.db:conference.timezone.europe',
        'America' => 'my_extension.db:conference.timezone.america',
      ],
      'sortItems' => [
        'label' => 'asc',
        // Then by the offset to UTC, the time zones with the same offset
        // stay sorted by label
        'offset' => TimezoneSorter::class . '->sortByOffset',
      ],
      'dbFieldLength' => 64,
      'behaviour' => [
        'allowLanguageSynchronization' => true,
      ],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  'timezone',
  '',
  'after:location',
);
Copied!
default
Type
string
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['default']
Scope
Display / Proc.
RenderType
all

Default value set if a new record is created. If empty, the first element in the items array is selected.

disableNoMatchingValueElement
Type
boolean
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['disableNoMatchingValueElement']
Scope
Display
RenderType
all

If set, then no element is inserted if the current value does not match any of the existing elements. A corresponding options is also found in Page TSconfig.

fieldControl

For details see fieldControl.

fieldInformation

For details see fieldInformation.

fieldWizard
defaultLanguageDifferences
Type
array
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['defaultLanguageDifferences']

For details see defaultLanguageDifferences.

localizationStateSelector
Type
array
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['localizationStateSelector']

For details see localizationStateSelector.

otherLanguageContent
Type
array
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['otherLanguageContent']

For details see otherLanguageContent.

selectIcons
Type
array
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['selectIcons']
Scope
Display

Render thumbnails of icons below the select drop-down. Disabled by default.

fileFolderConfig
allowedExtensions
Type
string
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fileFolderConfig']['allowedExtensions']
Scope
Display / Proc.

List of file extensions to select. If blank, all files are selected. Specify list in lowercase.

This configuration can be overridden by Page TSconfig.

depth
Type
integer
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fileFolderConfig']['depth']
Scope
Display / Proc.
RenderType
all

Depth of directory recursions. Default is 99. Specify in range from 0-99. 0 (zero) means no recursion into subdirectories. Only useful in combination with property folder.

This configuration can be overridden by Page TSconfig.

folder
Type
string
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fileFolderConfig']['folder']
Scope
Display / Proc.

Specifying a folder from where files are added to the item array.

Specify the folder relative to the \TYPO3\CMS\Core\Core\Environment::getPublicPath() . See getPublicPath() . Alternatively use the prefix "EXT:" to point to an extension folder.

Files from the folder are selected recursively to the level specified by depth and only files of the extensions defined by allowedExtensions are listed in the select box.

Only the file reference relative to the folder is stored.

If the files are images (gif,png,jpg) they will be configured as icons (third parameter in items array).

This configuration can be overridden by Page TSconfig.

Examples: Select SVGs recursively from a folder
A marker icon from a folder

A marker icon from a folder

EXT:my_extension/Configuration/TCA/Overrides/440-tx_myextension_location-marker.php 
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_location', [
  'marker' => [
    'label' => 'my_extension.db:location.marker',
    'config' => [
      'type' => 'select',
      'renderType' => 'selectSingle',
      'items' => [
        ['label' => '', 'value' => ''],
      ],
      'fileFolderConfig' => [
        'folder' => 'EXT:my_extension/Resources/Public/Icons/Markers/',
        'allowedExtensions' => 'svg',
        'depth' => 0,
      ],
      'fieldWizard' => [
        'selectIcons' => [
          'disabled' => false,
        ],
      ],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_location',
  'marker',
  '',
  'after:image',
);
Copied!
foreign_table
Type
string (table name)
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['foreign_table']
Scope
Display / Proc.
RenderType
all

The item-array will be filled with records from the table defined here. The table must have a TCA definition.

The uids of the chosen records will be saved in a comma separated list by default.

Use property MM to store the values in an intermediate MM table instead.

Example: Select single field with enabled selectIcons
The location of a conference, with the images of the locations

The location of a conference, with the images of the locations

EXT:my_extension/Configuration/TCA/Overrides/110-tx_myextension_conference-location.php 
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'location' => [
    'label' => 'my_extension.db:conference.location',
    'config' => [
      'type' => 'select',
      'renderType' => 'selectSingle',
      'foreign_table' => 'tx_myextension_location',
      'items' => [
        ['label' => '', 'value' => 0],
      ],
      'fieldWizard' => [
        'selectIcons' => [
          'disabled' => false,
        ],
      ],
      'relationship' => 'manyToOne',
      // Venues only, not their halls
      'foreign_table_where' => 'AND {#tx_myextension_location}.{#parent} = 0 ORDER BY tx_myextension_location.name',
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  'location',
  '',
  'after:conference_date',
);
Copied!
Example: Select field with foreign table via MM table
The speakers of a conference

The speakers of a conference

EXT:my_extension/Configuration/TCA/Overrides/125-tx_myextension_conference-speakers.php 
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'speakers' => [
    'label' => 'my_extension.db:conference.speakers',
    'config' => [
      'type' => 'select',
      'renderType' => 'selectMultipleSideBySide',
      'foreign_table' => 'tx_myextension_speaker',
      'MM' => 'tx_myextension_conference_speaker_mm',
      // Speakers in the default language, not their translations
      'foreign_table_where' => 'AND {#tx_myextension_speaker}.{#sys_language_uid} IN (-1, 0) ORDER BY tx_myextension_speaker.name',
      'size' => 5,
      'autoSizeMax' => 20,
      'fieldControl' => [
        'editPopup' => [
          'disabled' => false,
          'options' => [
            'title' => 'my_extension.db:conference.speakers.edit',
          ],
        ],
        'addRecord' => [
          'disabled' => false,
          'options' => [
            'title' => 'my_extension.db:conference.speakers.add',
            // A new speaker comes first in the list of selected speakers
            'setValue' => 'prepend',
          ],
        ],
        'listModule' => [
          'disabled' => false,
          'options' => [
            'title' => 'my_extension.db:conference.speakers.list',
          ],
        ],
      ],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  'speakers',
  '',
  'before:--div--;my_extension.db:tab.details',
);
Copied!
foreign_table_item_group
Type
string (column name)
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['foreign_table_item_group']
Scope
Display / Proc.
RenderType
all
Added
13.0

This property references a specific field in the foreign table, which holds an item group identifier.

Example: A select field with a foreign_table_item_group
EXT:my_extension/Configuration/TCA/Overrides/297-tx_myextension_talk-sponsor.php 
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_talk', [
  'sponsor' => [
    'label' => 'my_extension.db:talk.sponsor',
    'config' => [
      'type' => 'select',
      'renderType' => 'selectSingle',
      'items' => [
        ['label' => '', 'value' => 0],
      ],
      'foreign_table' => 'tx_myextension_sponsor',
      // The tier of a sponsor is the group of its item
      'foreign_table_item_group' => 'tier',
      'itemGroups' => [
        'gold' => 'my_extension.db:sponsor.tier.gold',
        'silver' => 'my_extension.db:sponsor.tier.silver',
        'bronze' => 'my_extension.db:sponsor.tier.bronze',
      ],
      'relationship' => 'manyToOne',
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_talk',
  'sponsor',
  '',
  'after:speaker',
);
Copied!
foreign_table_prefix
Type
plain text label or label reference
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['foreign_table_prefix']
Scope
Display
RenderType
all

Label prefix to the title of the records from the foreign-table.

Example: Select single field with foreign_prefix and foreign_where
The location of a conference

The location of a conference

'foreign_table_prefix' => 'Venue: ',
Copied!
foreign_table_where
Type
string (SQL WHERE)
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['foreign_table_where']
Scope
Display / Proc.
RenderType
all

The items from foreign_table are selected with this WHERE clause. The WHERE clause is effectively appended to the existing WHERE clause (which contains default constraints, such as NOT deleted ) and must begin with AND .

Field quoting

The example below uses the special field quoting syntax {#...} around identifiers to be as DBAL-compatible as possible. Note that ORDER BY and GROUP BY should NOT be quoted, since they always receive proper quoting automatically through the API.

Markers inside the WHERE statement

It is possible to use markers in the WHERE clause:

###REC_FIELD_[field name]###

Any field of the current record.

###THIS_UID###
Current element uid (zero if new).
###CURRENT_PID###
The current page id (pid of the record).

###SITEROOT###

###PAGE_TSCONFIG_ID###
A value you can set from Page TSconfig dynamically.
###PAGE_TSCONFIG_IDLIST###
A value you can set from Page TSconfig dynamically.
###PAGE_TSCONFIG_STR###
A value you can set from Page TSconfig dynamically.
###SITE:<KEY>.<SUBKEY>###
A value from the site configuration, for example: ###SITE:mySetting.categoryPid### or ###SITE:rootPageId###. Also values of extension configuration settings are possible. E.g. if there is settings.sitepackage.imprintPageUid defined in EXT:my_sitepackage/Configuration/Sets/Main/settings.definitions.yaml and set in config/sites/mysite/settings.yaml: ###SITE:settings.sitepackage.imprintPageUid###

The markers are preprocessed so that the value of CURRENT_PID and PAGE_TSCONFIG_ID are always integers (default is zero), PAGE_TSCONFIG_IDLIST will always be a comma-separated list of integers (default is zero) and PAGE_TSCONFIG_STR will be quoted before substitution (default is blank string).

More information about markers set by Page TSconfig can be found in the TSconfig reference.

Example: Select single field with foreign_prefix and foreign_where
The location of a conference

The location of a conference

EXT:my_extension/Configuration/TCA/Overrides/110-tx_myextension_conference-location.php 
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'location' => [
    'label' => 'my_extension.db:conference.location',
    'config' => [
      'type' => 'select',
      'renderType' => 'selectSingle',
      'foreign_table' => 'tx_myextension_location',
      'items' => [
        ['label' => '', 'value' => 0],
      ],
      'fieldWizard' => [
        'selectIcons' => [
          'disabled' => false,
        ],
      ],
      'relationship' => 'manyToOne',
      // Venues only, not their halls
      'foreign_table_where' => 'AND {#tx_myextension_location}.{#parent} = 0 ORDER BY tx_myextension_location.name',
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  'location',
  '',
  'after:conference_date',
);
Copied!
itemGroups
Type
array
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['itemGroups']
Scope
Display / Proc.
RenderType
all

Contains an array of key-value pairs. The key contains the id of the item group, the value contains the label of the item group or its language reference.

Only groups containing items will be displayed. In the select field first all items with no group defined are listed then the item groups in the order of their definition, each group with the corresponding items.

Item groups are rendered as <optgroup> .

Item groups can also be defined for items in foreign tables.

See also item group API methods

Example: SelectSingle field with itemGroups
The audience of a talk in two groups

The audience of a talk in two groups

EXT:my_extension/Configuration/TCA/Overrides/265-tx_myextension_talk-audience.php 
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_talk', [
  'audience' => [
    'label' => 'my_extension.db:talk.audience',
    'config' => [
      'type' => 'select',
      'renderType' => 'selectSingleBox',
      'items' => [
        ['label' => 'my_extension.db:talk.audience.developers', 'value' => 'developers', 'group' => 'technical'],
        ['label' => 'my_extension.db:talk.audience.integrators', 'value' => 'integrators', 'group' => 'technical'],
        ['label' => 'my_extension.db:talk.audience.editors', 'value' => 'editors', 'group' => 'business'],
        ['label' => 'my_extension.db:talk.audience.decision_makers', 'value' => 'decision_makers', 'group' => 'business'],
      ],
      'itemGroups' => [
        'technical' => 'my_extension.db:talk.audience.technical',
        'business' => 'my_extension.db:talk.audience.business',
      ],
      'behaviour' => [
        'allowLanguageSynchronization' => true,
      ],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_talk',
  'audience',
  '',
  'after:spoken_language',
);
Copied!
Example: SelectSingle field with itemGroups, size=6
The audience of a talk in two groups

The audience of a talk in two groups

EXT:my_extension/Configuration/TCA/Overrides/265-tx_myextension_talk-audience.php 
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_talk', [
  'audience' => [
    'label' => 'my_extension.db:talk.audience',
    'config' => [
      'type' => 'select',
      'renderType' => 'selectSingleBox',
      'items' => [
        ['label' => 'my_extension.db:talk.audience.developers', 'value' => 'developers', 'group' => 'technical'],
        ['label' => 'my_extension.db:talk.audience.integrators', 'value' => 'integrators', 'group' => 'technical'],
        ['label' => 'my_extension.db:talk.audience.editors', 'value' => 'editors', 'group' => 'business'],
        ['label' => 'my_extension.db:talk.audience.decision_makers', 'value' => 'decision_makers', 'group' => 'business'],
      ],
      'itemGroups' => [
        'technical' => 'my_extension.db:talk.audience.technical',
        'business' => 'my_extension.db:talk.audience.business',
      ],
      'behaviour' => [
        'allowLanguageSynchronization' => true,
      ],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_talk',
  'audience',
  '',
  'after:spoken_language',
);
Copied!
items
Type
array
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['items']
Scope
Display / Proc.
RenderType
all

Contains the elements for the selector box unless the property foreign_table or special has been set in which case automated values are set in addition to any values listed in this array.

Items registered for the field CType of table tt_content get automatically added to the New content element wizard. Settings from the items property can be overridden via page TSconfig newContentElement.wizardItems.

See also Add content elements to the Content Element Wizard.

Each element in this array is in itself an associative array.

label (plain text label or label reference)
The displayed title.
value (integer or string)

The value stored in the database.

  • The special value --div-- was used to insert a non-selectable
    value that appears as a divider label in the selector box. It is kept for backwards-compatible reasons. Use item groups for custom selects instead.
  • Values must not contain , (comma) and | (vertical bar). If you want to use authMode, you should
    also refrain from using : (colon).
icon (EXT: path or icon identifier)
Optional icon. For custom icons use a path prepended with EXT: to refer to an image file found inside an extension or use an registered icon identifier. If configured on the foreign_table, selicon-field is respected.
iconOverlay (icon identifier)

New in version 13.4.19

Optional overlay shown on top of the icon in the New content element wizard. Only used for items of the field CType of table tt_content. This replaces setting iconOverlay in page TSconfig newContentElement.wizardItems, which still works.

EXT:my_extension/Configuration/TCA/Overrides/610-tt_content-call_for_papers.php 
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

// Add the content element to the "Type" dropdown, with the predefined
// fields on the "General" tab
ExtensionManagementUtility::addRecordType(
  [
    'label' => 'my_extension.db:tt_content.call_for_papers',
    'value' => 'myextension_callforpapers',
    'icon' => 'content-text',
    // In the "New content element" wizard, the overlay shows that a call
    // for papers has a deadline
    'iconOverlay' => 'overlay-endtime',
    'group' => 'conference',
  ],
  '--palette--;;headers, bodytext',
);
Copied!
group (string)
The key of the item group.
description (string or array)
Fifth value is an optional description text. This is only shown when the list is shown with renderType='selectCheckBox'.
Example: Items with label and value
The salutation of a speaker

The salutation of a speaker

EXT:my_extension/Configuration/TCA/Overrides/305-tx_myextension_speaker-salutation.php 
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_speaker', [
  'salutation' => [
    'label' => 'my_extension.db:speaker.salutation',
    'config' => [
      'type' => 'select',
      'renderType' => 'selectSingle',
      'items' => [
        ['label' => '', 'value' => ''],
        [
          'label' => 'my_extension.db:speaker.salutation.mr',
          'value' => 'mr',
        ],
        [
          'label' => 'my_extension.db:speaker.salutation.ms',
          'value' => 'ms',
        ],
        [
          'label' => 'my_extension.db:speaker.salutation.mx',
          'value' => 'mx',
        ],
      ],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_speaker',
  'salutation',
  '',
  'before:name',
);
Copied!
Example: Items definition with label, value and icon

Each content element type is an item of the field CType of the table tt_content. The API method addRecordType() adds the item with a label, a value, and an icon:

EXT:my_extension/Configuration/TCA/Overrides/610-tt_content-call_for_papers.php 
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

// Add the content element to the "Type" dropdown, with the predefined
// fields on the "General" tab
ExtensionManagementUtility::addRecordType(
  [
    'label' => 'my_extension.db:tt_content.call_for_papers',
    'value' => 'myextension_callforpapers',
    'icon' => 'content-text',
    // In the "New content element" wizard, the overlay shows that a call
    // for papers has a deadline
    'iconOverlay' => 'overlay-endtime',
    'group' => 'conference',
  ],
  '--palette--;;headers, bodytext',
);
Copied!
Example: SelectSingle field with itemGroups

A select single field of size 6 with 3 item groups and one item without group.

The audience of a talk in two groups

The audience of a talk in two groups

EXT:my_extension/Configuration/TCA/Overrides/265-tx_myextension_talk-audience.php 
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_talk', [
  'audience' => [
    'label' => 'my_extension.db:talk.audience',
    'config' => [
      'type' => 'select',
      'renderType' => 'selectSingleBox',
      'items' => [
        ['label' => 'my_extension.db:talk.audience.developers', 'value' => 'developers', 'group' => 'technical'],
        ['label' => 'my_extension.db:talk.audience.integrators', 'value' => 'integrators', 'group' => 'technical'],
        ['label' => 'my_extension.db:talk.audience.editors', 'value' => 'editors', 'group' => 'business'],
        ['label' => 'my_extension.db:talk.audience.decision_makers', 'value' => 'decision_makers', 'group' => 'business'],
      ],
      'itemGroups' => [
        'technical' => 'my_extension.db:talk.audience.technical',
        'business' => 'my_extension.db:talk.audience.business',
      ],
      'behaviour' => [
        'allowLanguageSynchronization' => true,
      ],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_talk',
  'audience',
  '',
  'after:spoken_language',
);
Copied!
itemsProcessors
Type
array
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['itemsProcessors']
Scope
Display / Proc.
Added
14.0

An array indexed numerically. Each entry defines an item processor implementing ItemsProcessorInterface .

Item processors are executed sequentially based on their numerical array key. Each processor can add, modify, or remove items from the SelectItemCollection , influencing which items are ultimately displayed.

This option can be combined with itemsProcFunc. If both are configured, itemsProcFunc is executed first and itemsProcessors are executed afterwards.

EXT:my_extension/Configuration/TCA/Overrides/121-tx_myextension_conference-timezone.php 
<?php

use MyVendor\MyExtension\Backend\ItemsProcessor\TimezoneItemsProcessor;
use MyVendor\MyExtension\Backend\TimezoneSorter;
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'timezone' => [
    'label' => 'my_extension.db:conference.timezone',
    'config' => [
      'type' => 'select',
      'renderType' => 'selectSingle',
      'items' => [
        ['label' => '', 'value' => ''],
      ],
      'itemsProcessors' => [
        100 => [
          'class' => TimezoneItemsProcessor::class,
          'parameters' => [
            'regions' => 'Europe,America',
          ],
        ],
      ],
      'itemGroups' => [
        'Europe' => 'my_extension.db:conference.timezone.europe',
        'America' => 'my_extension.db:conference.timezone.america',
      ],
      'sortItems' => [
        'label' => 'asc',
        // Then by the offset to UTC, the time zones with the same offset
        // stay sorted by label
        'offset' => TimezoneSorter::class . '->sortByOffset',
      ],
      'dbFieldLength' => 64,
      'behaviour' => [
        'allowLanguageSynchronization' => true,
      ],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  'timezone',
  '',
  'after:location',
);
Copied!

For fields of type select, each SelectItem must be created with type: 'select' and must provide a label and a value. The value can be an integer or a string. Use the special value '--div--' to insert a divider (that cannot be selected).

You can also use any arguments supported by the items array, including group to group items and icon to display an icon with the item. Rendering the description is not supported.

EXT:my_extension/Classes/Backend/ItemsProcessor/TimezoneItemsProcessor.php 
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Backend\ItemsProcessor;

use TYPO3\CMS\Core\DataHandling\ItemsProcessorContext;
use TYPO3\CMS\Core\DataHandling\ItemsProcessorInterface;
use TYPO3\CMS\Core\Schema\Struct\SelectItem;
use TYPO3\CMS\Core\Schema\Struct\SelectItemCollection;

/**
 * Offers the time zones of the regions given in the parameter "regions",
 * grouped by region
 */
final readonly class TimezoneItemsProcessor implements ItemsProcessorInterface
{
  public function processItems(
    SelectItemCollection $items,
    ItemsProcessorContext $context,
  ): SelectItemCollection {
    $regions = explode(',', (string)($context->processorParameters['regions'] ?? 'Europe'));
    foreach (\DateTimeZone::listIdentifiers() as $identifier) {
      [$region, $city] = array_pad(explode('/', $identifier, 2), 2, '');
      if ($city === '' || !in_array($region, $regions, true)) {
        continue;
      }
      $items->add(new SelectItem(
        type: 'select',
        label: str_replace('_', ' ', $city),
        value: $identifier,
        group: $region,
      ));
    }
    return $items;
  }
}
Copied!

See also Item processor registration and implementation

itemsProcFunc
Type
string (class->method reference)
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['itemsProcFunc']
Scope
Display / Proc.

PHP method which is called to fill or manipulate the items array. See itemsProcFunc about details.

maxitems
Type
integer > 0
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['maxitems']
Scope
Display / Proc.

Maximum number of child items. Defaults to a high value. JavaScript record validation prevents the record from being saved if the limit is not satisfied.

minitems
Type
integer > 0
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['minitems']
Scope
Display

Minimum number of child items. Defaults to 0. JavaScript record validation prevents the record from being saved if the limit is not satisfied.

MM
Type
string (table name)
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['MM']
Scope
Proc.

This value contains the name of the table in which to store a MM relation. It is used together with foreign_table.

The database field with a MM property only stores the number of records in the relation.

Please have a look into the additional information in the MM common property description.

Example: Select field with foreign table via MM table
The speakers of a conference

The speakers of a conference

EXT:my_extension/Configuration/TCA/Overrides/125-tx_myextension_conference-speakers.php 
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'speakers' => [
    'label' => 'my_extension.db:conference.speakers',
    'config' => [
      'type' => 'select',
      'renderType' => 'selectMultipleSideBySide',
      'foreign_table' => 'tx_myextension_speaker',
      'MM' => 'tx_myextension_conference_speaker_mm',
      // Speakers in the default language, not their translations
      'foreign_table_where' => 'AND {#tx_myextension_speaker}.{#sys_language_uid} IN (-1, 0) ORDER BY tx_myextension_speaker.name',
      'size' => 5,
      'autoSizeMax' => 20,
      'fieldControl' => [
        'editPopup' => [
          'disabled' => false,
          'options' => [
            'title' => 'my_extension.db:conference.speakers.edit',
          ],
        ],
        'addRecord' => [
          'disabled' => false,
          'options' => [
            'title' => 'my_extension.db:conference.speakers.add',
            // A new speaker comes first in the list of selected speakers
            'setValue' => 'prepend',
          ],
        ],
        'listModule' => [
          'disabled' => false,
          'options' => [
            'title' => 'my_extension.db:conference.speakers.list',
          ],
        ],
      ],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  'speakers',
  '',
  'before:--div--;my_extension.db:tab.details',
);
Copied!
MM_match_fields
Type
array
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['MM_match_fields']
Scope
Display / Proc.

Array of field => value pairs to both insert and match against when writing/reading MM relations.

MM_opposite_field
Type
string (field name)
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['MM_opposite_field']
Scope
Proc.

If you want to make a MM relation editable from the foreign side (bidirectional) of the relation as well, you need to set MM_opposite_field on the foreign side to the field name on the local side.

For example, if the field companies.employees is your local side and you want to make the same relation editable from the foreign side of the relation in a field called persons.employers, you would need to set the MM_opposite_field value of the TCA configuration of the persons.employers field to the string "employees".

MM_oppositeUsage
Type
array
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['MM_oppositeUsage']
Scope
Proc.

In a MM bidirectional relation using match fields the opposite side needs to know about the match fields for certain operations (for example, when a copy is created in a workspace) so that relations are carried over with the correct information.

MM_oppositeUsage is an array which references which fields contain the references to the opposite side, so that they can be queried for match field configuration.

MM_table_where
Type
string (SQL WHERE)
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['MM_table_where']
Scope
Proc.

Additional where clause used when reading MM relations.

Example:

{#uid_local} = ###THIS_UID###
Copied!

The above example uses the special field quoting syntax {#...} around identifiers to be as DBAL-compatible as possible.

multiple
Type
boolean
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['multiple']
Scope
Display / Proc.

Allows the same item more than once in a list.

If used with bidirectional MM relations it must be set for both the native and foreign field configuration.

readOnly
Type
boolean
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['readOnly']
Scope
Display

Renders the field in a way that the user can see the value but cannot edit it.

relationship
Type
string
Default
manyToOne if foreign_table is set
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['relationship']
Scope
Proc.

New in version 13.3

Defines whether the field holds one related record or several, if it relates to records through foreign_table. This decides which value a Record object provides for this field, for example in a Fluid template.

oneToOne, manyToOne
The field provides a single Record object, or null if no record is selected. maxitems is set to 1 automatically, overriding any other value.
oneToMany
The field provides a LazyRecordCollection of Record objects.

A field with MM always provides a collection, whatever relationship says. Any other value, including manyToMany, throws an exception unless MM is set.

maxitems does not change the result the other way round: a field with oneToMany still provides a collection, even if maxitems is 1.

A select field without foreign_table has no relation. It provides an array of the selected values, or the single value for renderType => 'selectSingle'.

If relationship is not set and the field has a foreign_table, TYPO3 sets it to manyToOne, so the field provides a single record. With MM, it is set to manyToMany instead, and the field provides a collection.

showIfEmpty
Type
boolean
Default
false
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['showIfEmpty']
Scope
Display

Changed in version 14.2

Starting with TYPO3 14.2, relational fields are hidden when no selectable items are available. Option showIfEmpty will disable this behaviour.

By default, select fields and any render types are hidden when no select items are available. Setting showIfEmpty to true displays the field even if no options are available.

EXT:my_extension/Configuration/TCA/Overrides/pages.php 
$GLOBALS['TCA']['pages']['columns']['some_select_field']['config']['showIfEmpty'] = true;
Copied!

Possible reasons why no select items are available:

size
Type
integer
Default
1
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['size']
Scope
Display

If set to 1 (default), displays a select drop-down, else a select box of given size.

sortItems
Type
array
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['sortItems']
Scope
Display
RenderType
all

The property sortItems allows sorting of static select items by their values or labels.

Built-in orderings are to sort items by their labels or values. It is also possible to define custom sorting via PHP code.

When using grouped select fields with itemGroups, sorting happens on a per-group basis - all items within one group are sorted - as the group ordering is preserved.

Example: Sort items by label
The time zone of a conference

The time zone of a conference

EXT:my_extension/Configuration/TCA/Overrides/121-tx_myextension_conference-timezone.php 
<?php

use MyVendor\MyExtension\Backend\ItemsProcessor\TimezoneItemsProcessor;
use MyVendor\MyExtension\Backend\TimezoneSorter;
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'timezone' => [
    'label' => 'my_extension.db:conference.timezone',
    'config' => [
      'type' => 'select',
      'renderType' => 'selectSingle',
      'items' => [
        ['label' => '', 'value' => ''],
      ],
      'itemsProcessors' => [
        100 => [
          'class' => TimezoneItemsProcessor::class,
          'parameters' => [
            'regions' => 'Europe,America',
          ],
        ],
      ],
      'itemGroups' => [
        'Europe' => 'my_extension.db:conference.timezone.europe',
        'America' => 'my_extension.db:conference.timezone.america',
      ],
      'sortItems' => [
        'label' => 'asc',
        // Then by the offset to UTC, the time zones with the same offset
        // stay sorted by label
        'offset' => TimezoneSorter::class . '->sortByOffset',
      ],
      'dbFieldLength' => 64,
      'behaviour' => [
        'allowLanguageSynchronization' => true,
      ],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  'timezone',
  '',
  'after:location',
);
Copied!
Example: Sort items by value
'sortItems' => [
  'value' => 'desc',
],
Copied!
Example: Sort items by a custom method

The time zones of a conference are sorted by label first, and then by their offset to UTC. A key other than label and value names a method in the form ClassName->methodName:

EXT:my_extension/Configuration/TCA/Overrides/121-tx_myextension_conference-timezone.php 
<?php

use MyVendor\MyExtension\Backend\ItemsProcessor\TimezoneItemsProcessor;
use MyVendor\MyExtension\Backend\TimezoneSorter;
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'timezone' => [
    'label' => 'my_extension.db:conference.timezone',
    'config' => [
      'type' => 'select',
      'renderType' => 'selectSingle',
      'items' => [
        ['label' => '', 'value' => ''],
      ],
      'itemsProcessors' => [
        100 => [
          'class' => TimezoneItemsProcessor::class,
          'parameters' => [
            'regions' => 'Europe,America',
          ],
        ],
      ],
      'itemGroups' => [
        'Europe' => 'my_extension.db:conference.timezone.europe',
        'America' => 'my_extension.db:conference.timezone.america',
      ],
      'sortItems' => [
        'label' => 'asc',
        // Then by the offset to UTC, the time zones with the same offset
        // stay sorted by label
        'offset' => TimezoneSorter::class . '->sortByOffset',
      ],
      'dbFieldLength' => 64,
      'behaviour' => [
        'allowLanguageSynchronization' => true,
      ],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  'timezone',
  '',
  'after:location',
);
Copied!

The method receives the items as SelectItem objects by reference. The orderings run one after the other, and usort() keeps the order of equal items. Time zones with the same offset therefore stay sorted by label:

EXT:my_extension/Classes/Backend/TimezoneSorter.php 
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Backend;

use TYPO3\CMS\Core\Schema\Struct\SelectItem;

/**
 * Sorts time zones by their current offset to UTC. Time zones with the
 * same offset keep their previous order.
 */
final class TimezoneSorter
{
  /**
   * @param SelectItem[] $items
   */
  public function sortByOffset(array &$items): void
  {
    $now = new \DateTimeImmutable();
    usort(
      $items,
      static fn(SelectItem $a, SelectItem $b): int => self::getOffset($a, $now) <=> self::getOffset($b, $now),
    );
  }

  private static function getOffset(SelectItem $item, \DateTimeImmutable $now): int
  {
    try {
      return (new \DateTimeZone((string)$item->getValue()))->getOffset($now);
    } catch (\Exception) {
      // The empty item stays first
      return PHP_INT_MIN;
    }
  }
}
Copied!