Title: wp_register_icon
Published: August 20, 2026

---

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

## In this article

 * [Parameters](https://developer.wordpress.org/reference/functions/wp_register_icon/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/functions/wp_register_icon/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/functions/wp_register_icon/?output_format=md#source)
 * [Related](https://developer.wordpress.org/reference/functions/wp_register_icon/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/functions/wp_register_icon/?output_format=md#changelog)
 * [User Contributed Notes](https://developer.wordpress.org/reference/functions/wp_register_icon/?output_format=md#user-contributed-notes)

[ Back to top](https://developer.wordpress.org/reference/functions/wp_register_icon/?output_format=md#wp--skip-link--target)

Registers a new icon.

## 󠀁[Parameters](https://developer.wordpress.org/reference/functions/wp_register_icon/?output_format=md#parameters)󠁿

 `$icon_name`stringrequired

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.

`$args`arrayrequired

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](https://developer.wordpress.org/reference/functions/wp_register_icon/?output_format=md#return)󠁿

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

## 󠀁[Source](https://developer.wordpress.org/reference/functions/wp_register_icon/?output_format=md#source)󠁿

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

[View all references](https://developer.wordpress.org/reference/files/wp-includes/icons.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/7.1/src/wp-includes/icons.php#L61)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/7.1/src/wp-includes/icons.php#L61-L63)

## 󠀁[Related](https://developer.wordpress.org/reference/functions/wp_register_icon/?output_format=md#related)󠁿

| Uses | Description | 
| [WP_Icons_Registry::get_instance()](https://developer.wordpress.org/reference/classes/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()](https://developer.wordpress.org/reference/functions/_wp_register_default_icons/)`wp-includes/icons.php` |

Registers the default core icons from the manifest.

  |

## 󠀁[Changelog](https://developer.wordpress.org/reference/functions/wp_register_icon/?output_format=md#changelog)󠁿

| Version | Description | 
| [7.1.0](https://developer.wordpress.org/reference/since/7.1.0/) | Introduced. |

## 󠀁[User Contributed Notes](https://developer.wordpress.org/reference/functions/wp_register_icon/?output_format=md#user-contributed-notes)󠁿

 1.   [Skip to note 2 content](https://developer.wordpress.org/reference/functions/wp_register_icon/?output_format=md#comment-content-7615)
 2.    [Rodrigo Vieira Eufrasio da Silva](https://profiles.wordpress.org/rodrigomct/)
     [  1 month ago  ](https://developer.wordpress.org/reference/functions/wp_register_icon/#comment-7615)
 3.  [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_register_icon%2F%23comment-7615)
     Vote results for this note: 0[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_register_icon%2F%23comment-7615)
 4.  **Cases that return false**
 5.  **_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.
 6.  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:
 7.      ```php
         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' );
         ```
     
 8.  **A name already taken is not overwritten**. Re-registering an existing icon fails;
     call [wp_unregister_icon()](https://developer.wordpress.org/reference/functions/wp_unregister_icon/)
     first to replace one.
 9.  **Cases that return true and break later**
 10. 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.
 11. **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.
 12.  [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_register_icon%2F%3Freplytocom%3D7615%23feedback-editor-7615)

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_register_icon%2F)
before being able to contribute a note or feedback.