TYPO3 Logo
TCA Reference
Options
Give feedback View source How to edit Edit on GitHub Full documentation (single file)

TCA Reference

About table configuration

  • Introduction
  • Examples
    • About the examples
    • How to use the styleguide extension
  • Best practices
    • Common fields
    • Language fields

Reference

  • Field definitions (columns)
    • Display conditions in TCA columns
    • Examples
  • Field types (config > type)
    • Properties in depth
      • fieldInformation
      • itemsProcFunc
      • MM
      • fieldControl
        • addRecord
        • editPopup
        • listModule
        • resetSelection
      • fieldWizard
        • defaultLanguageDifferences
        • localizationStateSelector
        • otherLanguageContent
    • Category
      • Examples
    • Checkboxes
      • Default checkbox
      • Toggle checkbox
      • Labeled toggle checkbox
      • Examples
    • Color
    • Datetime
    • Email
    • File
    • FlexForm field
      • About the data structure
      • FlexForm syntax
      • Examples
    • Folder
    • Group fields
      • Examples
      • Stored data values
    • Image manipulation
    • IRRE / inline
      • Examples
    • Input
    • Json
    • Language fields
      • Introduction
      • Examples
      • Language field properties
      • Migration
      • History
    • Link
    • The none field
    • Number
    • Pass through / virtual field
    • Password
      • Password policy examples
      • Password generator examples
    • Radiobuttons
    • Select fields
      • selectSingle
      • Select multiple values (selectSingleBox)
      • selectCheckBox
        • selectCheckBox and type check fields compared
      • selectMultipleSideBySide
        • Examples
      • selectTree
      • Property details
        • Item group API methods
    • Slugs / URL parts
      • Introduction
    • Text areas & RTE
      • text (multiline)
      • Rich text editor (RTE)
      • belayoutwizard
      • t3editor
      • textTable
    • Custom inputs (user)
    • Uuid
  • Table properties (ctrl)
    • Enabling columns
    • Examples
  • Backend display (interface)
  • Grouping fields (palettes)
  • Fields to be displayed (types)

Appendix

  • Sitemap
  1. TCA Reference
  2. Field types (config > type)
  3. Link
Give feedback Edit on GitHub

Link

New in version 12.0

The TCA type link has been introduced. It replaces the renderType=inputLink option of TCA type input. See also Migration

The TCA type link should be used to input values representing typolinks.

  • Example: A basic link field
  • Properties of the TCA column type link
  • Migration
  • Create an URL

Example: A basic link field

<?php

return [
    // ...
    'columns' => [
        'a_link_field' => [
            'label' => 'Link',
            'config' => [
                'type' => 'link',
                'allowedTypes' => ['page', 'url', 'record'],
            ],
        ],
    ],
];
Copied!

Properties of the TCA column type link

Name Type Scope
allowedTypes
array of keywords Display / Proc.
behaviour
allowLanguageSynchronization
boolean Proc.
appearance
array Display
autocomplete
boolean Display
default
string Display / Proc.
fieldControl
fieldInformation
fieldWizard
defaultLanguageDifferences
array
localizationStateSelector
array
otherLanguageContent
array
mode
string (keywords) Display
nullable
boolean Proc
placeholder
string Display
readOnly
boolean Display
required
boolean Display / Proc.
search
array Search
pidonly
boolean
case
boolean
andWhere
string
size
integer Display
valuePicker
array Display

New in version 12.0

Instead of the former exclude list blindLinkOptions of linkPopup.options, the type link uses now include lists. Those lists are furthermore no longer comma separated, but PHP arrays, with each option as a separate value.

The replacement for the previously used blindLinkOptions option is the allowedTypes configuration. The allowedTypes configuration is also evaluated in the DataHandler, preventing the user from adding links of non-allowed types.

To allow all link types, skip the allowedTypes configuration or set it to ['*']. It's not possible to deny all types.

allowedTypes

allowedTypes
Type
array of keywords
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display / Proc.
page
Links to internal pages
url
Links to external pages
file
Links to a file
folder
Links to a folder
email
Creates an email link
telephone
Creates a phone link
record

Enables any record link handler that is defined in the LinkHandler API. To enable only a specific custom LinkHandler, add the defined identifier instead.

// 'record' will match any custom link handler
'allowedTypes' => ['page', 'url', 'record']
Copied!
// 'tx_news' and 'custom_identifier' are both custom link handlers
'allowedTypes' => ['page', 'url', 'tx_news', 'custom_identifier']
Copied!
// Allow all types (or skip this option).
'allowedTypes' => ['*']
Copied!

behaviour

behaviour

allowLanguageSynchronization

allowLanguageSynchronization
Type
boolean
Default
false
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 link. 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/someTable.php
<?php

$linkField = [
    'config' => [
        'type' => 'link',
        'behaviour' => [
            'allowLanguageSynchronization' => true,
        ],
    ],
];
Copied!

appearance

appearance
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display

Has information about the appearance, namely:

allowedOptions (array)

New in version 12.0

Formerly known as blindLinkFields of linkPopup.options, which was a deny-list. Now this is an include-list.

Display certain options in the link browser. To allow all options in the Link Browser, skip this configuration or set it to ['*']. To deny all options in the Link Browser, set this configuration to [] (empty array).

class
Custom CSS classes for the link
params
Additional link parameters
target
Either empty, _top or _blank
title
The title attribute of the link
rel
The link relationship. Only available for RTE enabled fields and if buttons.link.relAttribute.enabled is enabled in the RTE YAML configuration.
// Display only 'class' and 'params'
'appearance' => [
    'allowedOptions' => ['class', 'params'],
],
Copied!
// Allow all options (or skip this option).
'appearance' => [
    'allowedOptions' => ['*'],
],
Copied!
// Deny all options
'appearance' => [
    'allowedOptions' => [],
],
Copied!

New in version 12.3

For custom email links, the options can be restricted:

body
The body of an email can be pre-filled.
cc
The "cc" field can be pre-filled.
bcc:
The "bcc" field can be pre-filled.
subject:
The subject of an email can be pre-filled.
'appearance' => [
    'allowedOptions' => ['body', 'cc'],
],
Copied!
allowedFileExtensions (array)

New in version 12.0

Formerly known as allowedExtensions of linkPopup.options.

An array of allowed file extensions. To allow all extensions, skip this configuration or set it to ['*']. It's not possible to deny all extensions.

// Allow only jpg and png file extensions
'appearance' => [
    'allowedFileExtensions' => ['jpg', 'png'],
],
Copied!
// Allow all file extensions (or skip this option).
'appearance' => [
    'allowedFileExtensions' => ['*'],
],
Copied!
browserTitle (string, LLL)

New in version 12.0

Formerly known as title of linkPopup.options.

Allows to set a different title attribute for the Link Browser icon, defaults to Link.

// Either provide a LLL-reference (recommended)
'appearance' => [
    'browserTitle' => 'LLL:EXT:Resources/Private/Language/locallang.xlf:my_custom_title',
],
Copied!
// Or a simple string value
'appearance' => [
    'browserTitle' => 'My custom title',
],
Copied!
enableBrowser (boolean)

New in version 12.0

Formerly known as disabled of linkPopup.

The Link Browser is enabled by default. To disable the Link Browser altogether, set this option to false.

// Disable the link browser
'appearance' => [
    'enableBrowser' => false,
],
Copied!

autocomplete

autocomplete
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display

Controls the autocomplete attribute of a given link field. If set to true (default false), adds attribute autocomplete="on" to the email input field allowing browser auto filling the field:

EXT:some_extension/Configuration/TCA/Overrides/tx_sometable.php
<?php

$myLinkField = [
    'label' => 'A link with autocomplete',
    'config' => [
        'type' => 'link',
        'size' => 20,
        'nullable' => 'true',
        'autocomplete' => true,
    ],
];
Copied!

default

default
Type
string
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['default']
Scope
Display / Proc.

Default value set if a new record is created.

fieldControl

fieldControl

For details see fieldControl.

fieldInformation

fieldInformation

For details see fieldInformation.

fieldWizard

fieldWizard

defaultLanguageDifferences

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

For details see defaultLanguageDifferences.

localizationStateSelector

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

For details see localizationStateSelector.

otherLanguageContent

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

For details see otherLanguageContent.

mode

mode
Type
string (keywords)
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['mode']
Scope
Display

Possible keywords: useOrOverridePlaceholder

This property is related to the placeholder property. When defined, a checkbox will appear above the field. If that box is checked, the field can be used to enter whatever the user wants as usual. If the box is not checked, the field becomes read-only and the value saved to the database will be NULL.

Warning

In order for this property to apply properly, the DB column must be allowed to be NULL, and property nullable must be set to true.

Changed in version 12.0

This option was introduced to replace the TCA eval option with null as value.

nullable

nullable
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Default
false
Scope
Proc

If set to true, a checkbox will appear, which by default deactivates the field. In the deactivated state the field is saved as NULL in the database. By activating the checkbox it is possible to set a value. If nothing is entered into the field, then an empty string will be saved and not a NULL.

The database field must allow the NULL value.

Example: a nullable link field
EXT:some_extension/Configuration/TCA/Overrides/tx_sometable.php
<?php

$myLinkField = [
    'title' => 'A nullable field',
    'config' => [
        'type' => 'link',
        'nullable' => true,
    ],
];
Copied!

placeholder

placeholder
Type
string
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['placeholder']
Scope
Display

Placeholder, containing a default value.

EXT:my_extension/Configuration/TCA/Overrides/some-table.php
<?php

$temporaryColumns['alinkField'] = [
    'title' => 'My link field',
    'config' => [
        'type' => 'link',
        'placeholder' => '#FF8700',
        'mode' => 'useOrOverridePlaceholder',
    ],
];
Copied!

Note

As the TCA is cached it is not possible to set dynamic values such as now().

readOnly

readOnly
Type
boolean
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.

Warning

This property affects only the display. It is still possible to write to those fields when using the DataHandler.

required

required
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display / Proc.
Default
false

If set to true a non-empty value is required in the field. Otherwise the form cannot be saved.

search

search
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['search']
Scope
Search

Defines additional search-related options for a given field.

pidonly

pidonly
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['search']['pidonly']

Searches in the column only if search happens on the single page, does not search the field if searching in the whole table.

case

case
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['search']['case']

Makes the search case-sensitive. This requires a proper database collation for the field, see your database documentation.

andWhere

andWhere
Type
string
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['search']['andWhere']

Additional SQL WHERE statement without 'AND'. With this it is possible to place an additional condition on the field when it is searched

EXT:some_extension/Configuration/TCA/tx_sometable.php
$temporaryColumns['some_date'] => [
    'config' => [
        'search' => [
            'andWhere' => '{#CType}=\'type_x\' OR {#CType}=\'type_y\'',
        ],
        // ...
    ],
];
Copied!

This means that the "some_date" field of the "tt_content" table will be searched in only for elements of type X and Y. This helps making any search more relevant.

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

size

size
Type
integer
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display

Abstract value for the width of the <input> field. To set the link field to the full width of the form area, use the value 50. Minimum is 10. Default is 30.

valuePicker

valuePicker
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display

Renders a select box with static values next to the input field. When a value is selected in the box, the value is transferred to the field. Keys:

mode (keyword)
blank (or not set)
The selected value substitutes the value in the input field
append
The selected value is appended to an existing value of the input field
prepend
The selected value is prepended to an existing value of the input field
items (array)
An array with selectable items. Each item is an array with the first value being the label in the select drop-down (LLL reference possible) the second being the value transferred to the input field.
Example: A link field with value picker
<?php

$myLinkField = [
    'label' => 'input_33',
    'config' => [
        'type' => 'link',
        'mode' => 'prepend',
        'valuePicker' => [
            'items' => [
                ['HTTPS', 'https://'],
                ['HTTP', 'http://'],
            ],
        ],
    ],
];
Copied!

Note

The softref definition softref=typolink is automatically applied to all TCA type link columns.

Migration

The previously configured linkPopup field control is now integrated into the new TCA type directly. Additionally, instead of exclude lists ( blindLink[Fields|Options]), does the new type now use include lists. Those lists are furthermore no longer comma separated, but PHP array's, with each option as a separate value.

The migration from renderType=inputLink to type=link is done like following:

  'a_link_field' => [
      'label' => 'Link',
      'config' => [
-         'type' => 'input',
-         'renderType' => 'inputLink',
+         'type' => 'link',
          'required' => true,
          'size' => 20,
-         'max' => 1024,
-         'eval' => 'trim,null',
-         'fieldControl' => [
-             'linkPopup' => [
-                 'disabled' => true,
-                 'options' => [
-                     'title' => 'Browser title',
-                     'allowedExtensions' => 'jpg,png',
-                     'blindLinkFields' => 'class,target,title',
-                     'blindLinkOptions' => 'mail,folder,file,telephone',
-                 ],
-             ],
-         ],
-         'softref' => 'typolink',
+         'nullable' => true,
+         'allowedTypes' => ['page', 'url', 'record'],
+         'appearance' => [
+             'enableBrowser' => false,
+             'browserTitle' => 'Browser title',
+             'allowedFileExtensions' => ['jpg', 'png'],
+             'allowedOptions' => ['params', 'rel'],
+         ],
      ],
  ],
Copied!

An automatic TCA migration is performed on the fly, migrating all occurrences to the new TCA type and triggering a PHP E_USER_DEPRECATED error where code adoption has to take place.

Note

The value of TCA type link columns is automatically trimmed before being stored in the database. Therefore, the eval=trim option is no longer needed and should be removed from the TCA configuration.

Note

The prior softref definition softref=>typolink is now automatically applied to all link fields.

Create an URL

To create a URL from such a link field in a Fluid template, use the <f:link.typolink> or <f:uri.typolink> view helper.

In PHP code, use LinkFactory::create() or LinkFactory::createUri():

EXT:my_extension/Classes/Service/MyService.php
<?php

namespace MyVendor\MyExtension\Service;

use TYPO3\CMS\Frontend\ContentObject\ContentObjectRenderer;
use TYPO3\CMS\Frontend\Typolink\LinkFactory;

class SomeService
{
    public function __construct(
        private readonly LinkFactory $linkFactory,
    ) {}

    public function getUri(string $tcaLinkValue, ContentObjectRenderer $contentObjectRenderer): string
    {
        return $this->linkFactory->createUri(
            $tcaLinkValue,
            $contentObjectRenderer
        );
    }
}
Copied!
  • Previous
  • Next
Reference to the headline

Copy and freely share the link

This link target has no permanent anchor assigned. You can make a pull request on GitHub to suggest an anchor. The link below can be used, but is prone to change if the page gets moved.

Copy this link into your TYPO3 manual.

  • Home
  • Contact
  • Issues
  • Repository

Last rendered: May 04, 2025 10:06

© since 2012 by the TYPO3 contributors
  • Legal Notice
  • Privacy Policy