You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This guide provides comprehensive coverage of creating, building, and deploying custom icon packs, including solutions to common issues.
9
+
This guide provides comprehensive coverage of creating, building, and deploying custom icon packs, including solutions to common issues. It details two approaches:
10
10
11
-
== Prerequisites
12
-
13
-
This guide assumes:
14
-
15
-
* Familiarity with the command line and running commands
16
-
* https://nodejs.org/en/[Node.js] and https://www.npmjs.com/[NPM] are already installed
17
-
* Optional: https://git-scm.com/[git] is already installed
11
+
* The inline approach, for adding a small number of custom icons
12
+
* The icon file approach, using the Icon Pack Template project to easily generate the required output file from a folder of SVGs.
18
13
19
14
== How Icons Work in {productname}
20
15
21
-
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.
16
+
A {productname} icon pack is a JavaScript construct containing strings of link:https://developer.mozilla.org/en-US/docs/Web/SVG[SVG's]. Icon packs are often kept in separate files, but can be inlined if needed. An icon pack can be used to add one or more custom icons or to replace some or all of the default {productname} icons.
22
17
23
18
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.
24
19
25
-
=== Icon Pack Structure and Loading
26
-
27
-
[IMPORTANT]
28
-
====
29
-
*Understanding Icon Pack Loading:*
30
-
31
-
{productname} loads icon packs from the path `+TINYMCE_BASE/icons/{iconPackName}/icons.js+`, where:
32
-
33
-
* `TINYMCE_BASE` is the {productname} root directory (the directory containing `tinymce.min.js`).
34
-
* `+{iconPackName}+` is the name of the icon pack.
20
+
== Registering an icon pack
35
21
36
-
**Example Directory Structure:**
37
-
----
38
-
js/tinymce/
39
-
├── tinymce.min.js ← TINYMCE_BASE marker file
40
-
├── icons/
41
-
│ ├── default/
42
-
│ │ └── icons.js ← Default TinyMCE icons
43
-
│ └── my_icon_pack/ ← Your custom pack
44
-
│ └── icons.js ← Must be exactly this filename
45
-
└── ... (other TinyMCE files)
46
-
----
47
-
====
48
-
49
-
=== Icon Pack File Format
50
-
51
-
The generated `icons.js` file in the `+dist/icons/{iconPackName}/icons.js+` directory follows this exact format:
22
+
Icon packs are registered with {productname} using the IconManager. Whether creating the icon pack manually or using the Icon Pack Template tool, the JavaScript required to setup an icon pack looks like:
52
23
53
24
[source,javascript]
54
25
----
55
-
tinymce.IconManager.add('your-pack-name', {
26
+
tinymce.IconManager.add('custom-pack-name', {
56
27
icons: {
57
-
'bold': '<svg width="24" height="24">...</svg>', // this is automatically generated from the 'bold.svg' file in the 'src/svg' directory
* xref:download-and-setup-the-icon-pack-template[Download and setup the icon pack template]
70
-
* xref:add-the-svg-files[Add the SVG files]
71
-
* xref:build-the-icon-pack[Build the icon pack]
36
+
== Creating an icon pack manually
72
37
73
-
=== Download and Setup the Icon Pack Template
38
+
When adding only a few icons, it may be easier to manually configure the new icon pack than to use the Icon Pack Template tool. To do this:
74
39
75
-
To use the {productname} icon pack template project:
40
+
. Gather the SVG files for the new icons. Extract their content string, e.g. `+<svg width="24" height="24">...</svg>+`
41
+
. Call `+tinymce.IconManager.add()+`
42
+
. Specify the icon pack name as the first argument
43
+
. The second argument is an object, with key `+icons+` and a nested object containing the new icons with their names and SVG strings as their keys and values.
76
44
77
-
. Download the link:https://github.com/tinymce/oxide-icon-pack-template[TinyMCE Oxide Icon Pack Template] by either:
78
-
* 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.
79
-
* From a terminal or command prompt, use git to clone the GitHub repository:
. Open a terminal or command prompt, navigate to the `oxide-icon-pack-template` directory.
87
-
. Install the project dependencies by executing:
88
-
+
89
-
[source,bash]
90
-
----
91
-
npm install
92
-
----
93
-
+
94
-
. When prompted, enter a name for the icon pack. The icon pack name should only contain:
95
-
* Numbers
96
-
* Letters
97
-
* Hyphens (`-`)
98
-
* Underscores (`_`)
99
-
+
100
-
. Verify that the `iconPackName` field has been added to your `package.json` file:
101
-
+
102
-
[source,json]
103
-
----
104
-
{
105
-
"iconPackName": "my_icon_pack",
106
-
}
107
-
----
108
-
109
-
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}.
45
+
The new icons can then be used by name within {productname}.
110
46
111
47
[IMPORTANT]
112
48
====
113
-
The `iconPackName` field in `package.json` is essential for the build process. This field:
114
-
115
-
* Defines the name that will be used in the generated `icons.js` file
116
-
* Must match the name you use in the `icons` option when initializing {productname}
117
-
* Is used by the build system to create the proper directory structure
118
-
* If missing or incorrect, the icon pack will not work properly
*Icon Override:* If custom icons have the same name as a default {productname} icon, they will override the default icon.
125
50
====
126
51
127
-
=== Add the SVG Files
52
+
This JavaScript can be included as a separate icon file or inlined beside the application's `+tinymce.init()+` call. Configure {productname} to load the icon pack and possibly where from.
128
53
129
-
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}.
54
+
[NOTE]
55
+
====
56
+
*Naming Icon Pack Files:* When loading icon packs from a separate file, it is safest to name the file `+icons.js+`. This ensures that, if placed in the default location, {productname} will recognize the file as an icon pack.
57
+
====
130
58
131
-
For example: `+bold.svg+` will have the identifier `bold`. Such as:
59
+
=== Example: using a custom icon pack inline
132
60
133
61
[source,js]
134
62
----
63
+
tinymce.IconManager.add('customIcons', { // icon pack name
icon: 'my-custom-icon' // use the custom icon for a custom toolbar button
145
76
});
146
77
}
147
78
});
148
79
----
149
80
150
-
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.
151
-
152
-
[NOTE]
153
-
====
154
-
* {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.
155
-
* *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.
156
-
====
157
-
158
-
==== SVG File Organization
159
-
160
-
Organize your SVG files in the `src/svg/` directory:
├── my-custom-icon.svg ← Creates new 'my-custom-icon' identifier
169
-
├── company-logo.svg ← Creates new 'company-logo' identifier
170
-
└── save-action.svg ← Creates new 'save-action' identifier
171
-
----
172
-
173
-
*Icon Identifier Rules:*
174
-
175
-
* Filename becomes the identifier: `+bold.svg+` → `+'bold'+`
176
-
* Hyphens are preserved: `+my-custom-icon.svg+` → `+'my-custom-icon'+`
177
-
178
-
=== Build the Icon Pack
81
+
== Using the Icon Pack Template tool
179
82
180
-
To build the icon pack using Gulp:
83
+
For large custom icon packs, use the xref:using-the-icon-pack-template.adoc[Icon Pack Template tool], which can take a folder of SVGs and generate the required output file. This approach is ideal when creating icon packs with many icons or when automating the build process.
181
84
182
-
. Open a terminal or command prompt and navigate to the root directory of the icon pack (such as: `+oxide-icon-pack-template/+`).
183
-
. Build the icon pack by executing the `npx gulp` command:
184
-
+
185
-
[source,bash]
186
-
----
187
-
npx gulp
188
-
----
189
-
+
190
-
A `+dist/+` directory containing the icon pack will be automatically created.
191
-
+
192
-
.Example: `+dist/icons/my-icon-pack/icons.js+` automatically generated from the SVG files in the `+src/svg+` directory.
. Using a web browser, open `+dist/html/icons.html+` to preview the icons.
85
+
For step-by-step instructions, see: xref:using-the-icon-pack-template.adoc[Using the Icon Pack Template tool].
205
86
206
-
==== Troubleshooting Information for Building Icon Packs
87
+
== Deploying an Icon Pack file
207
88
208
-
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:
89
+
An icon pack file can be served either:
209
90
210
-
. Using a text editor, open `+gulpfile.js+`.
211
-
. Add the `+svgo+` option to the `+iconPackager+` function, such as:
212
-
+
213
-
[source,javascript]
214
-
----
215
-
iconPackager({
216
-
name: 'my-icon-pack',
217
-
svgo: { floatPrecision: 3 } //Increase the rounding precision
218
-
})
219
-
----
91
+
* With {productname}
92
+
* Separate from {productname}
220
93
221
-
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].
94
+
Use the xref:editor-icons.adoc#icons[`+icons+`] and xref:editor-icons.adoc#icons_url[`+icons_url+`] options to configure {productname} appropriately.
222
95
223
-
== Deploying an Icon Pack
96
+
[NOTE]
97
+
====
98
+
*Default Icon Pack Location:*
224
99
225
-
An icon pack can be served either:
100
+
The `+icons+` option will only recognize icon files located at `+TINYMCE_BASE/icons/${iconPackName}/icons.js+`; where:
0 commit comments