PHPackages                             oliverthiele/ot-icons - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Templating & Views](/categories/templating)
4. /
5. oliverthiele/ot-icons

ActiveTypo3-cms-extension[Templating & Views](/categories/templating)

oliverthiele/ot-icons
=====================

ViewHelper for rendering icons in your FluidTemplates. The output can be changed from one icon set to another at a later date.

v1.0.0(6mo ago)0701GPL-2.0-or-laterPHP

Since Oct 20Pushed 5mo agoCompare

[ Source](https://github.com/oliverthiele/ot-icons)[ Packagist](https://packagist.org/packages/oliverthiele/ot-icons)[ Docs](https://www.oliver-thiele.de)[ RSS](/packages/oliverthiele-ot-icons/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (2)Versions (3)Used By (1)

ot-icons — Accessible SVG Icon Rendering for TYPO3
==================================================

[](#ot-icons--accessible-svg-icon-rendering-for-typo3)

🧩 Overview
----------

[](#-overview)

**ot-icons** is a TYPO3 extension that provides a modern, accessible and update-safe way to render SVG icons in Fluid templates. Instead of hardcoding paths or class names, icons are mapped via configuration files to ensure maximum flexibility and maintainability.

### ✨ Key Features

[](#-key-features)

- **Mapping-based icon resolution** — update or change icon sets (e.g., Font Awesome → Material Icons) without modifying templates.
- **Fully accessible SVG output** — automatic handling of `role`, `aria-hidden`, `aria-label`, and `` / `` tags.
- **Multiple output modes** — inline SVG, sprite-based, or Base64 (future).
- **Default styles per icon set** — each mapping file defines its default subdirectory (e.g., `solid/`).
- **Cache-optimized** — internal request cache plus TYPO3 caching with version-aware keys.

---

🚀 Motivation
------------

[](#-motivation)

In many TYPO3 projects, icons are still integrated via **hard-coded FontAwesome or Material classes** like ``. This approach works — until an icon set changes its naming, folder structure, or style conventions. Upgrading FontAwesome from 5 → 6 → 7 often means **manually fixing dozens of templates**.

**ot-icons** eliminates that problem.

By using *mapping files* and a clean Fluid API, you can **switch or upgrade entire icon sets**without touching a single Fluid template. Old identifiers are automatically translated to their new equivalents, keeping your templates clean and update-safe.

At the same time, **ot-icons** ensures that all SVGs are rendered with proper **accessibility semantics** — something most icon packs ignore:

- Decorative icons are automatically hidden from assistive technologies (`aria-hidden="true"`).
- Semantic icons receive the correct `role="img"` and accessible names via `` or `aria-label`.
- Optional `aria-description` tags allow extended screen-reader support.

Unlike many existing icon packs for TYPO3, **ot-icons** focuses on:

- **Frontend and Fluid integration**, not backend icons.
- **Inline SVG rendering** instead of external webfonts.
- **Extensibility** — custom mappings, per-site configuration, and planned sprite/localStorage support.

The result: **Accessible, maintainable, and future-proof icon rendering for modern TYPO3 sites.**

---

⚙️ Installation
---------------

[](#️-installation)

Require the package via Composer:

```
composer require oliverthiele/ot-icons
```

The global Fluid namespace is automatically registered when the extension is loaded. You can use <i:icon> in your templates immediately — no manual registration needed.

---

🛠 Integration into your build system (e.g. Webpack)
---------------------------------------------------

[](#-integration-into-your-build-system-eg-webpack)

To make your icon sets available to TYPO3, copy the SVG files from your preferred library (e.g. Font Awesome, Material Icons) into your public asset directory.

A typical Webpack setup using `copy-webpack-plugin` might look like this:

```
new CopyWebpackPlugin({
  patterns: [
    {
      from: './node_modules/@fortawesome/fontawesome-pro/svgs',
      to: 'Website/SVG'
    },
    {
      from: '../Default/Resources/Assets/'
    }
  ],
})
```

This step ensures that all SVG icons are copied into your project's public build directory — for example, under:

```
EXT:ot_febuild/Resources/Public/Assets/Website/SVG/

```

---

🧠 Configuration
---------------

[](#-configuration)

Once your assets are available, register the icon directory in your TYPO3 site configuration (config/sites/{site}/config.yaml):

```
settings:
    otIcons:
        defaultIconSet: 'FontAwesome_7'
        defaultIconStyle: 'solid'
        iconDirectory: 'EXT:ot_febuild/Resources/Public/Assets/Website/SVG/'
        customMappingDirectory: 'EXT:my_sitepackage/Configuration/Mappings/'
```

- **defaultIconSet** — defines which mapping file to use (e.g. FontAwesome\_7).
- **defaultIconStyle** — fallback style for icons without explicit style.
- **iconDirectory** — absolute path (using EXT:) to your compiled SVG files.
- **customMappingDirectory** — optional directory for your own mapping overrides.

> 🧹 **Note:**When adding or modifying mapping files in a custom directory, make sure to **clear the TYPO3 caches** to reload the updated mappings.

Each icon set defines its mapping file under:

```
Configuration/Mappings/{IconSetName}.php

```

Example `FontAwesome_7.php`:

Font Awesome version 6 and later renamed several icons (for example, `square-chevron-up` instead of `chevron-up-square`).

Only identifiers that differ between versions need to be mapped here. The mapping file below demonstrates how older identifiers are translated to their new counterparts.

Missing mappings can be contributed via pull request.

```
return [
    'config' => [
        'prefix' => 'fa-',
        'version' => '7.0.0',
        'defaultSubdirectory' => 'solid/',
    ],
    'map' => [
        'chevron-up-square'  => 'square-chevron-up',
        'chevron-left-square'  => 'square-chevron-left',
        'chevron-right-square'  => 'square-chevron-right',
        'chevron-down-square'  => 'square-chevron-down',
    ],
];
```

---

🔄 Custom mapping overrides
--------------------------

[](#-custom-mapping-overrides)

Integrators can also provide their own mapping overrides without modifying the `ot-icons` extension.

Simply create a file at:

```
EXT:my_sitepackage/Configuration/Mappings/{IconSetName}.php

```

It has the same structure as the default mapping file — only the differing identifiers need to be listed. When present, this file is automatically merged into the default mapping.

Example override:

```