Create an icon pack for OpenTiny

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

A OpenTiny 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 OpenTiny icons.

An icon pack only requires the custom icons to be included; the default OpenTiny 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 Tiny Skins and Icon Packs.

Creating a OpenTiny icon pack

To create a custom icon pack:

Download and setup the icon pack template

To use the OpenTiny icon pack template project:

  1. Download the OpenTiny 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

  2. Open a terminal or command prompt, navigate to the oxide-icon-pack-template directory.

  3. Install the project dependencies by executing:

    npm install

  4. 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 OpenTiny.

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 OpenTiny.

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.

OpenTiny 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:

  1. Open a terminal or command prompt and navigate to the root directory of the icon pack (such as: oxide-icon-pack-template/).

  2. Build the icon pack by executing the npx gulp command:

    npx gulp

    A dist/ directory containing the icon pack will be created.

  3. 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:

  1. Using a text editor, open gulpfile.js.

  2. 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:

Deploy the icon pack with OpenTiny

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

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

  • TINYMCE_BASE is the OpenTiny root directory (the directory containing tinymce.min.js).

  • ${iconPackName} is the name of the icon pack.

To use a OpenTiny icon pack:

  1. If required, create a new icons directory in TINYMCE_BASE.

  2. Copy the icon pack into the icons directory. For example:

    $ cp -r  dist/icons/my_icon_pack  TINYMCE_BASE/icons/

  3. 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 OpenTiny separately

On initialization, OpenTiny will try to load any icon pack specified by the icons_url option. The icons in the icon pack will be merged with OpenTiny’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 OpenTiny and the icon pack are loaded from different locations. For example: When loading OpenTiny 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
});