wp_register_icon( string $icon_name, array $args ): bool

Registers a new icon.

Parameters

$icon_namestringrequired

Namespaced icon name in the form "collection/icon-name" (e.g. "my-plugin/arrow-left"). The "core" collection is reserved for WordPress core icons; third-party code should register icons under its own collection rather than the "core" collection.

$argsarrayrequired

List of properties for the icon.

label string
Required. A human-readable label for the icon.
content string
Optional. SVG markup for the icon.
If not provided, the content will be retrieved from the file_path if set.
If both content and file_path are not set, the icon will not be registered.
file_path string
Optional. The full path to the file containing the icon content.

Return

bool True if the icon was registered successfully, else false.

Source

function wp_register_icon( $icon_name, $args ) {
	return WP_Icons_Registry::get_instance()->register( $icon_name, $args );
}

View all references View on Trac View on GitHub

Uses	Description
WP_Icons_Registry::get_instance()`wp-includes/class-wp-icons-registry.php`	Utility method to retrieve the main instance of the class.

Used by	Description
_wp_register_default_icons()`wp-includes/icons.php`	Registers the default core icons from the manifest.

Changelog

Version	Description
7.1.0	Introduced.

User Contributed Notes

Skip to note 2 content

Rodrigo Vieira Eufrasio da Silva 1 month ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
Cases that return false

content and file_path are mutually exclusive. The parameter list reads as though file_path is a fallback for a missing content, but passing both is rejected the same way as passing neither. Supply exactly one.

The collection has to be registered first. The registry checks the part of the name before the slash and refuses an icon whose collection is unknown, so wp_register_icon( ‘my-plugin/arrow’, … ) fails until wp_register_icon_collection( ‘my-plugin’, … ) has run. Core registers its own collections on init at priority 0, so registering a collection and its icons on init at the default priority works:
```
function wpdocs_register_icons() {
	wp_register_icon_collection( 'wpdocs', array( 'label' => __( 'Wpdocs', 'wpdocs' ) ) );
	wp_register_icon( 'wpdocs/arrow', array(
		'label'     => __( 'Arrow', 'wpdocs' ),
		'file_path' => plugin_dir_path( __FILE__ ) . 'icons/arrow.svg',
	) );
}
add_action( 'init', 'wpdocs_register_icons' );
```
A name already taken is not overwritten. Re-registering an existing icon fails; call wp_unregister_icon() first to replace one.

Cases that return true and break later

file_path is not checked at registration time. Whether the path resolves, ends in .svg, exists, and is readable is only verified the first time the icon’s content is requested. A wrong path registers successfully and later surfaces as an error notice with null content instead.

Inline content is filtered through a narrow allowlist. Only svg, path, and polygon survive, each with a fixed set of attributes — stroke and stroke-width are not among them, and g, circle, and rect are not allowed elements. If everything is stripped the icon is rejected outright, but a partially stripped icon registers and renders wrong. Convert shapes to path elements and use fills rather than strokes.
Log in to add feedback

You must log in before being able to contribute a note or feedback.