How to Register Custom Svg Icon Collections in WordPress 7.1 Using the Icon Registration API

ByAkensai

How to Register Custom Svg Icon Collections in WordPress 7.1 Using the Icon Registration API is one of the most practical skills you can add to your WordPress development workflow. WordPress 7.1 introduced a dedicated Icon Registration API that gives developers a clean, structured way to bundle SVG icons into reusable collections. Instead of scattering inline SVG code across templates, you can register a named collection once and call individual icons anywhere in your theme or plugin. This approach keeps your codebase clean and consistent. It also makes icon sets easier to swap out or update later. In this tutorial, you will learn how to create an SVG sprite file, register it as a named collection using the new API, and output individual icons in your templates. By the end, you will have a fully working custom icon system running inside your WordPress site.

Prerequisites for Registering Custom SVG Icon Collections

Before you start, make sure your environment meets the following requirements.

Required software and access:

  • WordPress 7.1 or later installed and running
  • SSH or FTP access to your server
  • A code editor such as VS Code or Nano
  • A child theme or custom plugin to place your code in
  • Basic familiarity with PHP and SVG markup

You should be comfortable editing theme files and working inside functions.php or a plugin file. If you are new to SVG sprites, an SVG sprite is a single file that holds multiple icon shapes as named <symbol> elements. The Icon Registration API reads that file and makes each symbol available by ID.

You don’t need to install any extra libraries. The API ships with WordPress 7.1 core. Check the official WordPress Icon documentation to confirm your version supports the API before continuing.

Estimated time to complete this tutorial: 30 to 45 minutes.

Step-by-Step Guide to Registering Custom SVG Icon Collections in WordPress 7.1

Related tutorial: How to Harden Nginx Ssl/tls Configuration for Enhanced Security

Follow these steps carefully. Each step builds on the previous one.

Step 1: Create your SVG sprite file

First, create a folder called icons inside your theme or plugin directory. Then create a file named sprite.svg inside it.

/wp-content/themes/your-theme/icons/sprite.svg

Open that file and add your SVG symbols. Each icon gets its own <symbol> element with a unique ID.

<svg xmlns="http://www.w3.org/2000/svg" style="display:none;">
  <symbol id="icon-home" viewBox="0 0 24 24">
    <path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z"/>
  </symbol>
  <symbol id="icon-search" viewBox="0 0 24 24">
    <path d="M21 21l-4.35-4.35M17 11A6 6 0 1 1 5 11a6 6 0 0 1 12 0z"/>
  </symbol>
  <symbol id="icon-close" viewBox="0 0 24 24">
    <path d="M18 6L6 18M6 6l12 12"/>
  </symbol>
</svg>

The style="display:none;" attribute hides the sprite container from view. The browser still loads and parses the symbols.

Step 2: Open your functions.php or plugin file

Navigate to your theme’s functions.php file using SSH or your file manager.

nano /var/www/html/wp-content/themes/your-theme/functions.php

If you are building a plugin, open your main plugin PHP file instead. Always work inside a child theme. Never edit a parent theme directly.

Step 3: Register the icon collection using wp_register_svg_icons()

WordPress 7.1 introduced the wp_register_svg_icons() function. Call it inside an init hook.

add_action( 'init', 'akensai_register_icon_collection' );

function akensai_register_icon_collection() {
    wp_register_svg_icons(
        'akensai-icons',
        get_theme_file_path( 'icons/sprite.svg' ),
        array(
            'icon-home',
            'icon-search',
            'icon-close',
        )
    );
}

The first argument is your collection handle. Use a unique prefix to avoid conflicts with other plugins. The second argument is the absolute path to your sprite file. The third argument is an array of icon IDs available in that collection.

Step 4: Output an icon in your template

Use the wp_get_svg_icon() function to render an individual icon anywhere in your templates.

<?php echo wp_get_svg_icon( 'akensai-icons', 'icon-home' ); ?>

This outputs a clean <svg> element with a <use> tag referencing the correct symbol. You don’t need to write any inline SVG manually.

Step 5: Add CSS classes for sizing and styling

The function accepts an optional third argument for extra attributes.

<?php
echo wp_get_svg_icon(
    'akensai-icons',
    'icon-search',
    array( 'class' => 'site-icon site-icon--search', 'aria-label' => 'Search' )
);
?>

Then add your styles in style.css.

.site-icon {
  width: 24px;
  height: 24px;
  fill: currentColor;
}

Using fill: currentColor means the icon inherits the text color of its parent element automatically.

Step 6: Verify the registration in WordPress admin

Go to Appearance > Theme File Editor or use WP-CLI to confirm the hook fired correctly.

wp eval "var_dump( wp_get_registered_svg_icons() );"

You should see your collection handle and icon list in the output. If the array is empty, check that your init hook is loading properly and that the sprite file path is correct.

Step 7: Enqueue the sprite file for block editor support

If you need icons inside the Gutenberg block editor, enqueue the sprite on the enqueue_block_editor_assets hook as well.

add_action( 'enqueue_block_editor_assets', 'akensai_enqueue_editor_sprite' );

function akensai_enqueue_editor_sprite() {
    wp_enqueue_script(
        'akensai-svg-sprite',
        get_theme_file_uri( 'icons/sprite.svg' ),
        array(),
        '1.0.0',
        true
    );
}

This makes your custom icons available inside the block editor interface. See the WordPress theme asset enqueuing guide for more details on enqueueing assets correctly.

Troubleshooting Common Issues with SVG Icon Registration

Icons not showing up on the front end

Check that your sprite file path uses get_theme_file_path() and not get_template_directory_uri(). The registration function needs a server file path, not a URL.

Icons display as broken boxes

This usually means the symbol ID in your sprite doesn’t match the ID you passed to wp_get_svg_icon(). Open your sprite.svg and double-check each id attribute. IDs are case-sensitive.

SVG file returns a 404 error

Your web server might be blocking SVG files. Add this rule to your .htaccess file.

AddType image/svg+xml .svg

On Nginx, add the following to your server block.

types {
    image/svg+xml svg;
}

Icons look distorted

Always include a viewBox attribute on each <symbol> element. Without it, the browser can’t scale the icon correctly.

Hook fires too late

If you registered icons on a hook that fires after init, they won’t be available to early-loading blocks. Move your registration call to the init action as shown in Step 3.

Conclusion: What You’ve Accomplished with the Icon Registration API

You now know exactly how to register custom SVG icon collections in WordPress 7.1 using the Icon Registration API. You built a sprite file, registered a named collection with a unique handle, and output individual icons in your templates with full CSS control. This approach is far cle

Similar Posts