Creating your own Iconpack Provider

Any custom iconsets can be registered and provided via custom extensions.

Iconsets that meet at least one of the following criteria can be used:

Available as webfont
Available as SVG sprite (preferred)
Available as single SVG icons

An individual Iconpack extension consists of the necessary assets (SVG files, StyleSheets, etc.) and a configuration file, which is described below.

Tip

Have a look at the existing extensions!

Important

Currently only webfonts and SVG images are possible in the RTE, although SVG sprites are already implemented in CKEditor 4. The implementation in CKEditor 5 for TYPO3 v12 will follow. However, the output in the frontend is independent of this and always takes place in the selected format.

Note

If you are so kind and want to make your iconpack extension available to the community, it would be great if you use the name iconpack_* as extension key, e.g. iconpack_supericons.

The Structure of an Iconpack Extension

The structure for your own iconpack extension, which consists of SVG icons and a webfont, for example, looks something like this:

iconpack_customicons
├── composer.json
├── Configuration
│   └── MyCustomIconpack.yaml
├── ext_emconf.php
├── ext_localconf.php
└── Resources
   └── Public
      ├── Css
      │   └── webfont.css
      ├── Icons
      │   ├── Extension.svg
      │   ├── icon1.svg
      │   ├── icon2.svg
      │   ├── icon3.svg
      │   ├── ...
      │   ├── ...
      │   └── iconZ.svg
      └── Fonts
         ├── my-custom-iconpack.eot
         ├── my-custom-iconpack.svg
         ├── my-custom-iconpack.ttf
         └── my-custom-iconpack.woff

Create a Configuration for your Iconpack

The iconpack itself is configured via the YAML file. In this file, the basic information about the iconpack is recorded and the definitions for the available renderTypes are specified:

Caution

The key of an iconpack should be chosen wisely and should not be changed, as it is used to identify the iconpack and this value is also saved in the database!

iconpack:
   title: "My Custom Icons"
   # The key of the iconpack (!)
   key: "mci"
   version: 1.0.0

   renderTypes:
      webfont:
         # CSS file that is used for web fonts:
         css: "EXT:iconpack_customicons/Resources/Public/Css/webfont.css"
         # CSS prefix for the icons:
         prefix: "mci-"
         # Attributes to be used by default:
         attributes:
            aria-hidden: "true"
            role: "img"

      svg:
         # Source folder of the SVG files, which are rendered as <img> tag:
         source: "EXT:iconpack_customicons/Resources/Public/Icons/"
         attributes:
            class: "mci"

      svgInline:
         # Source folder of the SVG files that are rendered as <svg> tag (inline SVG):
         source: "EXT:iconpack_customicons/Resources/Public/Icons/"
         attributes:
            class: "mci"
            fill: "currentColor"

   # Define here which icons are provided by this iconpack
   # In this case, the values here correspond to the file names (without file name extension)
   icons:
      - icon1
      - icon2
      - icon3
      - ...
      - ...
      - iconZ

Register your Iconpack

The iconpack is then registered in the IconpackRegistry via ext_localconf.php

<?php

defined('TYPO3') || die();

if (\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::isLoaded('iconpack')) {
   \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(
      \Quellenform\Iconpack\IconpackRegistry::class
   )->registerIconpack(
      'EXT:iconpack_customicons/Configuration/MyCustomIconpack.yaml'
   );
}

Rendering in the Frontend

Depending on which renderTypes your iconpack provides (in this simple example we have webfonts and SVG icons), these are selected by default in the following order (fallback):

svgInline
svgSprite
webfont
svg

If you want to overwrite or customize these settings, you can do this via TypoScript:

plugin.tx_iconpack.settings.overrides.renderTypes.mci = svg

Rendering in the Backend

In the backend, the order of the renderTypes for native fields and the RTE is predefined differently, as the respective version of the CKEditor plays a role here.

For native fields:

svgSprite
svgInline
webfont
svg

And for all RTE fields (as the implementation does not yet allow SVG elements in all TYPO3 versions):

webfont
svg

Customizing the Rendering Sequence

If you want to change the order of the rendering fallback (which would only make sense in exceptional cases), you can add the following setup to the YAML configuration:

iconpack:
   preferredRenderTypes:
      backend:
         native: "svg"
         rte: "svg"
      frontend:
         native: "svg"
         rte: "svg"