---
title: "Field definitions (columns)"
manual: "TCA Reference"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3tca:columns@main"
source: "Columns/Index.rst"
modified: "2026-09-15T18:56:37+00:00"
---

# Field definitions (columns)

The \['columns'\] section contains configuration for each table  *field* (also called "column") which can
be edited or shown in the backend. This is typically the biggest part of a TCA definition.

The configuration includes both properties for the display in the backend as well as the processing of the
submitted data.

Each field can be configured as a certain "type" (**required!**), for instance a checkbox, an input field, or a
database relation selector box. Each type allows a set of additional "renderType"s (**sometimes required!**). Each "type" and "renderType" combination comes with a set of additional properties.

**Content on this page**

-   [Example: A basic input field](https://docs.typo3.org/permalink/t3tca:example-a-basic-input-field@main)
-   [Properties of columns section of TCA](https://docs.typo3.org/permalink/t3tca:properties-of-columns-section-of-tca@main)

**Subpages**

-   [Display conditions in TCA columns](https://docs.typo3.org/permalink/t3tca:display-conditions-in-tca-columns@main)
-   [Examples](https://docs.typo3.org/permalink/t3tca:examples@main)

## Example: A basic input field

The basic structure of a field definition in TCA looks like this:

![1](../Images/AutomaticScreenshots/Input1.png)

**EXT:styleguide/Configuration/TCA/tx_styleguide_elements_basic.php**

```php
[
    'columns' => [
        'input_1' => [
            'l10n_mode' => 'prefixLangTitle',
            'label' => 'input_1 description',
            'description' => 'field description',
            'config' => [
                'type' => 'input',
                'behaviour' => [
                    'allowLanguageSynchronization' => true,
                ],
            ],
        ],
    ],
]
```

You can find this example in the [extension styleguide](https://docs.typo3.org/permalink/t3tca:styleguide@main).

Properties on the level parallel to [label](https://docs.typo3.org/permalink/t3tca:confval-columns-label@main)
are valid for all "type" and "renderType" combinations.
They are listed below. The list of properties within the "config" section depend on the specific "type" and "renderType"
combination and are explained in detail in the [\['columns'\]\['config'\]](https://docs.typo3.org/permalink/t3tca:columns-types@main) section.

## Properties of `columns` section of TCA

-   **config**

    -   *Type:* array
    -   *Path:* $GLOBALS\['TCA'\]\[$table\]\['columns'\]\[$field\]\['config'\]
    -   *Required:* true
    -   *Scope:* Proc. / Display
    -   *Example:* [Example: A basic input field](https://docs.typo3.org/permalink/t3tca:columns-example-basic@main)

    Contains the main configuration properties of the fields display and
    processing behavior.

    The possibilities for this array depend on the value of the array keys
    [type](https://docs.typo3.org/permalink/t3tca:confval-columns-config-type@main) and [rendertype](https://docs.typo3.org/permalink/t3tca:confval-columns-config-rendertype@main)
    within the array.

    -   **type**

        -   *Type:* string, one of the [column types](https://docs.typo3.org/permalink/t3tca:columns-types@main)
        -   *Path:* $GLOBALS\['TCA'\]\[$table\]\['columns'\]\[$field\]\['config'\]\['type'\]
        -   *Required:* true

        The `type` influences the rendering of the form field in the backend.
        It also influences the processing of data on saving the values.

    -   **rendertype**

        -   *Type:* string
        -   *Path:* $GLOBALS\['TCA'\]\[$table\]\['columns'\]\[$field\]\['config'\]\['rendertype'\]
        -   *Required:* true

        For some [type](https://docs.typo3.org/permalink/t3tca:confval-columns-config-type@main) definitions there are additional
        render types available that mainly influence rendering. For example
        [Select fields](https://docs.typo3.org/permalink/t3tca:columns-select@main) and
        [Text areas](https://docs.typo3.org/permalink/t3tca:columns-text@main) provide different render types.

-   **description**

    -   *Type:* plain text label or [label reference](https://docs.typo3.org/permalink/t3coreapi:label-reference)
    -   *Path:* $GLOBALS\['TCA'\]\[$table\]\['columns'\]\[$field\]
    -   *Required:* false
    -   *Scope:* Display
    -   *Example:* [Example: A basic input field](https://docs.typo3.org/permalink/t3tca:columns-example-basic@main)

    The property can be used to display an additional help text between the field label and
    the user input when editing records. As an example, the Core uses the description property
    in the site configuration module when editing a site on some properties like `identifier`.

    The property is available on all common `TCA` types like `input` and `select` and so on.

    The field can be used with a string that will be directly output or with a
    language reference.

-   **displayCond**

    -   *Type:* string / array
    -   *Path:* $GLOBALS\['TCA'\]\[$table\]\['columns'\]\[$field\]
    -   *Required:* false
    -   *Scope:* Display
    -   *Example:* [Examples for display conditions](https://docs.typo3.org/permalink/t3tca:columns-displaycond-examples@main)

    Contains one or more condition rules for whether to display the field or not.

    Read more in the dedicated chapter [Display conditions in TCA columns](https://docs.typo3.org/permalink/t3tca:columns-displaycond@main).

-   **exclude**

    -   *Type:* boolean
    -   *Path:* $GLOBALS\['TCA'\]\[$table\]\['columns'\]\[$field\]
    -   *Required:* false
    -   *Scope:* Proc. / Display

    If set, all backend users are prevented from editing the field unless they
    are members of a backend user group with this field added as an
    "Allowed Excludefield" (or "admin" user).

    See [Access lists](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Backend/AccessControl/AccessControlOptions/Index.html#access-options-access-lists) for more
    about permissions.

**Example: Simple input field**

```php
[
     'columns' => [
          'input_2' => [
                'label' => 'input_2 description',
                'exclude' => true,
                'config' => [
                     'type' => 'input',

                ],
          ],
     ],
]
```

-   **l10n_display**

    -   *Type:* string (list of keywords)
    -   *Path:* $GLOBALS\['TCA'\]\[$table\]\['columns'\]\[$field\]
    -   *Required:* false
    -   *Scope:* Display
    -   *Example:* [Select field with defaultAsReadonly](https://docs.typo3.org/permalink/t3tca:tca-example-translated-select-single-13@main), [Translated field without l10n_display definition](https://docs.typo3.org/permalink/t3tca:tca-example-translated-select-single-8@main)

    Localization display, see [l10n_mode](https://docs.typo3.org/permalink/t3tca:columns-properties-l10n-mode@main).

    This option can be used to define the language related field
    rendering. This has nothing to do with the processing of language
    overlays and data storage but the display of form fields.

    Keywords are:

    -   **hideDiff**

        The differences to the default language field will not be displayed.

    -   **defaultAsReadonly**

        This renders the field as read only field with the content of the default
        language record. The field will be rendered even if
        [l10n_mode](https://docs.typo3.org/permalink/t3tca:columns-properties-l10n-mode@main) is set to
        `'exclude'`. While `exclude` defines the field not to be
        translatable, this option activates the display of the default data.

-   **l10n_mode**

    -   *Type:* string (keyword)
    -   *Path:* $GLOBALS\['TCA'\]\[$table\]\['columns'\]\[$field\]
    -   *Required:* false
    -   *Scope:* Display / Proc.
    -   *Example:* [Example: prefixLangTitle](https://docs.typo3.org/permalink/t3tca:tca-example-translated-text-2@main), [Disable the prefixLangTitle for the header field in tt_content](https://docs.typo3.org/permalink/t3tca:tca-example-l10n-mode@main)

    Only active if the [\['ctrl'\]\['languageField'\]](https://docs.typo3.org/permalink/t3tca:ctrl-reference-languagefield@main) property is set.

    The main relevance is when a record is localized by an API call in DataHandler that makes a copy of the default
    language record. You can think of this process as copying all fields from the source record. By default, the given
    value from the default language record is copied to the localization overlay and the field is editable in the
    overlay record. This behaviour can be changed:

    -   **exclude**

        Field will not be shown in FormEngine if this record is a localization of the default language. Works basically
        like a display condition. Internally, the field value of the default language record is copied over to the
        field of the localized record. The DataHandler keeps the values of localized records in sync and actively copies
        a changed value from the default language record into the localized overlays if changed.
        You can force the field to be displayed as readonly (with default language value)
        by setting  ["l10n_display"](https://docs.typo3.org/permalink/t3tca:columns-properties-l10n-display@main) to `defaultAsReadonly`.

    -   **prefixLangTitle**

        The field value from the default language record gets copied when a localization overlay is created, but the
        content is prefixed with the title of the target language. The field stays editable in the localized record.
        It only works for field types like "text" and "input". The text will be prepended and can be configured by
        the page TSconfig property [TCEMAIN.translateToMessage](https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/PageTsconfig/TceMain.html#pagetcemain-translatetomessage)

    If this property is not set for a given field, the value of the default language record is copied over to the
    localized record on creation, the field value is then distinct from the default language record, can be edited
    at will and will never be overwritten by the DataHandler if the value of the default language record changes.

-   **label**

    -   *Type:* plain text label or [label reference](https://docs.typo3.org/permalink/t3coreapi:label-reference)
    -   *Path:* $GLOBALS\['TCA'\]\[$table\]\['columns'\]\[$field\]
    -   *Required:* true
    -   *Scope:* Display
    -   *Example:* [Example: A basic input field](https://docs.typo3.org/permalink/t3tca:columns-example-basic@main)

    The name of the field as shown in the form:

    ![](../Images/AutomaticScreenshots/Label.png)

    > [!NOTE]
    > Labels can be overridden in the
    > [types definition](https://docs.typo3.org/permalink/t3tca:types-properties-showitem@main) and the
    > [palettes definition](https://docs.typo3.org/permalink/t3tca:palettes-properties-showitem@main). They can also
    > be overridden by the page TSconfig property
    > [label](https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/PageTsconfig/TceForm.html#tceform_label).

-   **onChange**

    -   *Type:* string
    -   *Path:* $GLOBALS\['TCA'\]\[$table\]\['columns'\]\[$field\]
    -   *Required:* false
    -   *Scope:* Display

    If set to `reload`, it triggers a form reload once the value of this field
    is changed. This is automatically set for fields specified as
    [record type](https://docs.typo3.org/permalink/t3tca:ctrl-reference-type@main) in the control section.

    The `onChange` property is useful for fields which are targets of a
    [display condition's FIELD: evaluation](https://docs.typo3.org/permalink/t3tca:columns-properties-displaycond@main).

    On changing the field a modal gets displayed prompting to reload the record.

    ![](../Images/AutomaticScreenshots/CtrlTypeChangeModal.png)

**Example: Select field triggering reload**

![](../Images/AutomaticScreenshots/SelectRequestupdate1.png)

**EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php**

```php
[
    'columns' => [
        'select_requestUpdate_1' => [
            'label' => 'select_requestUpdate_1',
            'onChange' => 'reload',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => 'Just an item',
                        'value' => 1,
                    ],
                    [
                        'label' => 'bar',
                        'value' => 'bar',
                    ],
                    [
                        'label' => 'and yet another one',
                        'value' => -1,
                    ],
                ],
            ],
        ],
    ],
]
```