---
title: "TinyMCE Icon options"
description: "Configure the editor's toolbar button and menu item icons."
canonical_url: "https://www.tiny.cloud/docs/tinymce/latest/editor-icons/"
md_url: "https://www.tiny.cloud/docs/tinymce/latest/editor-icons/index.md"
version: "latest"
last_updated: "2025-12-10T03:38:03Z"
tokens: 1576
---
# 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:

```js
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](../enhanced-skins-and-icon-packs/#icon-pack-compatibility-matrix).

## Custom icon packs

For information on creating custom icon packs, see: [Create an icon pack for TinyMCE](../creating-an-icon-pack/).

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](../creating-an-icon-pack/#download-and-setup-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](../editor-icon-identifiers/) and icons in the icon pack will overwrite the default icons with the same identifier.

### Example: using a premium icon pack

```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 icon packs with matching skins and content styling

```js
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](../editor-icon-identifiers/) and icons in the icon pack will overwrite the default icons with the same identifier.

> **Important:** **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:**
> 
> ```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
> });
> ```

## 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`

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

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

> **Note:**
> - 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`](../bundling-icons/#premium-icon-packs-npm) to match the deployment strategy.