---
title: "Link handler configuration"
manual: "TYPO3 Explained"
version: "13.4"
permalink: "https://docs.typo3.org/permalink/t3coreapi:link-handler-configuration@13.4"
source: "ApiOverview/LinkHandling/Configuration.rst"
rendered: "2026-10-04T08:50:54+00:00"
---

# Link handler configuration {#link-handler-configuration}

Link browser tabs are registered in [page TSconfig](https://docs.typo3.org/m/typo3/reference-typoscript/13.4/en-us/PageTsconfig/Index.html#pagetsconfig) like this:

**EXT:examples/Configuration/TsConfig/Page/LinkBrowser/HaikuRecordLinkBrowser.tsconfig**

```typoscript
TCEMAIN.linkHandler {
  haiku {
    handler = TYPO3\CMS\Backend\LinkHandler\RecordLinkHandler
    label = LLL:EXT:examples/Resources/Private/Language/locallang_browse_links.xlf:haiku
    configuration {
      table = tx_examples_haiku
    }
    displayAfter = url
    scanBefore = page
  }
}

```

See the complete example: [Tutorial: Custom record link
browser](https://docs.typo3.org/permalink/t3coreapi:tablerecordlinkbrowsertutorials@13.4).

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

Due to the integration of EXT:recordlist into EXT:backend the namespace of
link handlers has changed from
\TYPO3\CMS\Recordlist\LinkHandler
to
\TYPO3\CMS\Backend\LinkHandler.
For TYPO3 v12 the moved classes are available as an alias under the old
namespace to allow extensions to be compatible with TYPO3 v11 and v12.

Possible options are:

-   **`handler`**

    The fully-qualified classname of the link handler.

-   **`label`**

    The name displayed on the tab button in the link browser.

-   **`displayAfter` / `displayBefore`**

    Can be used to decide the order of the tabs.

-   **`scanAfter` / `scanBefore`**

    The first backend link handler who determines that it can [handle the link](https://docs.typo3.org/permalink/t3coreapi:tutorial-backend-link-handler-canhandlelink@13.4) may edit a link. Most
    likely your links will start with a [specific prefix](https://docs.typo3.org/permalink/t3coreapi:tutorial-github-link-handler@13.4) to identify them.

    You should register your tab at least before the `url` link handler.
    The `url` link handler treats all links, that no other handler can treat.

-   **`configuration`**

    Some custom configuration, available to the backend link handler.

## Record link handler configuration {#record-link-handler-configuration}

Record link handlers have the following additional options:

-   **`configuration.hidePageTree = 1`**

    Hide the page tree in the link browser

-   **`configuration.storagePid = 84`**

    The link browser starts with the given page

-   **`configuration.pageTreeMountPoints = 123,456`**

    Only records on these pages and their children will be displayed

## Page link handler configuration {#link-handler-configuration-page-link-handler}

-   **`configuration.pageIdSelector.enabled`**

    Enable an additional field in the link browser to enter the uid of a page.

![The link browser field for entering a page uid.](Linkhandler/Images/LinkBrowserTSConfigExamplepageIdSelector.png)

Enable the field with the following page TSConfig:

**EXT:some_extension/Configuration/page.tsconfig**

```typoscript
TCEMAIN.linkHandler.page.configuration.pageIdSelector.enabled = 1
```

or by configuring the link button in your ckeditor configuration

**EXT:some_extension/Configuration/RTE/Default.yaml**

```yaml
buttons:
  link:
    pageIdSelector:
      enabled: true
```

> [!NOTE]
> Additionally, you have to allow the pageIdSelector as a link option in your RTE configuration, e.g.

**EXT:some_extension/Configuration/RTE/Default.yaml**

```yaml
allowedOptions: 'target,title,class,pageIdSelector'
```