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
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!

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.

Iconpack Kickstarter

If you want to take the easy route and create a ready-to-use iconpack from SVG files, you can use the Iconpack Kickstarter, which allows you to create a complete iconpack and includes all the necessary renderTypes (svgInline, svgSprites, svg, webfont).

Simply clone the repository and follow the instructions in the README.md file.

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
   # Set this value to "true" if you want to hide your iconpack in dropdown menus in the BE.
   # This is useful if you only want to use it in FE/ViewHelpers
   #   Default value: false
   hidden: false

   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"

   # Optional categories for the backend modal.
   # All icons not listed here can be displayed using ViewHelper,
   # but cannot be selected in the backend modal wizard!!!
   categories:
      cat1:
         icons:
            - icon1
            - icon2
            - icon3
            - ...
         label: "Category 1"
      cat2:
         icons:
            - icon4
            - icon5
            - icon6
            - ...
         label: "Category 2"

   # 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

   # Aliases for obsolete icons.
   # Here you can list those icons that have been replaced by this particular version of the icon pack.
   aliases:
      icon1:
         - old-icon1
         - old-icon2

The keys "categories", "icons" and "aliases" can be used directly in the main configuration with arrays, but it is also possible to refer to a YAML or JSON file instead. External configuration of these values is particularly recommended if the number of icons is very high or if better maintainability is required.

# Icon categories for listing in the modal window (BE only)
categories: "EXT:iconpack_customicons/Resources/Public/Metadata/categories.yml"

# The icons in this iconpack
icons: "EXT:iconpack_customicons/Resources/Public/Metadata/icons.yml"
# Alternative: Use a JSON-file
#icons: "EXT:iconpack_customicons/Resources/Public/Metadata/icons.json"

# Aliases for specific icons
aliases: "EXT:iconpack_customicons/Resources/Public/Metadata/aliases.yaml"

Aliases

It may happen that some icons are removed from newer versions of certain iconpacks. Aliases are used to register these icons and provide replacements for them. Essentially, this simply involves replacing icon identifiers, with an alias specifying which icon should be replaced by which other icon.

Aliases can be used in external configuration files in two ways: - Either directly in the "icons" key/array - Or in a separate file in the "aliases" key/array

If you use the "aliases" key or your own file for storing aliases, any aliases stored directly in the "icons" key will be ignored!

If the configuration is done in icons.yml, use the following structure:

icon1:
   aliases:
      - old-icon1
      - very-old-icon1
icon2:
   aliases: old-icon2

If you want to configure aliases.yml (which replaces the previous method), use the following:

icon1:
   - old-icon1
   - very-old-icon1
icon2: old-icon2

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 (with a fallback from top to bottom):

svgInline
svgSprite
webfont
svg

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

plugin.tx_iconpack.settings.renderTypes.mci = svg

Rendering in the Backend

In the backend, the order of the renderTypes for native fields and the RTE is predefined in the source code.

Unless you explicitly change this order in your YAML file or disable the rteSvg option in the extension settings, it will also be:

svgInline
svgSprite
webfont
svg

Customizing the Rendering Sequence

If you want to change the order of rendering fallbacks or specify only a specific renderType (which in both cases would only make sense in exceptional cases), you can add the following setting to the YAML configuration:

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