iconpack
quellenform/t3x-iconpack
1.5
en
Stephan Kellermayr & Contributors
This document is published under the Open Publication License.
Mon, 13 Apr 2026 09:40:13 +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
fa7:. 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 webfont, sprites, inline SVG or as an SVG image without having to change the content in the database.
To illustrate this behavior better, here is an example.
Only the following code is always (!) stored in the database (RTE):
<span data-iconfig="fa7:solid,star"></span>How this code is then displayed in the backend and frontend depends on the
configured render and the icons provided by the respective iconpack.
In the case of Font Awesome 7, for example, all possible types are provided:
The following possibilities are therefore available as render, which
are displayed in BE/FE as follows:
<svg viewBox="0 0 576 512" class="iconpack fas fa-star" fill="currentColor" aria-hidden="true">
<path d="M316.9 18C311.6 7 300.4 0 288.1 0s-23.4 7-28.8 18L195 150.3 51.4 171.5c-12 1.8-22 10.2-25.7 21.7s-.7 24.2 7.9 32.7L137.8 329 113.2 474.7c-2 12 3 24.2 12.9 31.3s23 8 33.8 2.3l128.3-68.5 128.3 68.5c10.8 5.7 23.9 4.9 33.8-2.3s14.9-19.3 12.9-31.3L438.5 329 542.7 225.9c8.6-8.5 11.7-21.2 7.9-32.7s-13.7-19.9-25.7-21.7L381.2 150.3 316.9 18z"></path>
</svg><svg class="iconpack fas fa-star" fill="currentColor" viewBox="0 0 576 512" aria-hidden="true">
<use href="/_assets/IDENTIFIER/Vendor/fontawesome-free-6.7.2-web/sprites/solid.svg#star"></use>
</svg><span class="iconpack fas fa-star" aria-hidden="true"></span><img class="iconpack fas fa-star" src="/_assets/IDENTIFIER/Vendor/fontawesome-free-6.7.2-web/svgs/solid/star.svg" loading="lazy" aria-hidden="true" alt="">The converters included in this extension ensure that only the most necessary code is stored in the database, and the output in BE/FE always corresponds to the configuration and requirements.
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
dynamically 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. Here you can choose between site sets, add classic TypoScript records, or write your own TypoScript.
New in version TYPO3 v13.1 / iconpack v1.2.6
If you are working with TYPO3 v12.4, use TypoScript Records.
The extension ships some TypoScript code which can be included in the site configuration via Site sets:
The extension ships some TypoScript code which needs to be included.
You can edit the corresponding template directly, or you can choose the following method (TYPO3 v12+):
Select Iconpack (iconpack) at the field Include TypoScript sets:
If you choose one of the two methods above, the following TypoScript constants are available for editing:
string
iconpack
Default CSS class: This classname will be the added in the frontend to all icons.
string
EXT:iconpack/Resources/Public/Css/Iconpack.min.css
Default CSS file: Use this CSS file as default in the frontend.
string
svgInline,svgSprite,webfont,svg
Render types order (Native fields): If an Iconpack provides one of the types defined here (separated by commas), it will be used in the frontend (the order is crucial!).
string
svgInline,svgSprite,webfont,svg
Render types order (RTE): If an Iconpack provides one of the types defined here (separated by commas), it will be used in the frontend (the order is crucial!).
If you do not choose either of the methods above or want to make individual configurations, you will need to define a few things in TypoScript so that the icons can be displayed in the frontend:
lib.parseFunc_RTE.nonTypoTagUserFunc Tip
Take a closer look at the content of
iconpack/ to make individual
adjustments.
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".
# You can also assign one (or more) of the valid values directly to the identifier of a specific iconpack, which will
# then affect both "native" and "rte" equally.
# 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
fa7 {
native = svgInline
}
mi = 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.
bool
1
If this option is enabled, icons are loaded in the RTE as SVG (inline, sprites) if they are available in the respective iconpack. Otherwise, only webfonts and IMG tags will be used instead, which results in a simpler format but may differ from the frontend appearance. Note: Clear the TYPO3 cache after changing this option!
This setting only affects the presentation of the icons used in the RTE, not the content stored in the database! When loading the content, an icon is generated as SVG via the iconfig string and displayed in the RTE. When saving, it is converted back and no real SVG code ever ends up in the database!
string
EXT:iconpack/Configuration/Iconpack/Default.yaml
Path to the YAML configuration file containing the default options for all installed iconpacks. Leave this field blank to disable it, or use your own configuration file. If you specify your own file here, it will overwrite the default options for all iconpacks, unless they contain their own options. Please also note that you must specify a corresponding CSS file for rendering the respective options in the YAML file with the key optionsCss (see example below).
string (list of keywords)
iconButton
Select how the icon field should be rendered in the backend.
This setting displays the icon next to an input field and a dedicated button:
This setting displays the input field next to an icon (as a button):
This setting displays the icon next to a dedicated button:
This setting displays only the icon, which also serves as the button:
Important
Changing the extension configuration requires an emptying of the TYPO3 cache for the changes to take effect!
If you deactivate autoConfigRte or autoAddAssets, 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:
# Allow <span> tags (webfont)
- span(*)[!data-iconfig,id,name,class,style,alt,title]{color,background*,margin,padding,align,vertical-align}
# Allow SVG images (svg)
- img[!data-iconfig,id,name,class,style,alt,title]{margin,padding,align,vertical-align}
extraPlugins:
- iconpackIf you have also enabled the rteSvg option via the extension configuration, you will need to allow various SVG elements in CKEditor4 as well (in CKEditor5, this is done automatically via the model schema of the CKEditor plugin):
editor:
config:
extraAllowedContent:
# Allow SVG (svgInline, svgSprite)
# svgGlobalAttributes = class,id,title
# svgPresentationAttributes = clip-path,clip-rule,color,display,fill,fill-opacity,fill-rule,filter,mask,opacity,shape-rendering,stroke,stroke-dasharray,stroke-dashoffset,stroke-linecap,stroke-linejoin,stroke-miterlimit,stroke-opacity,stroke-width,transform,visibility
- svg(*)[!data-iconfig,name,style,alt,width,height,fill,viewBox,xmlns,xmlns:xlink,class,id,title,clip-path,clip-rule,color,display,fill,fill-opacity,fill-rule,filter,mask,opacity,shape-rendering,stroke,stroke-dasharray,stroke-dashoffset,stroke-linecap,stroke-linejoin,stroke-miterlimit,stroke-opacity,stroke-width,transform,visibility]{color,background*,margin,padding,align,vertical-align}
- use[href,xlink:href,x,y,width,height,class,id,title,clip-path,clip-rule,color,display,fill,fill-opacity,fill-rule,filter,mask,opacity,shape-rendering,stroke,stroke-dasharray,stroke-dashoffset,stroke-linecap,stroke-linejoin,stroke-miterlimit,stroke-opacity,stroke-width,transform,visibility]
- title[id]
- desc[id]
- defs[class,id,title,clip-path,clip-rule,color,display,fill,fill-opacity,fill-rule,filter,mask,opacity,shape-rendering,stroke,stroke-dasharray,stroke-dashoffset,stroke-linecap,stroke-linejoin,stroke-miterlimit,stroke-opacity,stroke-width,transform,visibility]
- linearGradient[gradientUnits,gradientTransform,spreadMethod,x1,x2,y1,y2,class,id,title,clip-path,clip-rule,color,display,fill,fill-opacity,fill-rule,filter,mask,opacity,shape-rendering,stroke,stroke-dasharray,stroke-dashoffset,stroke-linecap,stroke-linejoin,stroke-miterlimit,stroke-opacity,stroke-width,transform,visibility]
- radialGradient[gradientUnits,gradientTransform,spreadMethod,cx,cy,fr,fx,fy,r,class,id,title,clip-path,clip-rule,color,display,fill,fill-opacity,fill-rule,filter,mask,opacity,shape-rendering,stroke,stroke-dasharray,stroke-dashoffset,stroke-linecap,stroke-linejoin,stroke-miterlimit,stroke-opacity,stroke-width,transform,visibility]
- g(*)[class,id,title,clip-path,clip-rule,color,display,fill,fill-opacity,fill-rule,filter,mask,opacity,shape-rendering,stroke,stroke-dasharray,stroke-dashoffset,stroke-linecap,stroke-linejoin,stroke-miterlimit,stroke-opacity,stroke-width,transform,visibility]
- stop[stop-color,stop-opacity,offset,class,id,title,clip-path,clip-rule,color,display,fill,fill-opacity,fill-rule,filter,mask,opacity,shape-rendering,stroke,stroke-dasharray,stroke-dashoffset,stroke-linecap,stroke-linejoin,stroke-miterlimit,stroke-opacity,stroke-width,transform,visibility]
- line[x1,y1,x2,y2,clip-path,clip-rule,color,display,fill,fill-opacity,fill-rule,filter,mask,opacity,shape-rendering,stroke,stroke-dasharray,stroke-dashoffset,stroke-linecap,stroke-linejoin,stroke-miterlimit,stroke-opacity,stroke-width,transform,visibility]
- path[!d,style,clip-path,clip-rule,color,display,fill,fill-opacity,fill-rule,filter,mask,opacity,shape-rendering,stroke,stroke-dasharray,stroke-dashoffset,stroke-linecap,stroke-linejoin,stroke-miterlimit,stroke-opacity,stroke-width,transform,visibility]
- polyline[!points,clip-path,clip-rule,color,display,fill,fill-opacity,fill-rule,filter,mask,opacity,shape-rendering,stroke,stroke-dasharray,stroke-dashoffset,stroke-linecap,stroke-linejoin,stroke-miterlimit,stroke-opacity,stroke-width,transform,visibility]
- polygon[!points,clip-path,clip-rule,color,display,fill,fill-opacity,fill-rule,filter,mask,opacity,shape-rendering,stroke,stroke-dasharray,stroke-dashoffset,stroke-linecap,stroke-linejoin,stroke-miterlimit,stroke-opacity,stroke-width,transform,visibility]
- rect[width,height,x,y,rx,ry,clip-path,clip-rule,color,display,fill,fill-opacity,fill-rule,filter,mask,opacity,shape-rendering,stroke,stroke-dasharray,stroke-dashoffset,stroke-linecap,stroke-linejoin,stroke-miterlimit,stroke-opacity,stroke-width,transform,visibility]
- circle[cx,cy,r,clip-path,clip-rule,color,display,fill,fill-opacity,fill-rule,filter,mask,opacity,shape-rendering,stroke,stroke-dasharray,stroke-dashoffset,stroke-linecap,stroke-linejoin,stroke-miterlimit,stroke-opacity,stroke-width,transform,visibility]
- ellipse[cx,cy,rx,ry,clip-path,clip-rule,color,display,fill,fill-opacity,fill-rule,filter,mask,opacity,shape-rendering,stroke,stroke-dasharray,stroke-dashoffset,stroke-linecap,stroke-linejoin,stroke-miterlimit,stroke-opacity,stroke-width,transform,visibility]editor:
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/)
The defaultConfig option defines a YAML file that controls the default options for all installed iconpacks. You can edit this file as you wish so that you can use your own transformations and animations. Please note, however, that the values used here will also be stored in the database, so you should use these settings with caution.
iconpack:
optionsCss:
transforms: "EXT:iconpack/Resources/Public/Css/IconpackTransforms.min.css"
options:
size:
type: "select"
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:label.size"
values:
xs:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:size.xs"
attributes:
class: "iconpack-xs"
sm:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:size.sm"
attributes:
class: "iconpack-sm"
md:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:size.md"
attributes:
class: "iconpack-md"
lg:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:size.lg"
attributes:
class: "iconpack-lg"
1x:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:size.1x"
attributes:
class: "iconpack-1x"
2x:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:size.2x"
attributes:
class: "iconpack-2x"
3x:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:size.3x"
attributes:
class: "iconpack-3x"
4x:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:size.4x"
attributes:
class: "iconpack-4x"
5x:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:size.5x"
attributes:
class: "iconpack-5x"
6x:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:size.6x"
attributes:
class: "iconpack-6x"
7x:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:size.7x"
attributes:
class: "iconpack-7x"
8x:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:size.8x"
attributes:
class: "iconpack-8x"
9x:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:size.9x"
attributes:
class: "iconpack-9x"
10x:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:size.10x"
attributes:
class: "iconpack-10x"
decoration:
type: "select"
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:label.decoration"
values:
border:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:decoration.border"
attributes:
class: "iconpack-border"
transform:
type: "select"
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:label.transform"
values:
r90:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:transform.90"
attributes:
class: "iconpack-rotate-90"
r180:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:transform.180"
attributes:
class: "iconpack-rotate-180"
r270:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:transform.270"
attributes:
class: "iconpack-rotate-270"
fx:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:transform.flipHorizontal"
attributes:
class: "iconpack-flip-horizontal"
fy:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:transform.flipVertical"
attributes:
class: "iconpack-flip-vertical"
fxy:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:transform.flipBoth"
attributes:
class: "iconpack-flip-both"
beat:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:transform.beat"
attributes:
class: "iconpack-beat"
bounce:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:transform.bounce"
attributes:
class: "iconpack-bounce"
fade:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:transform.fade"
attributes:
class: "iconpack-fade"
beat-fade:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:transform.beat-fade"
attributes:
class: "iconpack-beat-fade"
flip:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:transform.flip"
attributes:
class: "iconpack-flip"
shake:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:transform.shake"
attributes:
class: "iconpack-shake"
spin:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:transform.spin"
attributes:
class: "iconpack-spin"
spin-pulse:
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:transform.spin-pulse"
attributes:
class: "iconpack-spin-pulse"
fixed:
type: "checkbox"
label: "LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:label.fixed"
attributes:
class: "iconpack-fw"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'
]
]
]
);You can also customize the input field to suit your needs and change the button however you like. Something like this:
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTCAcolumns(
'tt_content', [
'my_custom_field' => [
'label' => 'My Label',
'config' => [
'type' => 'user',
'renderType' => 'IconpackWizard'
'formElementStyle' => 'iconInputButton', // See extension configuration
'buttonIcon' => 'ext-iconpack', // Use 'false' to hide the button icon completely
'buttonLabel' => 'LLL:EXT:iconpack/Resources/Private/Language/locallang_be.xlf:js.label.iconNative',
'buttonTooltip' => 'My Custom Button Tooltip',
]
]
]
);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
}
}
}Note, however, that for this to work, all content must also be accepted by the HTMLparser, which is why — depending on the requirements or desired output — additional TypoScript may be necessary.
For example, if you need to output inline SVG, you may need the following TypoScript code:
# Here all tags are defined, which are NOT removed by the parser in principle.
# Without this instruction the content from the database will not be displayed in the frontend when using DataProcessor!
# If you use your own configuration, make sure that this statement is included at the end, or is not overwritten by other statements.
# Note: Even if you allow certain tags here, the sanitizer still decides whether these tags actually end up in the frontend or not!
lib.parseFunc_RTE.allowTags := addToList(icon, svg, use, g, line, path, polyline, polygon, rect, circle, ellipse, image, desc, defs, linearGradient, radialGradient, stop)If you don't use inline SVG, but only SVG sprites, you can also reduce this to the following statement:
lib.parseFunc_RTE.allowTags := addToList(svg, use)If you want to additionally restrict various attributes in SVG elements, use the following TypoScript:
lib.parseFunc_RTE.nonTypoTagStdWrap.HTMLparser.tags.svg.allowedAttribs = id, name, class, style, fill, viewBox, xmlns, width, height, role, aria-hiddenIcons 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="fa7: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!
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_.
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
render (svgInline, svgSprites, svg, webfont).
Simply clone the repository and follow the instructions in the README.md file.
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
# 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-icon2The 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"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-icon2If you want to configure aliases.yml (which replaces the previous method), use the following:
icon1:
- old-icon1
- very-old-icon1
icon2: old-icon2The 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 (with a fallback from top to bottom):
If you want to overwrite or customize these settings later, you can do this via TypoScript:
plugin.tx_iconpack.settings.renderTypes.mci = svgIn the backend, the order of the render 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 rte
option in the extension settings, it will also be:
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"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_ci/Resources/Public/Css/CustomWebfont.css"
prefix: "ci-"
attributes:
class: "ci"
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-"
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: "fa7"
# This iconpack replaces all icons from previous versions with the identifiers "fa5" and "fa6"
replaces: "fa5,fa6"
version: "7.1.0"
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"
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"
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"
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/"
# If you specify your own options here, they will be used instead of the default options.
# Please note that you must also use the corresponding CSS in the renderTypes above.
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/metadata/categories.yml"
# The icons in this iconpack (mandatory)
icons: "EXT:iconpack_fontawesome/Resources/Public/metadata/icons.yml"
# Alternative 1: Use a JSON-file
#icons: "EXT:iconpack_fontawesome/Resources/Public/metadata/icons.json"
# Alternative 2: Define the icons as array
#icons:
# - icon1
# - icon2
# - icon3
# Aliases for specific icons
aliases: "EXT:iconpack_fontawesome/Resources/Public/metadata/aliases.yaml"The 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.4.1
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/svgs/%1$s/"
svgSprite:
source: "EXT:iconpack_typo3/Resources/Public/Vendor/TYPO3.Icons/sprites/%1$s.svg"
svgInline:
source: "EXT:iconpack_typo3/Resources/Public/Vendor/TYPO3.Icons/svgs/%1$s/"Every good idea and extension depends on whether it is used, accepted by the community and whether it is financially supported. Therefore...
I would like to thank everyone who contributed in any way to the creation of this extension, but especially:
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!