---
title: "Using Custom Permission Options"
manual: "TYPO3 Explained"
version: "12.4"
permalink: "https://docs.typo3.org/permalink/t3coreapi:custom-permissions@12.4"
source: "ApiOverview/Backend/CustomPermissions.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).

# Using Custom Permission Options {#custom-permissions}

TYPO3 allows extension developers to register their own
permission options, managed automatically by the built-in user group
access lists. The options can be grouped in categories. A custom
permission option is always a checkbox (on/off).

The scope of such options is the backend only.

## Registration {#custom-permissions-registration}

Options are configured in the global variable
`$GLOBALS['TYPO3_CONF_VARS']['BE']['customPermOptions']` in
[`EXT:my_extension/ext_tables.php`](../../ExtensionArchitecture/FileStructure/ExtTables.md#file-extension-ext-tables-php). The syntax is demonstrated in
the following example, which registers two custom permission options:

**EXT:my_extension/ext_tables.php**

```php
<?php

declare(strict_types=1);

defined('TYPO3') or die();

// Register some custom permission options shown in BE group access lists
$GLOBALS['TYPO3_CONF_VARS']['BE']['customPermOptions']['tx_styleguide_custom'] = [
    'header' => 'Custom styleguide permissions',
    'items' => [
        'key1' => [
            'Option 1',
            // Icon has been registered in Icons.php
            'tcarecords-tx_styleguide_forms-default',
            'Description 1',
        ],
        'key2' => [
            'Option 2',
        ],
    ],
];

```

The result is that these options appear in the group access lists like
this:

![](../../Images/AutomaticScreenshots/Examples/CustomPermissions/CustomOptions.png)

As you can see it is possible to add both an icon and a description text.
If icons not provided by the Core are used, they need to be registered
with the [Icon API](https://docs.typo3.org/permalink/t3coreapi:icon@12.4).

## Evaluation {#custom-permissions-evaluation}

To check if a custom permission option is set call the following API
function from the user object:

**EXT:some_extension/Classes/SomeClass.php**

```php
$GLOBALS['BE_USER']->check('custom_options', $catKey . ':' . $itemKey);
```

`$catKey` is the category in which the option resides. From the example
above this would be `tx_examples_cat1`.

`$itemKey` is the key of the item in the category you are evaluating.
From the example above this could be `key1`, `key2` or `key3`
depending on which one of them you want to evaluate.

The function returns true if the option is set, otherwise false.

## Keys for Options {#custom-permissions-keys}

It is good practice to use the extension keys prefixed with `tx_` on
the first level of the array to avoid potential conflicts with other
custom options.

> [!WARNING]
> **Attention**
>
> Never pick a key containing any of the characters
> ",:\\|". They are reserved delimiter characters.