---
title: "Extending the user settings"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:user-settings-extending@main"
source: "Configuration/UserSettingsConfiguration/Extending.rst"
rendered: "2026-09-22T13:35:01+00:00"
---

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

<!-- TODO: no Markdown rendering for "deprecated" -->

The method \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addFieldsToUserSettings()
has been deprecated in favor of the new addUserSetting() method.

Adding fields to User Settings is done in a TCA Overrides file.

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

**EXT:examples/Configuration/TCA/Overrides/be_users.php**

```php
<?php

declare(strict_types=1);

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

ExtensionManagementUtility::addUserSetting(
  'mobile',
  [
    'label' => 'LLL:examples.db:be_users.tx_examples_mobile',
    'config' => [
      'type' => 'input',
    ],
  ],
  'after:email',
);

```

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

The new field is then displayed in the user settings after clearing the caches.

## TCA available for the user settings module {#user-settings-columns}

The `user_settings` TCA column has the following structure:

-   **`columns`**

    Array of field configurations, each containing:

    -   **`label`**

        The field label (LLL reference or string)

    -   **`config`**

        Standard TCA config array (type, renderType, items, etc.)

    -   **`table` (optional)**

        Set to `'be_users'` if the field is stored in a be_users table column

-   **`showitem`**

    Comma-separated list of fields to display, supports `--div--;` for tabs

Available field types:

-   `input` \- Text input field
-   `number` \- Number input field
-   `email` \- Email input field
-   `password` \- Password input field
-   `check` with :`renderType => 'checkboxToggle'` \- Checkbox/toggle
-   `select` with `renderType => 'selectSingle'` \- Select dropdown
-   `language` \- Language selector

## "On Click" / "On Confirmation" JavaScript callbacks {#user-settings-extending-javascript}

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

## Migration from `addFieldsToUserSettings` to `addUserSetting` {#user-settings-extending-migration}

Replace the two-step approach with the new `addUserSetting()` method.
Note that the new method uses TCA-style configuration and should be called from
[`Configuration/TCA/Overrides/be_users.php`](../../ExtensionArchitecture/FileStructure/Configuration/TCA/Index.md#file-extension-configuration-tca-overridessomefile-php) instead of [`ext_tables.php`](../../ExtensionArchitecture/FileStructure/ExtTables.md#file-extension-ext-tables-php).

Before:

**ext_tables.php (before)**

```php
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

$GLOBALS['TYPO3_USER_SETTINGS']['columns']['myCustomSetting'] = [
  'type' => 'check',
  'label' => 'my_extension.messages:myCustomSetting',
];
ExtensionManagementUtility::addFieldsToUserSettings(
  'myCustomSetting',
  'after:emailMeAtLogin',
);

```

After:

**Configuration/TCA/Overrides/be_users.php (after)**

```php
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

ExtensionManagementUtility::addUserSetting(
  'myCustomSetting',
  [
    'label' => 'my_extension.messages:myCustomSetting',
    'config' => [
      'type' => 'check',
      'renderType' => 'checkboxToggle',
    ],
  ],
  'after:emailMeAtLogin',
);

```