TinyMCE Icon options

TinyMCE icons come from icon packs. TinyMCE includes both community and premium icon packs, but also allows integrators to add custom icons or override TinyMCE icons with their own.

The default icon pack is shipped with TinyMCE and does not require any configuration, though it must be imported when bundling for deployment: For example:

import 'tinymce/icons/default';

Replacing the default icon can be done using the icons and icons_url settings.

Available icon packs

TinyMCE includes both community and premium icon packs:

  • Community: default (always required)

  • Premium: bootstrap, jam, material, small, thin (available with paid subscriptions)

For information on which icon packs work best with which skins, see: Icon pack compatibility matrix.

Custom icon packs

For information on creating custom icon packs, see: Create an icon pack for TinyMCE.

The value passed to icons must match the pack name defined either:

  • Passed to tinymce.IconManager.add when registering the icon pack via JavaScript; or

  • Specified in the package.json iconPackName field when creating the icon pack using the Icon Pack Template.

Replacing the default icon pack

There are two options related to replacing the icons in TinyMCE: icons and icons_url.

  • icons specifies which icon pack to use.

  • icons_url specifies where to find that icon pack if it is not in the default location.

If only icons is configured, TinyMCE will try to load the specified icon pack from 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 load icon packs from another location, integrators must specify that location using icons_url.

  • When using TinyMCE from Tiny Cloud, ZIP bundles, or NPM packages with bundling or file layering, only icons should be required.

  • When using custom icon packs or using NPM packages without bundling, icons_url will likely also be required.

icons

The icons option allows the editor icons to be extended or replaced using an icon pack. The icon pack is specified by name.

Type: String

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.

Example: using a premium icon pack

tinymce.init({
  selector: 'textarea',
  icons: 'material',  // Use Material Design icons
  plugins: [
    "advlist", "anchor", "autolink", "charmap", "code", "fullscreen",
    "help", "image", "insertdatetime", "link", "lists", "media",
    "preview", "searchreplace", "table", "visualblocks",
  ],
  toolbar: "undo redo | styles | bold italic underline strikethrough | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | link image",
});

Example: using icon packs with matching skins and content styling

tinymce.init({
  selector: 'textarea',
  icons: 'bootstrap',  // Use Bootstrap icons
  skin: 'bootstrap',   // Match with Bootstrap skin
  content_css: 'bootstrap',  // Use Bootstrap content styling
});

icons_url

The icons_url option allows integrators to specify a non-default location to load icon packs from. This is useful 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.

Type: String

On initialization, TinyMCE will try to load any icon pack specified by the icons option from the location specified by icons_url. 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.

Understanding icons_url and icons Together:

When using icons_url, you must also specify the icons option:

  • icons_url - Tells TinyMCE where to find the icon pack file.

  • icons - Tells TinyMCE which icon pack to use from the loaded file.

Example:

tinymce.init({
  selector: 'textarea',
  icons_url: 'dist/icons/my_icon_pack/icons.js', // Where to find it
  icons: 'my_icon_pack',  // Which pack to use
  // ... other options
});

Usage

To use a TinyMCE icon pack from a separate location:

  1. Ensure the icon pack is available at the specified URL.

  2. Add the icons_url option to tinymce.init.

  3. Specify the icon pack name using the icons setting.

Example: using icons_url

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 from a different location
  icons: 'material', // use icon pack
  plugins: [
    "advlist", "anchor", "autolink", "charmap", "code", "fullscreen",
    "help", "image", "insertdatetime", "link", "lists", "media",
    "preview", "searchreplace", "table", "visualblocks",
  ],
  toolbar: "undo redo | styles | bold italic underline strikethrough | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | link image",
});

Example: loading premium icons from tinymce-premium (NPM)

When installing the tinymce-premium NPM package, premium icon packs are stored in node_modules/tinymce-premium/icons/. Configure icons_url to point at the desired icon pack file. The path is relative to where TinyMCE is loaded from. For example:

tinymce.init({
  selector: 'textarea',
  icons_url: '../../node_modules/tinymce-premium/icons/material/icons.js',
  icons: 'material'
});

  • Ensure the node_modules directory (or a copy of the icon pack file) is accessible to the browser. Many projects copy the required icon pack into a public folder (such as /public/icons/material/icons.js) during their build step and update icons_url accordingly.

  • Combine this with the approaches listed in Premium icon packs from tinymce-premium to match the deployment strategy.