---
title: "Custom SVG Icons: An Exciting WordPress 7.1 Feature"
url: https://wpvibes.com/blog/wordpress-custom-icons/
date: 2026-08-12
modified: 2026-10-14
author: "Rashi"
description: "WordPress 7.1 is about to give developers something they've wanted for years: a real, public way to register custom SVG icons, no build step required. Here's what's coming and exactly how to use it."
categories:
  - "Tutorials"
tags:
  - "Custom Icons"
  - "Gutenberg"
  - "PHP"
  - "SVG Icons"
  - "WordPress"
  - "WordPress 7.1"
image: https://wpvibes.com/wp-content/uploads/2026/08/custom-svg-icons-wordpress-71-1024x538.png
word_count: 2017
---

# Custom SVG Icons: An Exciting WordPress 7.1 Feature

WordPress 7.1 added a public PHP API for custom SVG icons. You can register your own icons in named collections, and they appear in the Icon block’s picker, render in PHP templates, and show up in the REST API, with no JavaScript or build step.

This guide builds a small plugin, `wpvibes-custom-icons`, that registers a collection, adds icons inline and from files, auto-registers a whole folder, and uses the icons in the editor and in PHP.

**Want the finished code first?** The complete plugin is [on GitHub](https://github.com/webtechhardik/wpviibes-custom-icons).

## What Will You Build?

- A `wpvibes-custom-icons` plugin with an icon collection called `wpvibes`

- Three icons: a heart (registered inline), plus a star and a bookmark (registered from .svg files)

- A bulk pattern that registers every SVG in a folder automatically

- A shortcode for adding any registered icon to post content

## What Do You Need Before You Start?

**WordPress 7.1 or later**

A local development environment, such as LocalWP, WordPress Studio, or wp-env

Basic PHP knowledge

Step 1 of 7

## Step 1: How Does the Icons API Work?

The API has five functions, and every icon belongs to a **collection**:

- `wp_register_icon_collection( $name, $args )`: registers a collection. `label` is required; `description` is optional.

- `wp_register_icon( $name, $args )`: registers one icon. `label` is required, plus exactly one of `content` (inline SVG) or `file_path` (absolute path to an .svg file).

- `wp_get_icon( $name, $args )`: returns the icon’s SVG markup as a string.

- `wp_unregister_icon( $name )` and `wp_unregister_icon_collection( $name )`: remove an icon or a whole collection.

An icon’s name is `collection/icon-name`, so `core/plus` and `wpvibes/plus` never collide. Names must use lowercase letters, digits, hyphens, or underscores, and start and end with a letter or digit. Registration returns `false` if the collection doesn’t exist, the name is already taken, or you pass an unsupported argument key.

### What Can a Registered SVG Contain?

WordPress sanitizes every registered SVG with `wp_kses` against a small allowlist. According to the [WordPress 7.1 developer note](https://make.wordpress.org/core/2026/07/24/registering-and-rendering-svg-icons-in-wordpress-7-1/):

- Only `<svg>`, `<path>`, and `<polygon>` elements survive. Circles, rectangles, lines, groups, inline styles, and scripts are stripped.

- Stroke isn’t allowed anywhere, so outline (stroke-based) icons lose their outlines.

- Fill is kept on `<path>` and `<polygon>`, but not on `<svg>`.

What WordPress 7.1 keeps when it sanitizes a registered SVG icon. A filled icon built from path and polygon elements with fill set to currentColor survives and renders. An outline icon loses its stroke attributes and its circle, rect, line and g elements, so it renders empty. Inline styles and scripts are stripped too, and fill is kept only on path and polygon, not on the svg element.

**Important:** Build your icons as filled shapes using only `<path>` and `<polygon>`, and put `fill="currentColor"` on each shape. Many popular icon sets (Feather, Lucide, outline Heroicons) are stroke-based and use circles and lines, so convert them to filled paths before registering.

Step 2 of 7

## Step 2: Set Up the Plugin and Register the Collection

Create this folder inside `wp-content/plugins/`:

wpvibes-custom-icons/
├── wpvibes-custom-icons.php
└── icons/
├── star.svg
└── bookmark.svg

Create `wpvibes-custom-icons.php` with the plugin header and the collection:

`<?php
/**
* Plugin Name: WPVibes Custom Icons
* Description: Register custom SVG icons for WordPress 7.1+.
* Version: 1.0.0
* Author: WPVibes
* Requires at least: 7.1
* Requires PHP: 7.4
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
define( 'WPVIBES_ICONS_PATH', plugin_dir_path( __FILE__ ) );
/**
* Register the icon collection (default priority 10).
*/
add_action( 'init', 'wpvibes_register_icon_collection' );
function wpvibes_register_icon_collection() {
wp_register_icon_collection(
'wpvibes',
array(
'label' => __( 'WPVibes', 'wpvibes-icons' ),
)
);
}`

The collection name, `wpvibes`, becomes the prefix for every icon in it, and the label becomes the section heading in the icon picker.

**The collection must exist before its icons.** That’s why the icon registrations in the next steps run on `init` at priority 20, after the collection at the default priority of 10.

Step 3 of 7

## Step 3: Register Icons Two Ways

### 3.1: Register an inline icon with content

Inline SVG is handy for one or two icons. Add this to `wpvibes-custom-icons.php`:

`add_action( 'init', 'wpvibes_register_inline_icons', 20 );
function wpvibes_register_inline_icons() {
wp_register_icon(
'wpvibes/heart',
array(
'label' => __( 'Heart', 'wpvibes-icons' ),
'content' => '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="currentColor" d="M20.84 4.61a5.5 5.5 0 0 0-7.78 0L12 5.67l-1.06-1.06a5.5 5.5 0 0 0-7.78 7.78l1.06 1.06L12 21.23l7.78-7.78 1.06-1.06a5.5 5.5 0 0 0 0-7.78z"/></svg>',
)
);
}`

The `fill="currentColor"` on the path makes the icon take the color of the text around it.

### 3.2: Register icons from .svg files

For icons stored on disk, use `file_path`. Save these two files in the `icons/` folder.

`icons/star.svg`:

`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
<polygon fill="currentColor" points="12 2 15.09 8.26 22 9.27 17 14.14 18.18 21.02 12 17.77 5.82 21.02 7 14.14 2 9.27 8.91 8.26 12 2"/>
</svg>`

`icons/bookmark.svg`:

`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
<path fill="currentColor" d="M19 21l-7-5-7 5V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z"/>
</svg>`

Then register both:

`add_action( 'init', 'wpvibes_register_file_icons', 20 );
function wpvibes_register_file_icons() {
wp_register_icon(
'wpvibes/star',
array(
'label' => __( 'Star', 'wpvibes-icons' ),
'file_path' => WPVIBES_ICONS_PATH . 'icons/star.svg',
)
);
wp_register_icon(
'wpvibes/bookmark',
array(
'label' => __( 'Bookmark', 'wpvibes-icons' ),
'file_path' => WPVIBES_ICONS_PATH . 'icons/bookmark.svg',
)
);
}`

WordPress reads each file only when the icon is needed. Insert an **Icon** block in the editor, and the picker shows a new **WPVibes** section with Heart, Star, and Bookmark.

![Custom icon collection in the WordPress Icon block picker](https://wpvibes.com/wp-content/uploads/2026/08/custom-icons-added-tab-in-wordpress.png)Custom icon collection in the WordPress Icon block picker

**Icon not showing?** Check that the collection is registered first, the name follows the naming rules, the name isn’t already used, and you passed only supported keys. A wrong `file_path` doesn’t cause an error; the icon just renders empty.

Step 4 of 7

## Step 4: Register a Whole Folder of Icons

For a real icon library, let PHP register every SVG in the `icons/` folder. Replace `wpvibes_register_file_icons()` with:

`add_action( 'init', 'wpvibes_register_all_file_icons', 20 );
function wpvibes_register_all_file_icons() {
$svg_files = glob( WPVIBES_ICONS_PATH . 'icons/*.svg' );
if ( empty( $svg_files ) ) {
return;
}
foreach ( $svg_files as $file_path ) {
// "Advanced-Button.svg" -> "advanced-button" (lowercase, valid icon name).
$slug = sanitize_key( basename( $file_path, '.svg' ) );
$label = ucwords( str_replace( array( '-', '_' ), ' ', $slug ) );
wp_register_icon(
'wpvibes/' . $slug,
array(
'label' => $label,
'file_path' => $file_path,
)
);
}
}`

`glob()` finds every .svg file, `sanitize_key()` turns each filename into a valid lowercase icon name, and the label is built from the name, so `advanced-button.svg` appears as “Advanced Button”. Drop a new SVG into the folder, refresh the editor, and it’s in the picker.

![Multiple custom icons in the WPVibes icon collection](https://wpvibes.com/wp-content/uploads/2026/08/multiple-custom-icons-added-wordpress.jpg)Multiple custom icons in the WPVibes icon collection

Step 5 of 7

## Step 5: Where Can You Use Registered Icons?

## Step 1: What this step does

One PHP registration with wp_register_icon feeds three places: the Icon block picker in the editor, PHP templates and shortcodes through wp_get_icon, and read-only REST API endpoints for logged-in users who can edit posts.

### 5.1: In the Icon block

The Icon block’s picker shows every registered collection automatically, with no extra code. Icons are also available through read-only REST endpoints such as `/wp-json/wp/v2/icons` and `/wp-json/wp/v2/icon-collections`. These require a logged-in user who can edit posts, so they’re meant for editor tools rather than public use.

### 5.2: In PHP with wp_get_icon()

`wp_get_icon()` returns the SVG as a string, or an empty string if the icon isn’t registered:

`echo wp_get_icon(
'wpvibes/star',
array(
'size' => 32, // Width and height in px (default 24; null keeps the SVG's size).
'class' => 'featured-icon', // Extra CSS class on the <svg>.
'label' => __( 'Featured', 'wpvibes-icons' ), // Accessible label; omit for decorative icons.
)
);`

Without a `label`, the icon is treated as decorative and hidden from screen readers, which is right when text next to it already says the same thing.

Here’s a `[wpvibes_icon]` shortcode that lets anyone add an icon to post content:

`add_shortcode( 'wpvibes_icon', 'wpvibes_icon_shortcode' );
function wpvibes_icon_shortcode( $atts ) {
$atts = shortcode_atts(
array(
'name' => 'heart',
'text' => '',
'size' => 24,
'class' => '',
),
$atts
);
$icon = wp_get_icon(
'wpvibes/' . sanitize_key( $atts['name'] ),
array(
'size' => absint( $atts['size'] ),
'class' => sanitize_html_class( $atts['class'] ),
)
);
if ( ! $icon ) {
return '';
}
return sprintf(
'<span>%s %s</span>',
$icon,
esc_html( $atts['text'] )
);
}`

[wpvibes_icon name="heart" text="Hello World"]
[wpvibes_icon name="star" text="Featured post" size="32"]

### 5.3: As a block icon

A registered icon can replace the default Dashicon when you register a block:

`'icon' => 'wpvibes/star', // Instead of a Dashicon such as 'warning'`

This works for blocks registered in PHP, such as those in our [PHP-only blocks guide](https://wpvibes.com/blog/php-only-blocks-wordpress/).

Step 6 of 7

## Step 6: How Do You Style Custom Icons?

### 6.1: Use currentColor for color inheritance

Put `fill="currentColor"` on each shape instead of a fixed color. The icon then matches the surrounding text: red inside red text, and the link color inside a link.

`<!-- Fixed color: always red -->
<path fill="#dc2626" d="..."/>
<!-- Inherits the text color -->
<path fill="currentColor" d="..."/>`

Inside the Icon block, WordPress’s stylesheet already sets `fill: currentColor` on `.wp-block-icon svg`. Icons you output with `wp_get_icon()` elsewhere rely on the fill in the SVG itself, which is why the shape-level fill matters.

### 6.2: Force a specific color

For a brand mark or status icon, set `color` on the class you passed to `wp_get_icon()`:

`.featured-icon {
color: #f59e0b; /* Amber, regardless of surrounding text */
}`

### 6.3: Add hover effects

```
.wpvibes-icon-inline svg {
transition: transform 0.15s ease-in-out;
}
.wpvibes-icon-inline:hover svg {
transform: scale(1.1);
}
```

Use the `size` argument for a one-off size, and CSS classes when the icon appears in many places or needs hover and focus states.

Step 7 of 7

## Step 7: How Do You Remove Icons?

Use `wp_unregister_icon()` to remove a single icon, for example one registered by another plugin. Run it on `init` after that icon is registered:

`add_action( 'init', function () {
wp_unregister_icon( 'wpvibes/bookmark' );
}, 30 );`

`wp_unregister_icon_collection( 'wpvibes' )` removes a collection and every icon in it. Any post that already uses a removed icon in an Icon block will render it empty, since WordPress doesn’t change saved post content.

**Note:** You don’t need to unregister anything when your plugin is deactivated. Icons are registered on every page load, so once the plugin stops running, its icons are gone.

## How Do Custom Icons Fit the Bigger Picture?

Custom icons follow the same “register once, use everywhere” pattern as the Abilities API and block bindings: one PHP registration feeds the editor, your templates, and the REST API. Together with [PHP-only blocks](https://wpvibes.com/blog/php-only-blocks-wordpress/) or [ACF Blocks](https://wpvibes.com/blog/custom-gutenberg-acf-blocks/), a plugin can now ship custom blocks with branded icons and no build step.

## Frequently Asked Questions

### Do I have to register a collection before registering icons?
Yes. Every icon belongs to a collection, and registration fails if the collection doesn’t exist yet. Register the collection on `init` at the default priority, then register icons at a later priority, such as 20.
### Does WordPress sanitize SVG icons?
Yes. WordPress runs each SVG through `wp_kses` with a small allowlist: only `<svg>`, `<path>`, and `<polygon>` elements, no `stroke` attributes, and `fill` only on shapes. Scripts, inline styles, and other elements are stripped.
### Why does my outline icon look broken?
Stroke-based icons lose their outlines because WordPress strips the `stroke` attribute. Convert the icon to filled `<path>` or `<polygon>` shapes with `fill="currentColor"`, then register it again.
### Can I mix inline and file-based icons in one collection?
Yes. Each `wp_register_icon()` call is independent, so you can use `content` for some icons and `file_path` for others in the same collection.
### Can I register icons from a theme instead of a plugin?
Yes. Call `wp_register_icon()` from your theme’s `functions.php` and use `get_stylesheet_directory()` for file paths. The trade-off is that the icons disappear if you switch themes.
### What happens if two plugins use the same icon name?
Different collections never clash, so `wpvibes/heart` and `myplugin/heart` can coexist. Registering the same full name twice fails, so pick a collection name unique to your plugin.

## Wrapping Up

Register a collection, add icons inline or from files, keep each SVG to filled paths and polygons, and use the icons in the Icon block, PHP templates, and the REST API, all without JavaScript.

**Next step:** use your new icons in custom blocks with our [PHP-only blocks guide](https://wpvibes.com/blog/php-only-blocks-wordpress/).