---
title: "Frontend link builder"
manual: "TYPO3 Explained"
version: "12.4"
permalink: "https://docs.typo3.org/permalink/t3coreapi:link-builder@12.4"
source: "ApiOverview/LinkHandling/LinkBuilder.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).

# Frontend link builder {#link-builder}

A link builder, a class extending the abstract class
`\TYPO3\CMS\Frontend\Typolink\AbstractTypolinkBuilder`, is called whenever
a link is rendered in the frontend.

There are specific link builders for each type of link. Which link to
call is determined by the class configured in global configuration,
see [FE - frontend configuration](https://docs.typo3.org/permalink/t3coreapi:typo3confvars-fe-typolinkbuilder@12.4).

You can register a custom link builder in your extension's
[ext_localconf.php](https://docs.typo3.org/permalink/t3coreapi:ext-localconf-php@12.4):

**EXT:my_extension/ext_localconf.php**

```php
<?php

declare(strict_types=1);

use MyVendor\MyExtension\LinkHandler\MyLinkBuilder;

defined('TYPO3') or die();

$GLOBALS['TYPO3_CONF_VARS']['FE']['typolinkBuilder']['mylinkkey'] =
    MyLinkBuilder::class;

```

The link builders provided by the Core can be found in namespace
`\TYPO3\CMS\Frontend\Typolink`. It is possible to also create a
[custom link builder](https://docs.typo3.org/permalink/t3coreapi:tutorial-typolink-builder@12.4).

The main method of a link builder is the function
`AbstractTypolinkBuilder::build()`. It is called with
with the parameter array provided by the
[Core link handler](https://docs.typo3.org/permalink/t3coreapi:core-link-handler@12.4).

If the link can be rendered,
it returns a new `\TYPO3\CMS\Frontend\Typolink\LinkResult` object. The
actual rendering of the link depends on the context the link is rendered in
(for example HTML or JSON).

If the link cannot be built it should throw a
`\TYPO3\CMS\Frontend\Typolink\UnableToLinkException`.