iconpack
quellenform/t3x-iconpack
1.1
en
Stephan Kellermayr & Contributors
This document is published under the Open Publication License.
Mon, 02 Jun 2025 19:01:49 +0000
Table of Contents
This extension provides an iconpack registry for custom iconpacks which can be used in backend and frontend and are rendered according to the configuration of the installed iconpacks.
The idea behind the extension is to provide a flexible system by means of which any icon sets can be used and the desired output can be generated at any time by separating storage and rendering.
The extension iconpack is different from previous implementations and will
probably be the only icon extension you will need in the future.
The biggest differences are among others:
Instead of storing the entire HTML markup or a static file path for an icon in
the database fields, a short configuration string is stored instead (also in the
RTE). This string is called "iconfig" and looks something like
fa6:. This example will render the icon Star from
the iconpack Font Awesome 6 (solid style) with the additional property of a
spinnig rotation.
This string is only converted into HTML code according to the configuration during rendering in the backend or frontend, which ensures the greatest possible flexibility. It is possible to choose whether the icons are to be rendered as a web font, sprites, inline SVG or as an SVG image without having to change the content in the database.
Furthermore, this extension adds additional icon fields for pages and text headers, but it can also be used to extend fields of your own extensions.
Note
This extension does NOT have the same approach as the TYPO3 integrated
Icon with its approach to cache all icons including their HTML
markup for the backend and consider them as absolute, but focuses on
handling icons for editors and frontend output!
Install this extension from TER or with Composer:
composer require quellenform/t3x-iconpackInstall one of the existing iconpack providers:
Add the provided TypoScript to your template
(Make sure that lib. is not overwritten by any subsequent templates!)
[Optional] Install the Iconpack for Bootstrap Package extension
...if you want to use Iconpack with Bootstrap Package and want to replace the hard-coded icons with a better and flexible system.
Note
If you use EXT:bootstrap_package_iconpack, make sure
you include the templates at the end, otherwise lib. will be
overwritten by EXT:bootstrap_package and the icons cannot
be displayed.
Note
If you are using your own templates for the header, please note that a ViewHelper is used to display icons. In this case, simply take a look at the supplied template and migrate these settings.
The Extension works out of the box and configures all relevant parameters automatically.
Only the TypoScript needs to be inserted in order to obtain a display in the frontend:
To enable the icons to be output in the frontend, a few things need to be defined in the TypoScript:
lib.parseFunc_RTE.nonTypoTagUserFunc All these values can of course be overwritten individually.
Tip
Take a closer look at the content of
iconpack/ to make individual
adjustments.
If you want to keep the default settings, simply add the TypoScript provided at the end of your setup:
Note
If you use EXT:bootstrap_package_iconpack, make sure
you include the templates at the end, otherwise lib. will be
overwritten by EXT:bootstrap_package and the icons cannot
be displayed by the RTE.
The basic representation of icons is defined in the respective iconpack via the "renderTypes" key, and can be subsequently overwritten at any time using TypoScript for the frontend. The defined values are keywords separated by commas, which represent a sequence. If an iconpack does not contain the requested renderType, the next defined renderType is used.
To override the default settings for rendering iconpacks, the key
plugin. is created in the template or in the
respective page. The settings can apply to all iconpacks with the key
_default, or can refer to a specific iconpack.
The following examples show such a configuration for the frontend.
The settings for the frontend are made in the TypoScript Setup. Rendering in
the frontend is done via data, which can be assigned to any custom
fields.
# Typoscript setup
plugin.tx_iconpack {
settings {
# If you change the CSS class, please also note that you have to change it in your CSS files accordingly!
# You can also remove this completely if you don't need it.
cssClass = {$plugin.tx_iconpack.cssClass}
# Define the order of the renderTypes here.
# If an Iconpack provides one of the types defined here (separated by commas), it will be used (the order is crucial!).
# This can be specified differently for icons from a field or the RTE with the keys "native" and "rte".
# Available values: svgInline, svgSprite, webfont, svg
renderTypes {
# Override default values for all iconpacks
_default {
native = svgSprite, webfont
rte = webfont
}
# Override values only for specific iconpacks by using their key
fa6 {
native = svgInline
}
glyphicons = webfont
}
}
}You can control whether the required assets should be included automatically and whether the CKEditor should be configured automatically.
Some iconpacks also offer the option of choosing between different icon set versions and other options. These settings are made in the extension configuration of the respective iconpack.
The following settings are currently available:
bool
1
If enabled, the CKEditor will be configured automatically (no PageTS needed), so that the icons inserted in the RTE and their values are preserved when saving. If this option is disabled, these parameters must be inserted manually in the custom YAML configuration for the CKEditor.
bool
1
If enabled, all CSS files required by the installed iconpacks are automatically included in the frontend.
Important
Changing the extension configuration requires an emptying of the TYPO3 cache for the changes to take effect!
If you deactivate these settings, however, you will have to make the required configuration yourself and integrate it into your own setup. Use the following two examples...
editor:
externalPlugins:
iconpack: { resource: 'EXT:iconpack/Resources/Public/JavaScript/v11/CKEditor/plugin.js' }
config:
# Note: CSS files required by specific iconpacks is loaded automatically!
contentsCss:
- 'EXT:iconpack/Resources/Public/Css/Backend/CKEditor.min.css'
# This configuration is necessary so that certain contents can be inserted in CKEditor4 in the first place.
# All values defined here finally end up in the RTE and can be edited there.
#
# Note, however, that these values are additionally filtered again with PHP when saving, and ultimately only the attributes
# defined here are actually stored in the database. In addition, for the output in the frontend on the one hand the
# RteHtmlParser is used and on the other hand the Sanitizer, which finally decides which output ends up in the FE.
#
# More information about the RTE content filter can be found here:
# https://ckeditor.com/docs/ckeditor4/latest/examples/acfcustom.html
# https://ckeditor.com/docs/ckeditor4/latest/guide/dev_advanced_content_filter.html
#
extraAllowedContent:
# webfont: Allow <span> tags
- span(*)[!data-iconfig,id,name,class,style,alt,title]{color,background*,margin,padding,align,vertical-align}
# image: Allow svg images
- img[!data-iconfig,id,name,class,style,alt,title]{margin,padding,align,vertical-align}
extraPlugins:
- iconpackeditor:
config:
# Note: CSS files required by specific iconpacks is loaded automatically!
contentsCss:
- 'EXT:iconpack/Resources/Public/Css/Backend/CKEditor.min.css'
# Load modules for plugins when CKEditor is initialized
# See CKEditor plugin API for details
importModules:
- { module: '@quellenform/iconpack-ckeditor.js', exports: [ 'Iconpack' ] }
toolbar:
items:
- '|'
- Iconpack(Please take at look at the examples, located in Configuration/RTE/)
You can also use Iconpack in your own extensions and add the wizard to your own database fields as well as the RTE.
The wizard for adding icons can be used arbitrarily in own database fields. To
do this, simply assign the value Iconpack to the render of the
corresponding field.
Here is an example with /Configuration/:
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTCAcolumns(
'tt_content', [
'my_custom_field' => [
'label' => 'My Label',
'config' => [
'type' => 'user',
'renderType' => 'IconpackWizard'
]
]
]
);If you want to use Iconpack in your own RTE fields, the configuration is done
automatically in the TypoScript setup, where lib.
performs the transformation of the icons.
If this is not desired or possible, the content can optionally be preprocessed in the field via a DataProcessor.
Use the following TypoScript to add the DataProcessor to your own RTE field:
# Set templates and dataProcessing
lib.contentElement {
dataProcessing {
# This is required to render icons in RTE fields!
# The output is controlled exclusively by the DataProcessor and then cleaned up by the Sanitizer.
[number] = Quellenform\Iconpack\DataProcessing\IconpackProcessor
[number] {
fieldName = myCustomRteField
fieldType = rte
}
}
}Icons can be inserted directly from a fluid template using the provided
ViewHelper. All that needs to be done is to add the namespace
http:// and a corresponding
iconfig string. Optionally additional, preferred and
style can be used.
<html xmlns:i="http://typo3.org/ns/Quellenform/Iconpack/ViewHelpers" data-namespace-typo3-fluid="true">
<i:icon iconfig="{headerIcon}" preferredRenderTypes="svgInline,webfont" />
</html>You can also call up a specific icon directly from Fluid:
<i:icon iconfig="fa6:brands,youtube" additionalAttributes="{class:'social'}" />Any custom iconsets can be registered and provided via custom extensions.
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_.
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.woffThe 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
render 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
- ...
- ...
- iconZThe iconpack is then registered in the Iconpack via ext_
<?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'
);
}Depending on which render your iconpack provides (in this simple example
we have webfonts and SVG icons), these are selected by default in the following
order (fallback):
If you want to overwrite or customize these settings, you can do this via TypoScript:
plugin.tx_iconpack.settings.overrides.renderTypes.mci = svgIn the backend, the order of the render for native fields and the RTE is
predefined differently, as the respective version of the CKEditor plays a role
here.
For native fields:
And for all RTE fields (as the implementation does not yet allow SVG elements in all TYPO3 versions):
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"Detailed information on the use of YAML can be found (https://www.w3schools.io/file/yaml-arrays/.
iconpack:
title: "Custom Icons"
key: "ci"
version: "1.0"
renderTypes:
webfont:
css: "EXT:iconpack_mfg/Resources/Public/Css/CustomWebfont.css"
prefix: "mfg-"
attributes:
class: "mfg"
aria-hidden: "true"
role: "img"
icons:
- cloud
- at
- plus
- minus
- arrow_up
- arrow_down
- arrow_right
- arrow_lefticonpack:
title: "Bootstrap Icons"
key: "bi1"
version: 1.10.2
url: "https://icons.getbootstrap.com/"
renderTypes:
webfont:
css: "EXT:iconpack_bootstrap/Resources/Public/Vendor/icons-1.10.2/font/bootstrap-icons.css"
prefix: "bi-"
attributes:
aria-hidden: "true"
role: "img"
image:
source: "EXT:iconpack_bootstrap/Resources/Public/Vendor/icons-1.10.2/icons/"
attributes:
class: "bi"
svgSprite:
source: "EXT:iconpack_bootstrap/Resources/Public/Vendor/icons-1.10.2/bootstrap-icons.svg"
attributes:
class: "bi"
fill: "currentColor"
svgInline:
source: "EXT:iconpack_bootstrap/Resources/Public/Vendor/icons-1.10.2/icons/"
attributes:
class: "bi"
fill: "currentColor"
icons: "EXT:iconpack_bootstrap/Resources/Public/Vendor/icons-1.10.2/font/bootstrap-icons.json"iconpack:
# The title which is used in the backend [mandatory]
title: "Fontawesome Icons 5 (mod)"
# The main key for this iconpack [mandatory]
key: "fa5"
version: "5.15.4"
url: "https://fontawesome.com/"
# Override predefined preferred renderTypes (The first available type is selected) [optional]
preferredRenderTypes:
backend:
native: "svgSprite,svgInline,webfont,svg"
rte: "webfont,svg"
frontend:
native: "svgInline,svgSprite,webfont,svg"
rte: "svgInline,svgSprite,webfont,svg"
# Use only the following styles, even if others would be available in principle
stylesEnabled: "regular,solid,brands"
renderTypes:
# Default values (Always included in all renderTypes!)
_default:
# Default values (Always included in all styles!)
_default:
prefix: "fa-"
#attributes:
# Note: Individual classes can be added here.
#class: "XXX XXX2 XXX3"
# Note: Individual styles can be added here.
#style: "color:white;background-color:red"
css:
# Included in all styles but only in CKEditor
ckeditor: "EXT:iconpack_fontawesome/Resources/Public/Css/CustomStylesForCKEditor.css"
regular:
# Note: Language specific labels possible:
#label: "LLL:EXT:iconpack_xxx/Resources/Private/Language/locallang_be.xlf:label"
label: "FontAwesome (Regular)"
attributes:
class: "far"
#style: "background-color:green"
solid:
label: "FontAwesome (Solid)"
attributes:
class: "fas"
brands:
label: "FontAwesome (Brands)"
attributes:
class: "fab"
webfont:
_default:
css:
# Include in all webfonts-styles in all scopes (backend, CKEeditor, frontend)
shared: "EXT:iconpack_fontawesome/Resources/Public/Css/StylesForAllWebfonts.css"
attributes:
aria-hidden: "true"
role: "img"
regular:
css: "EXT:iconpack_fontawesome/Resources/Public/Css/regular.css"
solid:
css: "EXT:iconpack_fontawesome/Resources/Public/Css/solid.css"
brands:
css: "EXT:iconpack_fontawesome/Resources/Public/Css/brands.css"
svgSprite:
_default:
css:
backend: "EXT:iconpack_fontawesome/Resources/Public/Css/SvgBackend.css"
ckeditor: "EXT:iconpack_fontawesome/Resources/Public/Css/SvgBackend.css"
frontend: "EXT:iconpack_fontawesome/Resources/Public/Css/SvgFrontend.css"
attributes:
fill: "currentColor"
role: "img"
regular:
source: "EXT:iconpack_fontawesome/Resources/Public/Sprites/regular.svg"
solid:
source: "EXT:iconpack_fontawesome/Resources/Public/Sprites/solid.svg"
brands:
source: "EXT:iconpack_fontawesome/Resources/Public/Sprites/brands.svg"
svgInline:
_default:
css:
backend: "EXT:iconpack_fontawesome/Resources/Public/Css/SvgBackend.css"
ckeditor: "EXT:iconpack_fontawesome/Resources/Public/Css/SvgBackend.css"
frontend: "EXT:iconpack_fontawesome/Resources/Public/Css/SvgFrontend.css"
attributes:
fill: "currentColor"
role: "img"
regular:
source: "EXT:iconpack_fontawesome/Resources/Public/Svg/regular/"
solid:
source: "EXT:iconpack_fontawesome/Resources/Public/Svg/solid/"
brands:
source: "EXT:iconpack_fontawesome/Resources/Public/Svg/brands/"
options:
customCheckbox:
type: "checkbox"
label: "My Special Effect"
attributes:
class: "fa-special"
customStyles:
type: "select"
label: "Custom CSS-Style"
values:
red:
label: "Red"
attributes:
style: "color: red"
green:
label: "Green"
attributes:
style: "color: green"
categories: "EXT:iconpack_fontawesome/Resources/Public/Vendor/fontawesome-free-5.15.4-web/metadata/categories.yml"
# The icons in this iconpack (mandatory)
icons: "EXT:iconpack_fontawesome/Resources/Public/Vendor/fontawesome-free-5.15.4-web/metadata/icons.yml"
# Alternative 1: Use a JSON-file
#icons: "EXT:iconpack_fontawesome/Resources/Public/Vendor/fontawesome-free-5.15.4-web/metadata/icons.json"
# Alternative 2: Define the icons as array
#icons:
# - icon1
# - icon2
# - icon3The following example shows the setting in which parts of a path are replaced with parts of an icon identifier.
For example, the identifier is actions-, which in the case of an SVG
sprite leads to the path
EXT:,
or in the case of an SVG to
EXT:.
iconpack:
title: "TYPO3 Icons"
key: "t3"
version: 4.1.0
url: "https://typo3.github.io/TYPO3.Icons/"
renderTypes:
_default:
css: "EXT:iconpack_typo3/Resources/Public/Css/t3-icons.min.css"
prefix: "t3-"
svg:
source: "EXT:iconpack_typo3/Resources/Public/Vendor/TYPO3.Icons-4.1.0/svgs/%1$s/"
svgSprite:
source: "EXT:iconpack_typo3/Resources/Public/Vendor/TYPO3.Icons-4.1.0/sprites/%1$s.svg"
svgInline:
source: "EXT:iconpack_typo3/Resources/Public/Vendor/TYPO3.Icons-4.1.0/svgs/%1$s/"
attributes:
role: "img"Every good idea and extension depends on whether it is used, accepted by the community and whether it is financially supported. Therefore...
All notable changes to this project will be documented in this file.
First stable version...
<title> and alt to <desc>)<icon> to <span> for better compatibility! Due
to a lack of funding for the project, there is unfortunately no upgrade wizard
for this, but there is at least downward compatibility in the frontend. To
update your content and switch to the new tag, simply open the data record for
editing and save it again....because this feature is simply missing in TYPO3!
Various existing extensions have so far only ever handled a single iconpack, and even that was not optimally integrated into TYPO3. Most of them can either only be used in the RTE, and others only in a single additional field. All extensions so far also lack the possibility to influence the icon rendering afterwards. Furthermore, other extensions don't really offer the possibility to use an icon set flexibly in their own database fields and to achieve a consistent rendering across the whole website.
It took me several months to find out how an optimal flexible iconpack system should work. There is still room for improvement in the programming, but I tried to create a mechanism that offers the greatest possible flexibility and consistency for current and future requirements by analyzing various icon sets and extensive testing.
The main focus for me was that every possible icon set should be able to be used with it, and at the same time it should be possible to use it in all TYPO3 fields (native fields, RTE, fields in own extensions, ...).
Another focus was on the extensibility and modification of existing iconpack extensions. These should be integrated into the system as easy as possible (YAML file).
I wrote this extension at the end of 2020, and unfortunately didn't make it public right then.
The reason why the whole thing is now published by me after all is that I am convinced that such a system can really help to improve and simplify the handling with icons in TYPO3.
If you think that this is also a step in the right direction for you and you have wishes, thanks or improvements, please share your contribution!