Easy SVG developer reference

Easy SVG Support cleans every SVG before WordPress stores it and keeps a library of your own icons for the Icon block. Around that it offers a small, deliberate set of hooks, functions and JavaScript entry points for themes, site plugins and add-ons. This page explains what exists, what is promised to stay, and how to read the reference pages.

What you can build on

In short:

• Hooks. Every hook has a fixed, literal name. The sanitizer filters (esw_svg_allowed_tags, esw_svg_allowed_attributes, esw_svg_remove_remote_references) keep their older esw_ prefix because many sites already use them. Everything newer starts with easy_svg_.
• Functions. easy_svg_sanitizer(), easy_svg_icon(), easy_svg_rename_icon() and easy_svg_update_icon_markup().
• Shortcode. [easy_svg_icon name="easy-svg/heart"] with optional class and label, rendering the same markup as easy_svg_icon().
• Icon block. When the icon library is on and WordPress has its icon registry (7.1 and newer), every stored icon is registered in the collection easy-svg for the core Icon block.
• JavaScript. On the Icons screen, window.EasySvgPanel offers registerTab(), registerCollections() and api.
• REST. The panel talks to easy-svg/v1/settings and easy-svg/v1/library (with add, media, rename, replace and delete). Every route needs the manage_options capability. These routes are internal: they serve the panel and are not part of the promise below. The REST API tutorial shows how to use them with that in mind.

What is promised to stay

The plugin's readme draws a clear line, and this reference follows it:

• Stable items are the ones the readme names for developers: the hooks in its FAQ, the functions above, the three version constants, the shortcode, the Icon block collection and the panel registry entries. They keep their names and behaviour, and when their shape changes, a version constant changes with them.
• Internal items are everything else: helper functions, the classes esw_svg_tags and esw_svg_attributes, the global $sanitizer, options, transients, the REST routes and other JavaScript properties. In the readme's words, everything else "may be renamed or removed". Internal pages are documented so you can understand the plugin, and each one carries a notice.

Version constants and feature detection

Compare against these numbers, never against the plugin version. Each one only changes when its own surface changes shape, and a filter cannot be asked whether it exists, so the constants are the only reliable signal.

All three are defined when easy-svg.php loads, whether or not any feature is switched on. A plugin that loads before Easy SVG does not see them yet, so check on plugins_loaded or later:

function myaddon_boot() {
	if ( ! defined( 'EASY_SVG_API' ) ) {
		return; // Easy SVG Support is not active.
	}

	if ( defined( 'EASY_SVG_ICONS_API' ) && EASY_SVG_ICONS_API >= 3 ) {
		require_once __DIR__ . '/includes/icon-repair.php';
	}

	if ( defined( 'EASY_SVG_PANEL_API' ) && EASY_SVG_PANEL_API >= 3 ) {
		add_action( 'easy_svg_panel_enqueue', 'myaddon_enqueue_panel_bundle' );
	}
}
add_action( 'plugins_loaded', 'myaddon_boot' );

In JavaScript on the Icons screen, read window.EasySvgPanel.api, which holds the same number as EASY_SVG_PANEL_API.

How to read a reference page

Every item page has the same sections, in the same order:

1. Header line: the kind (Filter, Action, Function, Shortcode, Block, Constant, JavaScript), the product and the status.
2. Usage: the exact signature or definition.
3. When to use it: real situations, and when to reach for something else.
4. Parameters: what each argument holds and which values are allowed.
5. Return value: what your callback or the function must return, or what the constant holds.
6. Default: the value when nobody changes anything.
7. Examples: a basic case, a realistic one, and a defensive one that checks for the plugin first.
8. How it works: what the code really does, in which order and on which WordPress hooks.
9. Pitfalls: mistakes taken from the code, plus security notes where they matter.
10. Related: the neighbouring items.

Status is either Stable (part of the promise above) or Internal (may change without notice).

Groups sort the reference by topic:

Tutorials

All stable items

Sanitizer

• esw_svg_allowed_tags: filters the SVG element names the sanitizer keeps.
• esw_svg_allowed_attributes: filters the SVG attribute names the sanitizer keeps.
• esw_svg_remove_remote_references: decides whether references to other hosts are stripped.
• easy_svg_sanitizer(): returns a sanitizer configured exactly the way the site sanitizes.

Uploads and limits

• easy_svg_max_bytes: the largest SVG, in bytes, the plugin will read.
• easy_svg_max_mb_ceiling: the highest size admins can choose in the settings.
• easy_svg_max_php_tags: how many processing instructions a file may contain.
• easy_svg_max_use_tags: how many use elements a file may contain.

Multisite

• easy_svg_respect_network_filetypes: whether the network's allowed file types can keep SVG out.

Icons

• easy_svg_icon(): returns a stored icon as inline SVG.
• easy_svg_icon: the shortcode version of easy_svg_icon().
• easy_svg_icon_markup: filters one icon's markup on its way out of easy_svg_icon() and the shortcode.
• easy_svg_registrable_icons: filters the whole library before it reaches the Icon block.
• easy_svg_rename_icon(): changes an icon's visible name, keeping its slug.
• easy_svg_update_icon_markup(): replaces an icon's drawing through the sanitizer and the upload bounds.

Blocks

• easy-svg: the icon collection registered for the core Icon block.

Icons panel

• easy_svg_panel_enqueue: fires when the panel script is enqueued, so you can load yours after it.
• easy_svg_panel_menu_tabs: which tabs get their own menu entry, and which capability each needs.
• window.EasySvgPanel: the panel's extension registry.
• window.EasySvgPanel.registerTab: adds a tab with its own render function.
• window.EasySvgPanel.registerCollections: lists an add-on's icon collections in the Icon library tab.
• window.EasySvgPanel.api: the panel contract level in JavaScript.

Admin

• easy_svg_pro_url: the address behind the Buy Easy SVG Pro link on the Plugins screen.

Constants

• EASY_SVG_API: version of the sanitizer contract.
• EASY_SVG_PANEL_API: version of the Icons panel contract.
• EASY_SVG_ICONS_API: version of the icon contract.