TYPO3 Documentation
TCA Reference
Options
Give feedback View source View as Markdown How to edit Edit on GitHub

TCA Reference

About table configuration

  • Introduction
  • Examples
    • Exploring TCA with the styleguide
  • Best practices
    • Common fields
    • Language fields

Reference

  • Field definitions (columns)
    • Display conditions in TCA columns
    • Examples
  • Field types (config > type)
    • Properties in depth
      • itemsProcessors
      • itemsProcFunc
      • MM
      • fieldControl
        • addRecord
        • editPopup
        • listModule
        • resetSelection
      • fieldInformation
        • tcaDescription
      • fieldWizard
        • defaultLanguageDifferences
        • localizationStateSelector
        • otherLanguageContent
    • Category
      • Examples
    • Checkboxes
      • Default checkbox
      • Toggle checkbox
      • Labeled toggle checkbox
      • Examples
    • Color
    • Country
    • Datetime
    • Email
    • File
    • FlexForm field
      • Using FlexForms
      • FlexForm syntax
      • Examples
    • Folder
    • Group fields
      • Examples
      • Stored data values
    • Image manipulation
    • IRRE / inline
      • Examples
    • Input
    • Json
    • Language fields
      • Migration
      • History
    • Link
    • The none field
    • Number
    • Pass through / virtual field
    • Password
      • Password policy examples
      • Password generator examples
    • Radio buttons
    • 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
    • Text areas & RTE
      • text (multiline)
      • Rich text editor (RTE)
      • belayoutwizard
      • codeEditor
      • textTable
    • Custom inputs (user)
    • Uuid
  • Table properties (ctrl)
    • Auto-created columns
    • Enabling columns
    • Examples
  • Grouping fields (palettes)
  • Record types
    • tt_content system fields

Appendix

  • Sitemap

Options

Give feedback View source View as Markdown How to edit Edit on GitHub
  1. TCA Reference
  2. Field types (config > type)
  3. Link
Give feedback Markdown Edit on GitHub

Link 

New in version 13.0

When using the link type, TYPO3 takes care of generating the according database field. A developer does not need to define this field in an extension's ext_tables.sql file.

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

The according database field is generated automatically.

Table of contents:

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

Example: A basic link field 

The link to the tickets of a conference

The link to the tickets of a conference

EXT:my_extension/Configuration/TCA/Overrides/118-tx_myextension_conference-ticket_link.php
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'ticket_link' => [
    'label' => 'my_extension.db:conference.ticket_link',
    'displayCond' => [
      'AND' => [
        'FIELD:registration_open:REQ:true',
        'FIELD:seats:>:0',
      ],
    ],
    'config' => [
      'type' => 'link',
      'allowedTypes' => ['page', 'url'],
      'appearance' => [
        'browserTitle' => 'my_extension.db:conference.ticket_link.browser_title',
      ],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  'ticket_link',
  '',
  'after:registration_deadline',
);
Copied!

Properties of the TCA column type link 

Name Type Scope
allowedTypes
array of keywords Display / Proc.
behaviour
allowLanguageSynchronization
boolean Proc.
appearance
array Display
allowedOptions
array
allowedFileExtensions
array
browserTitle
string, LLL
enableBrowser
boolean
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.
searchable
boolean Display
size
integer Display
valuePicker
array Display
allowedTypes
Type
array of keywords
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['allowedTypes']
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.

EXT:my_extension/Configuration/TCA/Overrides/118-tx_myextension_conference-ticket_link.php
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'ticket_link' => [
    'label' => 'my_extension.db:conference.ticket_link',
    'displayCond' => [
      'AND' => [
        'FIELD:registration_open:REQ:true',
        'FIELD:seats:>:0',
      ],
    ],
    'config' => [
      'type' => 'link',
      'allowedTypes' => ['page', 'url'],
      'appearance' => [
        'browserTitle' => 'my_extension.db:conference.ticket_link.browser_title',
      ],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  'ticket_link',
  '',
  'after:registration_deadline',
);
Copied!
'allowedTypes' => [
  'page',
  // A custom link handler, defined by its identifier
  'my_handler',
],
Copied!
// Allow all link types (or skip this option)
'allowedTypes' => ['*'],
Copied!
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 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/240-tx_myextension_talk-recording.php
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_talk', [
  'recording' => [
    'label' => 'my_extension.db:talk.recording',
    'config' => [
      'type' => 'link',
      'allowedTypes' => ['url'],
      'appearance' => [
        'allowedOptions' => [],
        'enableBrowser' => false,
      ],
      'behaviour' => [
        'allowLanguageSynchronization' => true,
      ],
      'searchable' => false,
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_talk',
  'recording',
  'talk,keynote',
  'before:--div--;core.form.tabs:access',
);
Copied!
appearance
Type
array
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['appearance']
Scope
Display

Has information about the appearance, namely:

allowedOptions
Type
array
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['appearance']['allowedOptions']

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.

Changed in version 14.2

No longer limited to RTE-enabled fields.

For RTE-enabled fields, buttons.link.relAttribute.enabled, must be enabled.

The link to the recording of a talk shows no options:

EXT:my_extension/Configuration/TCA/Overrides/240-tx_myextension_talk-recording.php
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_talk', [
  'recording' => [
    'label' => 'my_extension.db:talk.recording',
    'config' => [
      'type' => 'link',
      'allowedTypes' => ['url'],
      'appearance' => [
        'allowedOptions' => [],
        'enableBrowser' => false,
      ],
      'behaviour' => [
        'allowLanguageSynchronization' => true,
      ],
      'searchable' => false,
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_talk',
  'recording',
  'talk,keynote',
  'before:--div--;core.form.tabs:access',
);
Copied!

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.

The email for feedback on a talk can have a subject and a text:

EXT:my_extension/Configuration/TCA/Overrides/257-tx_myextension_talk-feedback_email.php
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_talk', [
  'feedback_email' => [
    'label' => 'my_extension.db:talk.feedback_email',
    'config' => [
      'type' => 'link',
      'allowedTypes' => ['email'],
      'appearance' => [
        // The email can have a prepared subject and text
        'allowedOptions' => ['subject', 'body'],
      ],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_talk',
  'feedback_email',
  '',
  'after:comments',
);
Copied!
allowedFileExtensions
Type
array
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['appearance']['allowedFileExtensions']

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.

The program of a conference links to a PDF file:

EXT:my_extension/Configuration/TCA/Overrides/137-tx_myextension_conference-program.php
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'program' => [
    'label' => 'my_extension.db:conference.program',
    'config' => [
      'type' => 'link',
      'allowedTypes' => ['file'],
      'appearance' => [
        // The printed program is a PDF file
        'allowedFileExtensions' => ['pdf'],
      ],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  'program',
  '',
  'after:website',
);
Copied!
browserTitle
Type
string, LLL
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['appearance']['browserTitle']

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

EXT:my_extension/Configuration/TCA/Overrides/118-tx_myextension_conference-ticket_link.php
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'ticket_link' => [
    'label' => 'my_extension.db:conference.ticket_link',
    'displayCond' => [
      'AND' => [
        'FIELD:registration_open:REQ:true',
        'FIELD:seats:>:0',
      ],
    ],
    'config' => [
      'type' => 'link',
      'allowedTypes' => ['page', 'url'],
      'appearance' => [
        'browserTitle' => 'my_extension.db:conference.ticket_link.browser_title',
      ],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  'ticket_link',
  '',
  'after:registration_deadline',
);
Copied!
'appearance' => [
  // Or a plain string
  'browserTitle' => 'Link to the tickets',
],
Copied!
enableBrowser
Type
boolean
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['appearance']['enableBrowser']

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

EXT:my_extension/Configuration/TCA/Overrides/240-tx_myextension_talk-recording.php
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_talk', [
  'recording' => [
    'label' => 'my_extension.db:talk.recording',
    'config' => [
      'type' => 'link',
      'allowedTypes' => ['url'],
      'appearance' => [
        'allowedOptions' => [],
        'enableBrowser' => false,
      ],
      'behaviour' => [
        'allowLanguageSynchronization' => true,
      ],
      'searchable' => false,
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_talk',
  'recording',
  'talk,keynote',
  'before:--div--;core.form.tabs:access',
);
Copied!
autocomplete
Type
boolean
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['autocomplete']
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:

'autocomplete' => true,
Copied!
default
Type
string
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['default']
Scope
Display / Proc.

Default value set if a new record is created.

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.

mode
Type
string (keywords)
TCA 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 .

nullable
Type
boolean
Default
false
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['nullable']
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
'nullable' => true,
Copied!
placeholder
Type
string
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['placeholder']
Scope
Display

Placeholder, containing a default value.

'placeholder' => 'https://example.org',
Copied!

Note

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

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.

Warning

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

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

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

Changed in version 14.0 Breaking: #106976 - Removal of TCA search field configuration options

The following TCA field level search configuration options have been removed:

  • search.case
  • search.pidonly
  • search.andWhere

They have not been supported by the Core or common Extensions.

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

New in version 14.0

TYPO3 now automatically includes all fields of suitable types in backend search operations in the Content > Records module.

This option can be used to explicitly exclude fields from being searchable, instead of having to list them in the now removed option $GLOBALS['TCA'][$table]['ctrl']['searchFields'].

By default, all fields of type link are considered searchable. To exclude a field from being searchable, set the following in the field's TCA configuration:

EXT:my_extension/Configuration/TCA/Overrides/240-tx_myextension_talk-recording.php
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_talk', [
  'recording' => [
    'label' => 'my_extension.db:talk.recording',
    'config' => [
      'type' => 'link',
      'allowedTypes' => ['url'],
      'appearance' => [
        'allowedOptions' => [],
        'enableBrowser' => false,
      ],
      'behaviour' => [
        'allowLanguageSynchronization' => true,
      ],
      'searchable' => false,
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_talk',
  'recording',
  'talk,keynote',
  'before:--div--;core.form.tabs:access',
);
Copied!
size
Type
integer
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['size']
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
Type
array
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['valuePicker']
Scope
Display

Renders a select box with static values next to the input field. When an item is selected, the value replaces the current input value.

Changed in version 14.0 Breaking: #107677 - Drop prepend and append modes from TCA value picker

It is now recommended to define associative array keys for items using label and value. Existing numeric arrays are automatically migrated during TCA processing.

The mode option no longer supports append or prepend. The Value Picker always behaves like a replace operation. Legacy mode settings are ignored.

items (array)
A list of selectable items. Each item should be an associative array: ['label' => 'Shown label', 'value' => 'storedValue']. The label can be plain text or a label reference.

Hint

In earlier TYPO3 versions, the mode option allowed you to prepend or append the selected value to the current input. This option was removed in TYPO3 v14.0. The value picker now always replaces the current field value.

If you previously used mode => 'prepend' to insert a prefix (for example, to automatically add https:// before a link), you can achieve a similar result with a custom FormEngine element or a small JavaScript hook that modifies the input value after selection.

Example: Common profile addresses as a start for the website
The website of a speaker with its value picker

The website of a speaker with its value picker

EXT:my_extension/Configuration/TCA/Overrides/315-tx_myextension_speaker-website.php
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_speaker', [
  'website' => [
    'label' => 'my_extension.db:speaker.website',
    'config' => [
      'type' => 'link',
      'valuePicker' => [
        'items' => [
          ['label' => 'Profile page', 'value' => 'https://example.org/profile/'],
          ['label' => 'Code repository', 'value' => 'https://example.org/code/'],
        ],
      ],
      'allowedTypes' => ['url'],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_speaker',
  'website',
  '',
  'before:--div--;my_extension.db:tab.integration',
);
Copied!

Note

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

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, inject LinkFactory and call create() or createUri() on it. Both return a LinkResultInterface . Its method getUrl() returns the URL:

EXT:my_extension/Classes/Frontend/TicketUriBuilder.php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Frontend;

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

/**
 * Creates the URL of the ticket link of a conference: a page of the site or
 * the shop of a ticket provider
 */
final readonly class TicketUriBuilder
{
  public function __construct(
    private LinkFactory $linkFactory,
  ) {}

  /**
   * @param array<string, mixed> $conference
   */
  public function getUri(array $conference, ContentObjectRenderer $contentObjectRenderer): string
  {
    return $this->linkFactory
      ->createUri((string)($conference['ticket_link'] ?? ''), $contentObjectRenderer)
      ->getUrl();
  }
}
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: Oct 25, 2026 16:42

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