diff --git a/modules/ROOT/examples/live-demos/custom-icon-pack/index.html b/modules/ROOT/examples/live-demos/custom-icon-pack/index.html
new file mode 100644
index 0000000000..b2c4dce52d
--- /dev/null
+++ b/modules/ROOT/examples/live-demos/custom-icon-pack/index.html
@@ -0,0 +1,38 @@
+
+
+
Default TinyMCE Icons
+
+
+
+
Custom Icon Pack
+
+
+
+
+
+ Icon Credits: Custom icons in this demo are sourced from FreeSVGIcons.com - a collection of 250k+ open-source SVG icons.
+
diff --git a/modules/ROOT/examples/live-demos/custom-icon-pack/index.js b/modules/ROOT/examples/live-demos/custom-icon-pack/index.js
new file mode 100644
index 0000000000..6da201cf34
--- /dev/null
+++ b/modules/ROOT/examples/live-demos/custom-icon-pack/index.js
@@ -0,0 +1,47 @@
+// Load custom icon pack inline (for live demo compatibility)
+tinymce.IconManager.add('my-icon-pack', {
+ icons: {
+ 'audio': '',
+ 'bold': '',
+ 'italic': '',
+ }
+});
+
+// Default Icons Editor
+tinymce.init({
+selector: '#default-editor',
+icons: 'material', // use material icon pack
+plugins: 'lists link image code',
+toolbar: 'undo redo | bold italic underline | bullist numlist | link image code',
+height: 500,
+// license_key: 'gpl'
+});
+
+// Custom Icons Editor
+tinymce.init({
+selector: '#custom-editor',
+icons: 'my-icon-pack',
+plugins: 'lists link image code',
+toolbar: 'undo redo | myButton1 myButton2 myButton3 | bullist numlist | link image code',
+height: 500,
+setup: (editor) => {
+ editor.ui.registry.addButton('myButton1', {
+ icon: 'bold', // the 'bold' icon created from 'bold.svg'
+ onAction: (_) => {
+ editor.insertContent(' It\'s my custom bold icon button! ');
+ }
+ });
+ editor.ui.registry.addButton('myButton2', {
+ icon: 'italic', // the 'italic' icon created from 'italic.svg'
+ onAction: (_) => {
+ editor.insertContent(' It\'s my custom italic icon button! ');
+ }
+ });
+ editor.ui.registry.addButton('myButton3', {
+ icon: 'audio', // the 'audio' icon created from 'audio.svg'
+ onAction: (_) => {
+ editor.insertContent(' It\'s my custom audio icon button! ');
+ }
+ });
+}
+});
diff --git a/modules/ROOT/examples/live-demos/custom-icon-pack/svg/audio.svg b/modules/ROOT/examples/live-demos/custom-icon-pack/svg/audio.svg
new file mode 100644
index 0000000000..348ec21fbd
--- /dev/null
+++ b/modules/ROOT/examples/live-demos/custom-icon-pack/svg/audio.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/modules/ROOT/examples/live-demos/custom-icon-pack/svg/bold.svg b/modules/ROOT/examples/live-demos/custom-icon-pack/svg/bold.svg
new file mode 100644
index 0000000000..1b2952b0bf
--- /dev/null
+++ b/modules/ROOT/examples/live-demos/custom-icon-pack/svg/bold.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/modules/ROOT/examples/live-demos/custom-icon-pack/svg/italic.svg b/modules/ROOT/examples/live-demos/custom-icon-pack/svg/italic.svg
new file mode 100644
index 0000000000..1a8414fd1e
--- /dev/null
+++ b/modules/ROOT/examples/live-demos/custom-icon-pack/svg/italic.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/modules/ROOT/pages/bundling-icons.adoc b/modules/ROOT/pages/bundling-icons.adoc
index 89bc152fa2..4428cd67dd 100644
--- a/modules/ROOT/pages/bundling-icons.adoc
+++ b/modules/ROOT/pages/bundling-icons.adoc
@@ -3,20 +3,27 @@
:description_short: Information on bundling icon packs
:description: Information on bundling TinyMCE icon packs using module loading
+== Overview
+
+Icon packs provide visual styling for {productname}'s toolbar buttons, menu items, and contextual toolbars. When bundling {productname} with a module loader, icon packs can be included to customize the editor's appearance.
+
+{productname} includes both community and premium icon packs:
+
+* **Community icon packs**: Available with all {productname} installations
+* **Premium icon packs**: Available with paid {productname} subscriptions
+
+The default icon pack is always required and provides the base set of icons. Additional icon packs can be bundled to extend or replace the default icons.
+
:editorcomponent: icon pack
include::partial$module-loading/bundling-ref-example.adoc[]
:!editorcomponent:
-The following table shows examples of the syntax used to bundle the following icon pack:
+== Bundling syntax examples
-....
-./icons/example/icons.js
-....
-
-Example syntax for including the example icon pack in a bundle:
+The following examples show how to bundle icon packs using different module syntaxes. The examples use the `material` icon pack, but the same syntax applies to all available icon packs.
[cols='1,1,4']
-|===
+|====
|Module Syntax |Source |Example
.2+|ES6+
@@ -24,14 +31,14 @@ Example syntax for including the example icon pack in a bundle:
a|
[source, js]
----
-import 'tinymce/icons/example';
+import 'tinymce/icons/material';
----
|`.zip`
a|
[source, js]
----
-import '../tinymce/icons/example/icons';
+import '../tinymce/icons/material/icons';
----
.2+|Common JS
@@ -39,15 +46,44 @@ import '../tinymce/icons/example/icons';
a|
[source, js]
----
-require('tinymce/icons/example');
+require('tinymce/icons/material');
----
|`.zip`
a|
[source, js]
----
-require('../tinymce/icons/example/icons.js');
+require('../tinymce/icons/material/icons.js');
----
-|===
+|====
+
+== Available icon packs
include::partial$module-loading/bundling-icon-files.adoc[]
+
+== Usage in editor configuration
+
+After bundling an icon pack, configure the editor to use it by setting the `icons` option:
+
+[source, js]
+----
+tinymce.init({
+ selector: 'textarea',
+ icons: 'material', // Use the bundled material 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",
+});
+----
+
+== Troubleshooting
+
+**Icons not displaying**: Ensure the icon pack is properly bundled and the `icons` option matches the bundled pack name.
+
+**Missing icons**: The default icon pack is always required. Additional icon packs extend or replace default icons but do not provide all necessary icons on their own.
+
+**Build errors**: Verify that the icon pack path is correct and the pack exists in your {productname} installation.
+
diff --git a/modules/ROOT/pages/creating-an-icon-pack.adoc b/modules/ROOT/pages/creating-an-icon-pack.adoc
index 29067f0a95..4ec946f9cd 100644
--- a/modules/ROOT/pages/creating-an-icon-pack.adoc
+++ b/modules/ROOT/pages/creating-an-icon-pack.adoc
@@ -4,25 +4,65 @@
:description: How to make your own icon pack.
:keywords: create, creator, icon
-{productname} 6 introduced icon packs for customizing the editor icons.
+== Overview
+
+This guide provides comprehensive coverage of creating, building, and deploying custom icon packs, including solutions to common issues.
== Prerequisites
This guide assumes:
-* Familiarity with the command line and running commands.
-* https://nodejs.org/en/[Node.js] and https://www.npmjs.com[NPM] are already installed.
-* Optional: https://git-scm.com/[`+git+`] is already installed.
+* Familiarity with the command line and running commands
+* https://nodejs.org/en/[Node.js] and https://www.npmjs.com/[NPM] are already installed
+* Optional: https://git-scm.com/[git] is already installed
+
+== How Icons Work in {productname}
+
+A {productname} icon pack is a `+.js+` file containing strings of link:https://developer.mozilla.org/en-US/docs/Web/SVG[SVG's]. An icon pack can be used: to include one or more custom icons; or to replace some or all of the default {productname} icons.
+
+An icon pack only **requires** the custom icons to be included; the default {productname} icons are used as a fallback for icons missing from the custom icon pack.
+
+=== Icon Pack Structure and Loading
+
+[IMPORTANT]
+====
+*Understanding Icon Pack Loading:*
-== How icons work in {productname}
+{productname} loads icon packs from the path `+TINYMCE_BASE/icons/${iconPackName}/icons.js+`, where:
-A {productname} icon pack is a `+.js+` file containing strings of https://developer.mozilla.org/en-US/docs/Web/SVG[SVG's]. An icon pack can be used: to include one or more custom icons; or to replace some or all of the default {productname} icons.
+* `TINYMCE_BASE` is the {productname} root directory (the directory containing `tinymce.min.js`).
+* `${iconPackName}` is the name of the icon pack.
-An icon pack only requires the custom icons to be included; the default {productname} icons are used as a fallback for icons missing from the custom icon pack.
+**Example Directory Structure:**
+----
+js/tinymce/
+├── tinymce.min.js ← TINYMCE_BASE marker file
+├── icons/
+│ ├── default/
+│ │ └── icons.js ← Default TinyMCE icons
+│ └── my_icon_pack/ ← Your custom pack
+│ └── icons.js ← Must be exactly this filename
+└── ... (other TinyMCE files)
+----
+====
-NOTE: 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 xref:enhanced-skins-and-icon-packs.adoc[{prem_skins_icons}].
+=== Icon Pack File Format
-== Creating a {productname} icon pack
+The generated `icons.js` file in the `+dist/icons/${iconPackName}/icons.js+` directory follows this exact format:
+
+[source,javascript]
+----
+tinymce.IconManager.add('your-pack-name', {
+ icons: {
+ 'bold': '', // this is automatically generated from the 'bold.svg' file in the 'src/svg' directory
+ 'italic': '',
+ 'custom-icon': '',
+ // ... more icons
+ }
+});
+----
+
+== Creating a TinyMCE Icon Pack
To create a custom icon pack:
@@ -30,45 +70,65 @@ To create a custom icon pack:
* xref:add-the-svg-files[Add the SVG files]
* xref:build-the-icon-pack[Build the icon pack]
-[[download-and-setup-the-icon-pack-template]]
-=== Download and setup the icon pack template
+=== Download and Setup the Icon Pack Template
To use the {productname} icon pack template project:
-. Download the https://github.com/tinymce/oxide-icon-pack-template[{productname} Oxide Icon Pack Template] by either:
-* Downloading the `+.zip+` file from the https://github.com/tinymce/oxide-icon-pack-template[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:
+. Download the link:https://github.com/tinymce/oxide-icon-pack-template[TinyMCE Oxide Icon Pack Template] by either:
+* Downloading the `.zip` file from the link:https://github.com/tinymce/oxide-icon-pack-template[Oxide Icon Pack Template GitHub page] and extract the contents.
+* From a terminal or command prompt, use git to clone the GitHub repository:
+
-[source,sh]
+[source,bash]
----
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.
++
+. Open a terminal or command prompt, navigate to the `oxide-icon-pack-template` directory.
. Install the project dependencies by executing:
+
-[source,sh]
+[source,bash]
----
npm install
----
-
++
. When prompted, enter a name for the icon pack. The icon pack name should only contain:
+* Numbers
+* Letters
+* Hyphens (`-`)
+* Underscores (`_`)
+
---
-* Numbers.
-* Letters.
-* Hyphens ( `-` ).
-* Underscores ( `_` ).
---
+. Verify that the `iconPackName` field has been added to your `package.json` file:
++
+[source,json]
+----
+{
+ "iconPackName": "my_icon_pack",
+}
+----
+
+The icon pack name will be used with the link:https://www.tiny.cloud/docs/tinymce/latest/editor-icons/#icons[icons] option to apply the icons in {productname}.
+
+[IMPORTANT]
+====
+The `iconPackName` field in `package.json` is essential for the build process. This field:
-The icon pack name will be used with the xref:editor-icons.adoc#icons[icons] option to apply the icons in {productname}.
+* Defines the name that will be used in the generated `icons.js` file
+* Must match the name you use in the `icons` option when initializing {productname}
+* Is used by the build system to create the proper directory structure
+* If missing or incorrect, the icon pack will not work properly
-[[add-the-svg-files]]
-=== Add the SVG files
+*Example:*
+
+* `package.json` contains: `"iconPackName": "my_icon_pack"`
+* {productname} config uses: `icons: 'my_icon_pack'`
+* Generated file: `tinymce.IconManager.add('my_icon_pack', {...})`
+====
+
+=== 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 {productname}.
-For example: `+bold.svg+` will have the identifier `+bold+`. Such as:
+For example: `+bold.svg+` will have the identifier `bold`. Such as:
[source,js]
----
@@ -78,7 +138,7 @@ tinymce.init({
icons: 'my_icon_pack',
setup: (editor) => {
editor.ui.registry.addButton('myButton', {
- icon: 'bold', // the 'bold' icon created from 'bold.svg'
+ icon: 'bold', // the 'bold' icon created from 'bold.svg'
onAction: (_) => {
editor.insertContent(' It\'s my icon button! ');
}
@@ -87,47 +147,80 @@ tinymce.init({
});
----
-For a list of the icon identifiers, see: xref:editor-icon-identifiers.adoc[Available icons].
+For a list of default icon identifiers, see: link:https://www.tiny.cloud/docs/tinymce/latest/editor-icon-identifiers/[Available icons]. If using a custom icon pack, the icon identifiers will be the file names of the SVG files.
+
+[NOTE]
+====
+* {productname} 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 link:https://www.tiny.cloud/docs/tinymce/latest/creating-a-skin/[custom skin] is required.
+* *SVG Requirements:* 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.
+====
-{productname} 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 xref:creating-a-skin.adoc[custom skin] is required.
+==== SVG File Organization
-NOTE: 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.
+Organize your SVG files in the `src/svg/` directory:
+
+[source]
+----
+src/svg/
+├── bold.svg ← Overrides default bold icon
+├── italic.svg ← Overrides default italic icon
+├── underline.svg ← Overrides default underline icon
+├── my-custom-icon.svg ← Creates new 'my-custom-icon' identifier
+├── company-logo.svg ← Creates new 'company-logo' identifier
+└── save-action.svg ← Creates new 'save-action' identifier
+----
-[[build-the-icon-pack]]
-=== Build the icon pack
+*Icon Identifier Rules:*
+
+* Filename becomes the identifier: `+bold.svg+` → `+'bold'+`
+* Hyphens are preserved: `+my-custom-icon.svg+` → `+'my-custom-icon'+`
+
+=== 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:
+. Build the icon pack by executing the `npx gulp` command:
+
-[source,sh]
+[source,bash]
----
npx gulp
----
+
-A `+dist/+` directory containing the icon pack will be created.
-
+A `+dist/+` directory containing the icon pack will be automatically created.
++
+.Example: `+dist/icons/my-icon-pack/icons.js+` automatically generated from the SVG files in the `+src/svg+` directory.
+[source,js]
+----
+tinymce.IconManager.add('my-icon-pack', {
+ icons: {
+ 'audio': '',
+ 'bold': '',
+ 'italic': '',
+ }
+});
+----
++
. Using a web browser, open `+dist/html/icons.html+` to preview the icons.
-==== Troubleshooting information for building icon packs
+==== Troubleshooting Information for Building Icon Packs
-The SVG files are optimized during the build process with https://github.com/svg/svgo[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:
+The SVG files are optimized during the build process with link:https://github.com/svg/svgo[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:
+
-[source,js]
+[source,javascript]
----
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: https://github.com/svg/svgo[SVGO on GitHub].
-== Deploying an icon pack
+All user defined options, including SVGO options, will merge with the default options. For information on SVGO options, see: link:https://github.com/svg/svgo[SVGO on GitHub].
+
+== Deploying an Icon Pack
An icon pack can be served either:
@@ -135,13 +228,19 @@ An icon pack can be served either:
* xref:deploy-the-icon-pack-and-tinymce-separately[Separate from {productname}]
[[deploy-the-icon-pack-with-tinymce]]
-=== Deploy the icon pack with {productname}
+=== Deploy the Icon Pack with {productname}
:customIconPack: true
include::partial$configuration/icons.adoc[]
[[deploy-the-icon-pack-and-tinymce-separately]]
-=== Deploy the icon pack and {productname} separately
+=== Deploy the Icon Pack and {productname} Separately
include::partial$configuration/icons_url.adoc[]
:customIconPack: false
+
+== Interactive Demo
+
+See the custom icon pack in action with our interactive demo:
+
+liveDemo::custom-icon-pack[]
diff --git a/modules/ROOT/pages/custom-icon-pack-demo.adoc b/modules/ROOT/pages/custom-icon-pack-demo.adoc
new file mode 100644
index 0000000000..7c674d7571
--- /dev/null
+++ b/modules/ROOT/pages/custom-icon-pack-demo.adoc
@@ -0,0 +1,51 @@
+= Custom Icon Pack Demo
+:navtitle: Custom Icon Pack Demo
+:description: Interactive demo showing how to create and use custom icon packs with TinyMCE
+:keywords: custom, icon, icons, pack, demo, interactive, customize, theme
+
+This demo shows how to create and use custom icon packs with {productname}. Compare default icons with a custom icon pack side-by-side.
+
+== What This Demo Shows
+
+* **Side-by-side comparison** of default and custom icons
+* **Custom icon pack** with redesigned SVG icons
+* **Custom toolbar buttons** using icons from the custom pack
+* **Working code examples** you can copy
+
+== Key Features
+
+=== Custom Icon Pack Implementation
+
+The demo shows how to:
+
+. Load a custom icon pack using `icons_url`
+. Specify which icon pack to use with `icons`
+. Create custom toolbar buttons with custom icons
+
+=== Visual Comparison
+
+Compare:
+
+* Default {productname} icons (left editor)
+* Custom redesigned icons (right editor)
+* Different visual styles and approaches
+
+== How to Use This Demo
+
+1. **Compare the editors** - Notice the visual differences between default and custom icons
+2. **Test the custom buttons** - Use the star and heart buttons in the custom editor
+3. **Copy the code** - Use the provided examples in your own projects
+
+== Next Steps
+
+After exploring this demo:
+
+. Read the link:creating-an-icon-pack.adoc[Creating an Icon Pack] guide
+. Learn about link:bundling-icons.adoc[Bundling Icon Packs] for production
+. Check the link:icons.adoc[Icons Configuration] options
+
+liveDemo::custom-icon-pack[]
+
+== Icon Credits
+
+The custom icons used in this demo are sourced from https://freesvgicons.com/[FreeSVGIcons.com], a collection of 250k+ open-source SVG icons. When using free icons in your own projects, always check the license requirements and provide appropriate attribution.
diff --git a/modules/ROOT/pages/enhanced-skins-and-icon-packs.adoc b/modules/ROOT/pages/enhanced-skins-and-icon-packs.adoc
index 089cfe5210..6c280e596a 100644
--- a/modules/ROOT/pages/enhanced-skins-and-icon-packs.adoc
+++ b/modules/ROOT/pages/enhanced-skins-and-icon-packs.adoc
@@ -102,6 +102,7 @@ Below are some recommended combinations of skins and icon packs:
* xref:naked-demo.adoc[Naked editor]
* xref:outside-demo.adoc[Outside editor]
* xref:snow-demo.adoc[Snow editor]
+* xref:custom-icon-pack-demo.adoc[Custom Icon Pack Demo]
////
:pluginname: Tiny Skins and Icon
diff --git a/modules/ROOT/partials/configuration/icons.adoc b/modules/ROOT/partials/configuration/icons.adoc
index be53a1e76b..b50bbc29e5 100644
--- a/modules/ROOT/partials/configuration/icons.adoc
+++ b/modules/ROOT/partials/configuration/icons.adoc
@@ -15,6 +15,17 @@ On initialization, {productname} will try to load any icon pack specified by the
* `+TINYMCE_BASE+` is the {productname} root directory (the directory containing `+tinymce.min.js+`).
* `+${iconPackName}+` is the name of the icon pack.
+== Available icon packs
+
+{productname} includes both community and premium icon packs:
+
+* **Community**: `default` (always required)
+* **Premium**: `bootstrap`, `jam`, `material`, `small`, `thin` (available with paid subscriptions)
+
+For information on creating custom icon packs, see: xref:creating-an-icon-pack.adoc[Create an icon pack for {productname}].
+
+== Usage
+
To use a {productname} icon pack:
. If required, create a new `+icons+` directory in `+TINYMCE_BASE+`.
@@ -30,12 +41,14 @@ $ cp -r dist/icons/my_icon_pack TINYMCE_BASE/icons/
endif::[]
. Add the `+icons+` option to `+tinymce.init+`.
+
ifeval::[{customIconPack} == true]
-+
+For custom icon packs:
+
[source,js]
----
tinymce.init({
- selector: 'textarea', // change this value according to your HTML
+ selector: 'textarea',
icons: 'my_icon_pack' // TINYMCE_BASE/icons/my_icon_pack/icons.js
});
----
@@ -43,13 +56,31 @@ tinymce.init({
endif::[]
ifeval::[{customIconPack} != true]
-=== Example: using `+icons+`
+=== Example: using premium icon packs
+
+[source,js]
+----
+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 multiple icon packs
[source,js]
----
tinymce.init({
- selector: 'textarea', // change this value according to your HTML
- icons: 'material' // TINYMCE_BASE/icons/material/icons.js
+ selector: 'textarea',
+ icons: 'bootstrap', // Use Bootstrap icons
+ skin: 'bootstrap', // Match with Bootstrap skin
+ content_css: 'bootstrap', // Use Bootstrap content styling
});
----
diff --git a/modules/ROOT/partials/configuration/icons_url.adoc b/modules/ROOT/partials/configuration/icons_url.adoc
index 10d4c6003e..f6785119d2 100644
--- a/modules/ROOT/partials/configuration/icons_url.adoc
+++ b/modules/ROOT/partials/configuration/icons_url.adoc
@@ -9,15 +9,84 @@ endif::[]
On initialization, {productname} will try to load any icon pack specified by the *icons_url* option. The icons in the icon pack will be merged with xref:editor-icon-identifiers.adoc[{productname}'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 {productname} and the icon pack are loaded from different locations. For example: When loading {productname} from {cloudname}, the icon pack can be loaded from a different web server.
+
+[IMPORTANT]
+====
+*Understanding `icons_url` and `icons` Together:*
+
+When using `icons_url`, you must also specify the `icons` option:
+
+* `icons_url` - Tells {productname} *where* to find the icon pack file.
+* `icons` - Tells {productname} *which* icon pack to use from the loaded file.
+
+*Example:*
+[source,js]
+----
+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
+});
+----
+
+The `icons` value must match the pack name defined in your `package.json` `iconPackName` field.
+====
+
+== Usage
+
+To use a {productname} icon pack from a separate location:
+
+. Ensure the icon pack is available at the specified URL.
+. Add the `+icons_url+` option to `+tinymce.init+`.
+
ifeval::[{customIconPack} == true]
-Such as:
+For custom icon packs:
[source,js]
----
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
+ icons_url: 'dist/icons/my_icon_pack/icons.js', // Path to custom icon pack
+ icons: 'my_icon_pack' // Use custom icon pack
+});
+----
+
+=== Common Development Scenarios
+
+==== Local Development with Custom Icon Pack
+
+When developing locally with a custom icon pack:
+
+[source,js]
+----
+tinymce.init({
+ selector: 'textarea',
+ icons_url: 'dist/icons/my_icon_pack/icons.js', // Path to custom icon pack
+ icons: 'my_icon_pack', // Use custom icon pack
+ toolbar: 'myButton',
+ setup: (editor) => {
+ editor.ui.registry.addButton('myButton', {
+ icon: 'bold', // Uses your custom bold icon
+ onAction: (_) => {
+ editor.insertContent(' Custom icon clicked! ');
+ }
+ });
+ }
+});
+----
+
+==== CDN Deployment
+
+When deploying to a CDN or separate server:
+
+[source,js]
+----
+tinymce.init({
+ selector: 'textarea',
+ icons_url: 'https://cdn.example.com/icons/my_icon_pack/icons.js', // CDN URL
+ icons: 'my_icon_pack', // Use custom icon pack
+ // ... other options
});
----
@@ -31,8 +100,14 @@ ifeval::[{customIconPack} != true]
----
tinymce.init({
selector: 'textarea', // change this value according to your HTML
- icons_url: 'https://www.example.com/icons/material/icons.js', // load icon pack
- icons: 'material' // use icon pack
+ 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",
});
----
diff --git a/modules/ROOT/partials/module-loading/bundling-icon-files.adoc b/modules/ROOT/partials/module-loading/bundling-icon-files.adoc
index 3c0370f63f..1e0f9e4850 100644
--- a/modules/ROOT/partials/module-loading/bundling-icon-files.adoc
+++ b/modules/ROOT/partials/module-loading/bundling-icon-files.adoc
@@ -1,35 +1,49 @@
-== Community
+== Community icon packs
+
+These icon packs are available with all {productname} installations:
Default icons::
....
./icons/default/icons.js
....
-== Premium
+The default icon pack is always required and provides the base set of icons for all {productname} functionality.
+
+== Premium icon packs
-For information on premium icon packs, see: xref:enhanced-skins-and-icon-packs.adoc[{prem_skins_icons}].
+These icon packs are available with paid {productname} subscriptions. For more information, see: xref:enhanced-skins-and-icon-packs.adoc[{prem_skins_icons}].
Bootstrap icons::
....
./icons/bootstrap/icons.js
....
+Bootstrap-style icons that complement the Bootstrap skin and other modern interfaces.
+
Jam icons::
....
./icons/jam/icons.js
....
+Clean, minimal icons from the JAM icon library, ideal for modern web applications.
+
Material icons::
....
./icons/material/icons.js
....
+Material Design icons that work well with Material Design-inspired skins.
+
Small icons::
....
./icons/small/icons.js
....
+Compact icons designed for smaller toolbar buttons and space-constrained interfaces.
+
Thin icons::
....
./icons/thin/icons.js
....
+
+Thin, lightweight icons with minimal visual weight, perfect for clean, modern designs.
diff --git a/modules/ROOT/partials/module-loading/bundling-required-components.adoc b/modules/ROOT/partials/module-loading/bundling-required-components.adoc
index 8fef0893bb..0fe14291ed 100644
--- a/modules/ROOT/partials/module-loading/bundling-required-components.adoc
+++ b/modules/ROOT/partials/module-loading/bundling-required-components.adoc
@@ -4,7 +4,7 @@ The following components are required to bundle {productname}:
- The `tinymce` global
- The `silver` theme
- The `dom` model
-- The `default` icon pack. This is always required, but the default icons can be overridden using a custom or premium icon pack.
+- The `default` icon pack. This is always required and provides the base set of icons for all {productname} functionality. The default icons can be extended or overridden using additional icon packs.
- A _skin_ for styling the user interface, including toolbars and menus. This can be a community, premium or custom skin.
- A _content skin_ for styling UI features within the content such as table and image resizing. This can be a community, premium or custom skin.
diff --git a/package.json b/package.json
index 78b55e1534..cfa39cc679 100644
--- a/package.json
+++ b/package.json
@@ -31,6 +31,7 @@
"delay": "2500ms",
"ext": "*"
},
+ "iconPackName": "my-icon-pack",
"devDependencies": {
"@antora/cli": "^3.1.10",
"@antora/site-generator-default": "^3.1.10",