Create an icon pack for TinyMCE

TinyMCE 6 introduced icon packs for customizing the editor icons.

Prerequisites

This guide assumes:

Familiarity with the command line and running commands.
Node.js and NPM are already installed.
Optional: git is already installed.

How icons work in TinyMCE

A TinyMCE icon pack is a .js file containing strings of SVG’s. An icon pack can be used: to include one or more custom icons; or to replace some or all of the default TinyMCE icons.

An icon pack only requires the custom icons to be included; the default TinyMCE icons are used as a fallback for icons missing from the custom icon pack.

Don’t forget to explore our ready-to-use Premium Icon Packs such as 'Material' icons, and a smaller version of our default icons at Enhanced Skins & Icon Packs.

Creating a TinyMCE icon pack

To create a custom icon pack:

Download and setup the icon pack template
Add the SVG files
Build the icon pack

Download and setup the icon pack template

To use the TinyMCE icon pack template project:

Download the TinyMCE Oxide Icon Pack Template by either:
- Downloading the .zip file from the Oxide Icon Pack Template GitHub page and extract the contents.
- From a terminal or command prompt, use git to clone the GitHub repository, such as:
  git clone https://github.com/tinymce/oxide-icon-pack-template.git
Open a terminal or command prompt, navigate to the oxide-icon-pack-template directory.
Install the project dependencies by executing:
```
npm install
```
When prompted, enter a name for the icon pack. The icon pack name should only contain:
- Numbers.
- Letters.
- Hyphens ( - ).
- Underscores ( _ ).

The icon pack name will be used with the icons option to apply the icons in TinyMCE.

Add the SVG files

Each SVG files placed in /src/svg will be converted to an icon. The file names of the SVG files are used to set the icon identifier used by TinyMCE.

For example: bold.svg will have the identifier bold. Such as:

tinymce.init({
  selector: '#tiny_custom_button',  // change this value according to your HTML
  toolbar: 'myButton',
  icons: 'my_icon_pack',
  setup: (editor) => {
    editor.ui.registry.addButton('myButton', {
      icon: 'bold',    // the 'bold' icon  created from 'bold.svg'
      onAction: (_) => {
        editor.insertContent('&nbsp;<strong>It\'s my icon button!</strong>&nbsp;');
      }
    });
  }
});

For a list of the icon identifiers, see: Available icons.

TinyMCE does not resize the SVGs provided, relying on the size defined in the SVG. This allows icons of different sizes to be used in the editor. The Toolbar button sizes are independent of the icon sizes. To change button sizes, a custom skin is required.

Input SVGs must be shapes, not strokes. SVG files containing strokes will not render correctly. If the input files contain strokes, use a graphics program to convert the strokes into shapes.

Build the icon pack

To build the icon pack using Gulp:

Open a terminal or command prompt and navigate to the root directory of the icon pack (such as: oxide-icon-pack-template/).
Build the icon pack by executing the npx gulp command:
```
npx gulp
```
A dist/ directory containing the icon pack will be created.
Using a web browser, open dist/html/icons.html to preview the icons.

Troubleshooting information for building icon packs

The SVG files are optimized during the build process with SVGO. The optimization can result in distorted graphics due to rounding errors. The graphics may be fixed by providing new SVGO options. To change the SVGO options used:

Using a text editor, open gulpfile.js.
Add the svgo option to the iconPackager function, such as:
```
iconPackager({
  name: 'my-icon-pack',
  svgo: { floatPrecision: 3 } //Increase the rounding precision
})
```
All user defined options, including SVGO options, will merge with the default options. For information on SVGO options, see: SVGO on GitHub.

Deploying an icon pack

An icon pack can be served either:

With TinyMCE
Separate from TinyMCE

Deploy the icon pack with TinyMCE

On initialization, TinyMCE will try to load any icon pack specified by the icons option. The icons in the icon pack will be merged with TinyMCE’s default icons and icons in the icon pack will overwrite the default icons with the same identifier.

TinyMCE loads icon packs from the path TINYMCE_BASE/icons/${iconPackName}/icons.js; where:

TINYMCE_BASE is the TinyMCE root directory (the directory containing tinymce.min.js).
${iconPackName} is the name of the icon pack.

To use a TinyMCE icon pack:

If required, create a new icons directory in TINYMCE_BASE.
Copy the icon pack into the icons directory. For example:
```
$ cp -r  dist/icons/my_icon_pack  TINYMCE_BASE/icons/
```

Add the icons option to tinymce.init.

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  icons: 'my_icon_pack'  // TINYMCE_BASE/icons/my_icon_pack/icons.js
});

Deploy the icon pack and TinyMCE separately

On initialization, TinyMCE will try to load any icon pack specified by the icons_url option. The icons in the icon pack will be merged with TinyMCE’s default icons and icons in the icon pack will overwrite the default icons with the same identifier.

icons_url is used to specify the location of an icon pack when TinyMCE and the icon pack are loaded from different locations. For example: When loading TinyMCE from Tiny Cloud, the icon pack can be loaded from a different web server. Such as:

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  icons_url: 'https://www.example.com/icons/my_icon_pack/icons.js', // load icon pack
  icons: 'my_icon_pack'  // use icon pack
});