wp_register_icon() │ WP 7.1.0

Registers an SVG icon in the specified collection.

After registration, the icon is available to the block editor, the REST API, and wp_get_icon().

No Hooks.

Returns

true|false.

• true - the icon was successfully registered.
• false - registration failed; an _doing_it_wrong() notice is also generated when:
  • the icon name is invalid;
  • the collection is not registered;
  • the icon already exists;
  • the label is missing;
  • unknown properties were supplied;
  • SVG content is missing, or both content and file_path were supplied.

Usage

wp_register_icon( $icon_name, $args );

$icon_name(string) (required)

Icon name in the collection/name format, for example my-plugin/star.

The part after / must begin and end with a lowercase Latin letter or a digit. Hyphens and underscores are also allowed inside it.

The core collection is reserved for core icons. Plugins and themes should use their own collection.

$args(array) (required)

Icon properties.

• label(string) (required)
  Human-readable icon name. The string should be translatable.

• content(string)
  SVG icon markup. It is sanitized immediately during registration.

  Cannot be supplied together with file_path.

• file_path(string)
  Absolute path to the .svg file.

  The file is loaded only when the icon is first retrieved or rendered. Registration can therefore succeed even when the path is invalid or the file is unavailable. In that case, the icon content is empty and WordPress creates a warning.

Examples

#1 Registering an icon from an SVG string

First register the collection, then add an icon to it.

add_action( 'init', 'my_plugin_register_icons' );

function my_plugin_register_icons() {
	wp_register_icon_collection( 'my-plugin', [
		'label' => __( 'My Plugin Icons', 'my-plugin' ),
	] );

	wp_register_icon( 'my-plugin/star', [
		'label'   => 'Star',
		'content' => '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
				<path fill="currentColor" d="M12 2l2.9 6.9 7.1.6-5.4 4.7 1.6 7L12 18l-6.2 3.2 1.6-7L2 9.5l7.1-.6z" />
			</svg>',
	] );
}

#2 Registering an icon from a file

add_action( 'init', 'my_plugin_register_file_icon' );

function my_plugin_register_file_icon() {
	wp_register_icon_collection( 'my-plugin', [
		'label' => __( 'My Plugin Icons', 'my-plugin' ),
	] );

	wp_register_icon( 'my-plugin/heart', [
		'label'     => __( 'Heart', 'my-plugin' ),
		'file_path' => plugin_dir_path( __FILE__ ) . 'icons/heart.svg',
	] );
}