Icon API

Icon provider

The TYPO3 Core ships two 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

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).

The PHP way

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

<?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-myext-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

You can also use the Fluid core:icon ViewHelper to render an icon in your view:

{namespace core = TYPO3\CMS\Core\ViewHelpers}
<core:icon identifier="tx-myext-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.

{namespace core = TYPO3\CMS\Core\ViewHelpers}
<core:icon
    identifier="tx-myext-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

In JavaScript, icons can be only fetched from the Icon Registry. To achieve this, add the following dependency to your ES6 module: @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.

The icons are cached in the local storage of the client to reduce the workload off the server. Here is an example code how a usage of the JavaScript Icon API may look like:

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();