---
title: "Icon API"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:icon@main"
source: "ApiOverview/Icon/Index.rst"
rendered: "2026-09-21T11:24:09+00:00"
---

# Icon API {#icon}

TYPO3 provides an icon API for all icons in the TYPO3 backend.

-   [Registration](https://docs.typo3.org/permalink/t3coreapi:registration@main)
-   [Using icons in your code](https://docs.typo3.org/permalink/t3coreapi:using-icons-in-your-code@main)
-   [Available icons](https://docs.typo3.org/permalink/t3coreapi:available-icons-1@main)
-   [Migration](https://docs.typo3.org/permalink/t3coreapi:migration@main)

## Registration {#icon-registration}

All icons must be registered in the icon registry.
To register icons for your own extension, create a file called
[`Configuration/Icons.php`](../../ExtensionArchitecture/FileStructure/Configuration/Icons.md#file-extension-configuration-icons-php) in your extension - for example:
[`EXT:my_extension/Configuration/Icons.php`](../../ExtensionArchitecture/FileStructure/Configuration/Icons.md#file-extension-configuration-icons-php).

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

It is not possible anymore to register icons in the
ext_localconf.php file.Migrate the icon registration to
new format. There is also a Rector rule.

The file needs to return a PHP configuration array with the following keys:

**EXT:my_extension/Configuration/Icons.php**

```php
<?php

declare(strict_types=1);

use TYPO3\CMS\Core\Imaging\IconProvider\BitmapIconProvider;
use TYPO3\CMS\Core\Imaging\IconProvider\SvgIconProvider;
use TYPO3\CMS\Core\Imaging\IconProvider\SvgSpriteIconProvider;

return [
  // Icon identifier
  'tx-myextension-svgicon' => [
    // Icon provider class
    'provider' => SvgIconProvider::class,
    // The source SVG for the SvgIconProvider
    'source' => 'EXT:my_extension/Resources/Public/Icons/mysvg.svg',
  ],
  'tx-myextension-bitmapicon' => [
    'provider' => BitmapIconProvider::class,
    // The source bitmap file
    'source' => 'EXT:my_extension/Resources/Public/Icons/mybitmap.png',
    // All icon providers provide the possibility to register an icon that spins
    'spinning' => true,
  ],
  'tx-myextension-anothersvgicon' => [
    'provider' => SvgIconProvider::class,
    'source' => 'EXT:my_extension/Resources/Public/Icons/anothersvg.svg',
    // Since TYPO3 v12.0 an extension that provides icons for broader
    // use can mark such icons as deprecated with logging to the TYPO3
    // deprecation log. All keys (since, until, replacement) are optional.
    'deprecated' => [
      'since' => 'my extension v2',
      'until' => 'my extension v3',
      'replacement' => 'alternative-icon',
    ],
  ],
  'tx-myextension-spriteicon' => [
    // Icon provider for SVG sprites
    'provider' => SvgSpriteIconProvider::class,
    // The SVG sprite with fragment identifier (<symbol id="…">)
    'sprite' => 'EXT:my_extension/Resources/Public/Icons/sprite.svg#tx-myextension',
  ],
];

```

### Minimal SVG sprite structure {#icon-registration-minimal-svg-sprite}

When registering an icon with the `SvgSpriteIconProvider`, the referenced
SVG file must expose icons via the `<symbol>` element. A minimal SVG sprite
may look like this:

**Minimal SVG sprite example**

```xml
<svg xmlns="http://www.w3.org/2000/svg" style="display:none">
    <symbol id="tx-myextension" viewBox="0 0 16 16">
        <g fill="currentColor">
            <path d="M13.408 3.546 7.913 1.087a1.002 1.002 0 0 0-.817 0L1.592 3.545c-.36.161-.592.519-.592.914v7.102a1 1 0 0 0 .594.914l5.496 2.439a1.003 1.003 0 0 0 .812 0l5.504-2.446a1 1 0 0 0 .594-.914V4.459a1 1 0 0 0-.592-.913zM7.504 2l4.89 2.187L7.5 6.449 2.607 4.188 7.504 2zM2 5.01l5 2.31v6.46l-5-2.219V5.01zm6 8.766V7.32l5-2.31v6.545l-5 2.221z"/>
        </g>
    </symbol>
</svg>

```

The fragment identifier (`#tx-myextension`) is used to reference the symbol
from the SVG sprite when registering the icon.

### Icon provider {#icon-registration-icon-provider}

The TYPO3 Core ships three icon providers which can be used straight away:

-   `\TYPO3\CMS\Core\Imaging\IconProvider\BitmapIconProvider` – For all
    kinds of bitmap icons (GIF, PNG, JPEG, etc.)
-   `\TYPO3\CMS\Core\Imaging\IconProvider\SvgIconProvider` – For SVG icons
-   `\TYPO3\CMS\Core\Imaging\IconProvider\SvgSpriteIconProvider` – For SVG
    icons bundled in an SVG sprite

If you need a custom icon provider, you can add your own by writing a
class which implements the
[EXT:core/Classes/Imaging/IconProviderInterface.php (GitHub)](https://github.com/typo3/typo3/blob/main/typo3/sysext/core/Classes/Imaging/IconProviderInterface.php).

## Using icons in your code {#icon-usage}

You can use the Icon API to receive icons in your PHP
code or directly in Fluid.

> [!NOTE]
> The icons are cached in the local storage of the client to reduce the workload off the server.
> During development, it might be necessary to clear the local storage in addition to the usual
> TYPO3 caches.

### The PHP way {#icon-usage-php-way}

You can use the `\TYPO3\CMS\Core\Imaging\IconFactory` to request an icon:

**EXT:my_extension/Classes/MyClass.php**

```php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension;

use TYPO3\CMS\Core\Imaging\IconFactory;
use TYPO3\CMS\Core\Imaging\IconSize;

final class MyClass
{
  public function __construct(
    private readonly IconFactory $iconFactory,
  ) {}

  public function doSomething()
  {
    $icon = $this->iconFactory->getIcon(
      'tx-myextension-action-preview',
      IconSize::SMALL,
      'overlay-identifier',
    );

    // Do something with the icon, for example, assign it to the view
    // $this->view->assign('icon', $icon);
  }
}

```

The following icon sizes are available as enum values:

-   `\TYPO3\CMS\Core\Imaging\IconSize::DEFAULT`: 1em, to scale with font
    size
-   `\TYPO3\CMS\Core\Imaging\IconSize::SMALL`: fixed to 16px
-   `\TYPO3\CMS\Core\Imaging\IconSize::MEDIUM`: fixed to 32px
    (used as default value in API parameters)
-   `\TYPO3\CMS\Core\Imaging\IconSize::LARGE`: fixed to 48px
-   `\TYPO3\CMS\Core\Imaging\IconSize::MEGA`: fixed to 64px

### The Fluid ViewHelper {#icon-usage-fluid-viewhelper}

You can also use the [Fluid core:icon ViewHelper](https://docs.typo3.org/other/typo3/view-helper-reference/main/en-us/Core/Icon.html#typo3-core-icon)
to render an icon in your view:

```html
{namespace core = TYPO3\CMS\Core\ViewHelpers}
<core:icon identifier="tx-myextension-svgicon" size="small" />
```

This will render the desired icon using an `img` tag. If you prefer having
the SVG inlined into your HTML (for example, for being able to change colors
with CSS), you can set the optional `alternativeMarkupIdentifier`
attribute to `inline`. By default, the icon will pick up the font color of
its surrounding element if you use this option.

**EXT:my_extension/Resources/Private/Templates/SomeTemplate.fluid.html (excerpt)**

```html
{namespace core = TYPO3\CMS\Core\ViewHelpers}
<core:icon
    identifier="tx-myextension-svgicon"
    size="small"
    alternativeMarkupIdentifier="inline"
/>
```

The following icon sizes are available:

-   `default`: 1em, to scale with font size
-   `small`: fixed to 16px (used as default value when not passed)
-   `medium`: fixed to 32px
-   `large`: fixed to 48px
-   `mega`: fixed to 64px

### The JavaScript way {#icon-usage-javascript-way}

In JavaScript, icons can be only fetched from the Icon Registry. To achieve this,
add the following dependency to your [ES6 module](https://docs.typo3.org/permalink/t3coreapi:backend-javascript-es6@main):
`@typo3/backend/icons`. In this section, the module is known as `Icons`.

The module has a single public method `getIcon()` which accepts up to five arguments:

-   **identifier**

    `|` *Condition:* required
    `|` *Type:* string
    `|`

    Identifier of the icon as registered in the Icon Registry.

-   **size**

    `|` *Condition:* required
    `|` *Type:* Sizes
    `|` *Default:* medium
    `|`

    Desired size of the icon. All values of the `Sizes` enum from
    `@typo3/backend/enum/icon-types` are allowed,
    these are:

    -   `default`:  1em, to scale with font size
    -   `small`: fixed to 16px
    -   `medium`: fixed to 32px (default)
    -   `large`: fixed to 48px
    -   `mega`: fixed to 64px

-   **overlayIdentifier**

    `|` *Condition:* optional
    `|` *Type:* string
    `|`

    Identifier of an overlay icon as registered in the Icon Registry.

-   **state**

    `|` *Condition:* optional
    `|` *Type:* string
    `|`

    Sets the state of the icon. All values of the `States` enum from
    `@typo3/backend/enum/icon-types` are
    allowed, these are: `default` and `disabled`.

-   **markupIdentifier**

    `|` *Condition:* optional
    `|` *Type:* string
    `|`

    Defines how the markup is returned. All values of the
    `MarkupIdentifiers` enum from `@typo3/backend/enum/icon-types` are
    allowed, these are: `default` and `inline`. Please note that
    `inline` is only meaningful for SVG icons.

The method `getIcon()` returns a AjaxResponse Promise object, as internally
an Ajax request is done.

Here is an example code how a usage of the JavaScript Icon API may look like:

**EXT:my_extension/Resources/Public/JavaScript/my-es6-module.js**

```js
import Icons from '@typo3/backend/icons.js';

class MyEs6Module {
    constructor() {
        // Get a single icon
        Icons.getIcon('spinner-circle-light', Icons.sizes.small, null, 'disabled').then((icon: string): void => {
            console.log(icon);
        });
    }
}

export default new MyEs6Module();
```

## Available icons {#available-icons}

The TYPO3 Core comes with a number of icons that may be used in your extensions.

To search for available icons, you can browse through
[TYPO3.Icons](https://typo3.github.io/TYPO3.Icons/).

## Migration {#icon-migration}

The Rector rule [\\Ssch\\TYPO3Rector\\TYPO311\\v4\\RegisterIconToIconFileRector](https://github.com/sabbelasichon/typo3-rector/blob/main/docs/all_rectors_overview.md#registericontoiconfilerector)
can be used for automatic migration.

For manual migration remove all calls
to `\TYPO3\CMS\Core\Imaging\IconRegistry::registerIcon()` from
your [`EXT:my_extension/ext_localconf.php`](../../ExtensionArchitecture/FileStructure/ExtLocalconf.md#file-extension-ext-localconf-php) and move the content to
[`Configuration/Icons.php`](../../ExtensionArchitecture/FileStructure/Configuration/Icons.md#file-extension-configuration-icons-php) instead.