---
title: "Extending the user settings"
manual: "TYPO3 Explained"
version: "12.4"
permalink: "https://docs.typo3.org/permalink/t3coreapi:user-settings-extending@12.4"
source: "Configuration/UserSettingsConfiguration/Extending.rst"
rendered: "2026-10-21T15:29:37+00:00"
---

> [!WARNING]
> **Attention**
>
> TYPO3 v12 has reached end-of-life as of April 30th 2026 and
> is no longer being maintained. Use the version switcher on the top
> left of this page to select documentation for a supported version of TYPO3.
>
> Need more time before upgrading?
> You can purchase Extended Long Term Support (ELTS) for TYPO3 v12 here:
> [TYPO3 ELTS](https://typo3.com/services/extended-support-elts).

# Extending the user settings {#user-settings-extending}

Adding fields to the User Settings is done in two steps.
First of all, the new fields are added directly to the
`$GLOBALS['TYPO3_USER_SETTINGS']` array. Then the
field is made visible by calling
`\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addFieldsToUserSettings()`.

The configuration needs to be put into [`ext_tables.php`](../../ExtensionArchitecture/FileStructure/ExtTables.md#file-extension-ext-tables-php).

Here is an example, taken from the "examples" extension:

**EXT:examples/ext_tables.php**

```php
<?php

declare(strict_types=1);

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

$lll = 'LLL:EXT:examples/Resources/Private/Language/locallang_db.xlf:';

$GLOBALS['TYPO3_USER_SETTINGS']['columns']['tx_examples_mobile'] = [
    'label' => $lll . 'be_users.tx_examples_mobile',
    'type' => 'text',
    'table' => 'be_users',
];
ExtensionManagementUtility::addFieldsToUserSettings(
    $lll . 'be_users.tx_examples_mobile,tx_examples_mobile',
    'after:email',
);

```

The second parameter in the call to `addFieldsToUserSettings()`
is used to position the new field. In this example, we decide to add it
after the existing "email" field.

In this example the field is also added to the "be_users" table. This is
not described here as it belongs to 'extending the $TCA array'.
See label 'extending' in older versions of the TCA-Reference.

And here is the new field in the User Tools > User Settings module:

![](../../Images/AutomaticScreenshots/UserSettings/UserSettingsExtending.png)

## "On Click" / "On Confirmation" JavaScript Callbacks {#on-click-on-confirmation-javascript-callbacks}

To extend the User Settings module with JavaScript callbacks - for example with
a custom button or special handling on confirmation, use `clickData` or
`confirmData`:

**EXT:examples/ext_tables.php**

```php
<?php

declare(strict_types=1);

defined('TYPO3') or die();

$GLOBALS['TYPO3_USER_SETTINGS'] = [
    'columns' => [
        'customButton' => [
            'type' => 'button',
            'clickData' => [
                'eventName' => 'setup:customButton:clicked',
            ],
            'confirm' => true,
            'confirmData' => [
                'message' => 'Please confirm...',
                'eventName' => 'setup:customButton:confirmed',
            ],
        ],
        // ...
    ],
];

```

Events declared in corresponding `eventName` options have to be handled by
a custom static JavaScript module. Following snippets show the relevant parts:

```js
document.querySelectorAll('[data-event-name]')
  .forEach((element: HTMLElement) => {
    element.addEventListener('setup:customButton:clicked', (evt: Event) => {
      alert('clicked the button');
    });
  });
document.querySelectorAll('[data-event-name]')
  .forEach((element: HTMLElement) => {
    element.addEventListener('setup:customButton:confirmed', (evt: Event) => {
      evt.detail.result && alert('confirmed the modal dialog');
    });
  });

```

PSR-14 event [AddJavaScriptModulesEvent](https://docs.typo3.org/permalink/t3coreapi:addjavascriptmodulesevent@12.4) can be used
to inject a JavaScript module to handle those custom JavaScript events.