Registering custom social icons in WordPress 6.9

It’s been nearly six years since a community member opened a ticket to request an extension architecture for the Social Icons block. While it may have felt like a long wait, the day has finally arrived.

Gutenberg 21.1 shipped with the necessary changes to turn this wish for extending the block into a reality. This means the changes are set to be included in the WordPress 6.9, which is slated for release on December 2, 2025.

Admittedly, I’ve had a lot of fun with this over the last few weeks, tinkering with various ideas for adding more social services that users can choose from. But it was time to share what I’ve learned with you all. So let’s start building a plugin together!

In this tutorial, you’ll learn how to set up a plugin, register social icons for the editor, register them for the front end, and optionally style them with CSS. If you want to follow along with the finished code while reading, feel free to clone the GitHub repository.

You must be running Gutenberg 21.1+ to test out the features in this tutorial at the time of writing. Otherwise, WordPress 6.9 or newer.

Table of Contents

Plugin setup

Before diving into the good stuff, you need to get through the normal boilerplate of setting your plugin up. So go ahead and create a new folder in your /wp-content/plugins directory named devblog-custom-social-icons with the following file and folder structure:

src
- index.js
- style.css
package.json
plugin.php

In your plugin.php file, add your plugin header fields:

<?php
/**
 * Plugin Name:       Dev Blog Custom Social Icons
 * Plugin URI:        https://developer.wordpress.org/news
 * Description:       Registers custom icons and services for the Social Icons block.
 * Version:           1.0.0
 * Requires at least: 6.8
 * Requires PHP:      7.4
 * Requires Plugins:  gutenberg
 * Author:            Your Name
 * Author URI:        https://developer.wordpres.org/news
 * Text Domain:       devblog
 */

The next step is to add your project name and a couple of scripts to the package.json file:

{
	"name": "devblog-custom-social-icons",
	"scripts": {
		"start": "wp-scripts start",
		"build": "wp-scripts build"
	}
}

Then open your preferred command line tool and navigate to the /wp-content/plugins/devblog-custom-social-icons directory.

You need to install the @wordpress/scripts package by running the command below. If you’ve never done this, I recommend the Getting started with wp-scripts guide.

npm install @wordpress/scripts --save-dev

Once your dependencies are imported, go ahead and run the start command:

npm run start

With all the setup out of the way, now we get to jump into the fun bits.

To register custom social icons in the editor, you must do so using JavaScript. Inside your src/index.js file, you’ll register custom Block Variations.

Start by adding your JavaScript to the script queue, putting this code into your plugin.php file:

add_action( 'enqueue_block_editor_assets', 'devblog_custom_social_icons_editor_assets' );

function devblog_custom_social_icons_editor_assets() {
	$dir = untrailingslashit( plugin_dir_path( __FILE__ ) );
	$url = untrailingslashit( plugin_dir_url( __FILE__ ) );

	if ( file_exists( "{$dir}/build/index.asset.php" )) {
		$asset = include "{$dir}/build/index.asset.php";

		wp_enqueue_script(
			'devblog-custom-social-icons',
			"{$url}/build/index.js",
			$asset['dependencies'],
			$asset['version'],
			true
		);
	}
}

Then, open your src/index.js file and import a couple of necessary dependencies for registering variations and working with SVGs:

import { registerBlockVariation } from '@wordpress/blocks';
import {SVG, Path} from '@wordpress/primitives';

Adding your first custom icon

Custom social icons are nothing more than variations of the core/social-link block. This is how all icons are registered, even those bundled with WordPress.

Take a look at how this should be formatted when registering your own variation:

registerBlockVariation('core/social-link', {
	name: 'the-variation-name',
	title: 'The Service Title',
	icon: theVariationIcon,
	attributes: {
		service: 'the-service-name',
	},
	isActive: ['service']
});

I want to draw your attention to two properties in particular:

attributes.service: This should be a unique name that represents the social service you want to register.
isActive: This is set to an array with the service attribute passed in. This tells WordPress that the variation is active when the service attribute matches that of the variation.

Let’s try registering a social icon for the popular Ko-fi service. Add this code to your index.js file:

registerBlockVariation('core/social-link', {
	name: 'kofi',
	title: 'Ko-fi',
	icon: (
		<SVG role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
			<Path d="M11.351 2.715c-2.7 0-4.986.025-6.83.26C2.078 3.285 0 5.154 0 8.61c0 3.506.182 6.13 1.585 8.493 1.584 2.701 4.233 4.182 7.662 4.182h.83c4.209 0 6.494-2.234 7.637-4a9.5 9.5 0 0 0 1.091-2.338C21.792 14.688 24 12.22 24 9.208v-.415c0-3.247-2.13-5.507-5.792-5.87-1.558-.156-2.65-.208-6.857-.208m0 1.947c4.208 0 5.09.052 6.571.182 2.624.311 4.13 1.584 4.13 4v.39c0 2.156-1.792 3.844-3.87 3.844h-.935l-.156.649c-.208 1.013-.597 1.818-1.039 2.546-.909 1.428-2.545 3.064-5.922 3.064h-.805c-2.571 0-4.831-.883-6.078-3.195-1.09-2-1.298-4.155-1.298-7.506 0-2.181.857-3.402 3.012-3.714 1.533-.233 3.559-.26 6.39-.26m6.547 2.287c-.416 0-.65.234-.65.546v2.935c0 .311.234.545.65.545 1.324 0 2.051-.754 2.051-2s-.727-2.026-2.052-2.026m-10.39.182c-1.818 0-3.013 1.48-3.013 3.142 0 1.533.858 2.857 1.949 3.897.727.701 1.87 1.429 2.649 1.896a1.47 1.47 0 0 0 1.507 0c.78-.467 1.922-1.195 2.623-1.896 1.117-1.039 1.974-2.364 1.974-3.897 0-1.662-1.247-3.142-3.039-3.142-1.065 0-1.792.545-2.338 1.298-.493-.753-1.246-1.298-2.312-1.298"/>
		</SVG>
	),
	attributes: {
		service: 'kofi',
	},
	isActive: ['service']
});

Then try going to your editor and inserting a Social Icons block, and inside, adding the new Ko-fi variation. You should see something like the following examples, depending on what style or settings you choose:

You’ll notice that you don’t have any brand colors associated with the icon. We’ll get to that later. For now, you have a custom icon. So take a moment to celebrate!

Of course, you might want to add some other icons just to further test things out. I took the liberty of creating a few variations for IMDB, Letterboxd, Signal, and YouTube Music.

Try registering them by adding this code to your src/index.js file:

registerBlockVariation('core/social-link', {
	name: 'imdb',
	title: 'IMDB',
	icon: (
		<SVG role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
			<Path d="M22.3781 0H1.6218C.7411.0583.0587.7437.0018 1.5953l-.001 20.783c.0585.8761.7125 1.543 1.5559 1.6191A.337.337 0 0 0 1.6016 24h20.7971a.4579.4579 0 0 0 .0437-.002c.8727-.0768 1.5568-.8271 1.5568-1.7085V1.7098c0-.8914-.696-1.6416-1.584-1.7078A.3294.3294 0 0 0 22.3781 0zm0 .496a1.2144 1.2144 0 0 1 1.1252 1.2139v20.5797c0 .6377-.4875 1.1602-1.1045 1.2145H1.6016c-.5967-.0543-1.0645-.5297-1.1053-1.1258V1.6284C.5371 1.0185 1.0184.5364 1.6217.496h20.7564zM4.7954 8.2603v7.3636H2.8899V8.2603h1.9055zm6.5367 0v7.3636H9.6707v-4.9704l-.6711 4.9704H7.813l-.6986-4.8618-.0066 4.8618h-1.668V8.2603h2.468c.0748.4476.1492.9694.2307 1.5734l.2712 1.8713.4407-3.4447h2.4817zm2.9772 1.3289c.0742.0404.122.108.1417.2034.0279.0953.0345.3118.0345.6442v2.8548c0 .4881-.0345.7867-.0955.8954-.0609.1152-.2304.1695-.5018.1695V9.5211c.204 0 .3457.0205.4211.0681zm-.0211 6.0347c.4543 0 .8006-.0265 1.0245-.0742.2304-.0477.4204-.1357.5694-.2648.1556-.1218.2642-.298.3251-.5219.0611-.2238.1021-.6648.1021-1.3224v-2.5832c0-.6986-.0271-1.1668-.0742-1.4039-.041-.237-.1431-.4543-.3126-.6437-.1695-.1973-.4198-.3324-.7456-.421-.3191-.0808-.8542-.1285-1.7694-.1285h-1.4244v7.3636h2.3051zm5.14-1.7827c0 .3523-.0199.5762-.0544.6708-.033.0947-.1894.1424-.3046.1424-.1086 0-.19-.0477-.2238-.1351-.041-.0887-.0609-.2986-.0609-.6238v-1.9469c0-.3324.0199-.5423.0543-.6237.0338-.0808.1086-.122.2171-.122.1153 0 .2709.0412.3114.1425.041.0947.0609.2986.0609.6032v1.8926zm-2.4747-5.5809v7.3636h1.7157l.1152-.4675c.1556.1894.3251.3324.5152.4271.1828.0881.4608.1357.678.1357.3047 0 .5629-.0748.7802-.237.2165-.1562.3589-.3462.4198-.5628.0543-.2173.0887-.543.0887-.9841v-2.0675c0-.4409-.0139-.7324-.0344-.8681-.0199-.1357-.0742-.2781-.1695-.4204-.1021-.1425-.2437-.251-.4272-.3325-.1834-.0742-.3999-.1152-.6576-.1152-.2172 0-.4952.0477-.6846.1285-.1835.0887-.353.2238-.5086.4007V8.2603h-1.8309z"/>
		</SVG>
	),
	attributes: {
		service: 'imdb',
	},
	isActive: ['service']
});

registerBlockVariation('core/social-link', {
	name: 'letterboxd',
	title: 'Letterboxd',
	icon: (
		<SVG role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
			<Path d="M8.224 14.352a4.447 4.447 0 0 1-3.775 2.092C1.992 16.444 0 14.454 0 12s1.992-4.444 4.45-4.444c1.592 0 2.988.836 3.774 2.092-.427.682-.673 1.488-.673 2.352s.246 1.67.673 2.352zM15.101 12c0-.864.247-1.67.674-2.352-.786-1.256-2.183-2.092-3.775-2.092s-2.989.836-3.775 2.092c.427.682.674 1.488.674 2.352s-.247 1.67-.674 2.352c.786 1.256 2.183 2.092 3.775 2.092s2.989-.836 3.775-2.092A4.42 4.42 0 0 1 15.1 12zm4.45-4.444a4.447 4.447 0 0 0-3.775 2.092c.427.682.673 1.488.673 2.352s-.246 1.67-.673 2.352a4.447 4.447 0 0 0 3.775 2.092C22.008 16.444 24 14.454 24 12s-1.992-4.444-4.45-4.444z"/>
		</SVG>
	),
	attributes: {
		service: 'letterboxd',
	},
	isActive: ['service']
});

registerBlockVariation('core/social-link', {
	name: 'signal',
	title: 'Signal',
	icon: (
		<SVG role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
			<Path d="M12 0q-.934 0-1.83.139l.17 1.111a11 11 0 0 1 3.32 0l.172-1.111A12 12 0 0 0 12 0M9.152.34A12 12 0 0 0 5.77 1.742l.584.961a10.8 10.8 0 0 1 3.066-1.27zm5.696 0-.268 1.094a10.8 10.8 0 0 1 3.066 1.27l.584-.962A12 12 0 0 0 14.848.34M12 2.25a9.75 9.75 0 0 0-8.539 14.459c.074.134.1.292.064.441l-1.013 4.338 4.338-1.013a.62.62 0 0 1 .441.064A9.7 9.7 0 0 0 12 21.75c5.385 0 9.75-4.365 9.75-9.75S17.385 2.25 12 2.25m-7.092.068a12 12 0 0 0-2.59 2.59l.909.664a11 11 0 0 1 2.345-2.345zm14.184 0-.664.909a11 11 0 0 1 2.345 2.345l.909-.664a12 12 0 0 0-2.59-2.59M1.742 5.77A12 12 0 0 0 .34 9.152l1.094.268a10.8 10.8 0 0 1 1.269-3.066zm20.516 0-.961.584a10.8 10.8 0 0 1 1.27 3.066l1.093-.268a12 12 0 0 0-1.402-3.383M.138 10.168A12 12 0 0 0 0 12q0 .934.139 1.83l1.111-.17A11 11 0 0 1 1.125 12q0-.848.125-1.66zm23.723.002-1.111.17q.125.812.125 1.66c0 .848-.042 1.12-.125 1.66l1.111.172a12.1 12.1 0 0 0 0-3.662M1.434 14.58l-1.094.268a12 12 0 0 0 .96 2.591l-.265 1.14 1.096.255.36-1.539-.188-.365a10.8 10.8 0 0 1-.87-2.35m21.133 0a10.8 10.8 0 0 1-1.27 3.067l.962.584a12 12 0 0 0 1.402-3.383zm-1.793 3.848a11 11 0 0 1-2.345 2.345l.664.909a12 12 0 0 0 2.59-2.59zm-19.959 1.1L.357 21.48a1.8 1.8 0 0 0 2.162 2.161l1.954-.455-.256-1.095-1.953.455a.675.675 0 0 1-.81-.81l.454-1.954zm16.832 1.769a10.8 10.8 0 0 1-3.066 1.27l.268 1.093a12 12 0 0 0 3.382-1.402zm-10.94.213-1.54.36.256 1.095 1.139-.266c.814.415 1.683.74 2.591.961l.268-1.094a10.8 10.8 0 0 1-2.35-.869zm3.634 1.24-.172 1.111a12.1 12.1 0 0 0 3.662 0l-.17-1.111q-.812.125-1.66.125a11 11 0 0 1-1.66-.125"/>
		</SVG>
	),
	attributes: {
		service: 'signal',
	},
	isActive: ['service']
});

registerBlockVariation('core/social-link', {
	name: 'youtube-music',
	title: 'YouTube Music',
	icon: (
		<SVG role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
			<Path d="M12 0C5.376 0 0 5.376 0 12s5.376 12 12 12 12-5.376 12-12S18.624 0 12 0zm0 19.104c-3.924 0-7.104-3.18-7.104-7.104S8.076 4.896 12 4.896s7.104 3.18 7.104 7.104-3.18 7.104-7.104 7.104zm0-13.332c-3.432 0-6.228 2.796-6.228 6.228S8.568 18.228 12 18.228s6.228-2.796 6.228-6.228S15.432 5.772 12 5.772zM9.684 15.54V8.46L15.816 12l-6.132 3.54z"/>
		</SVG>
	),
	attributes: {
		service: 'youtube-music',
	},
	isActive: ['service']
});

Now give them a try, testing how they look with various styles and settings on the Social Icons block:

How fun!

Registering on the front end

If you’ve already looked at your post on the front end of the website, you probably saw something like this:

Wait! That doesn’t look right!

You might be wondering where the icons are. WordPress doesn’t have a way of knowing what those icons should be on the server, and therefore, on the frontend output of your site.

So the next step is to tell WordPress about them. You do this by filtering block_core_social_link_get_services. This is a new filter hook being introduced in WordPress 6.9. Here’s what the hook looks like:

$services_data = apply_filters( 
	'block_core_social_link_get_services', 
	$services_data 
);

The $services_data parameter that is passed to filters contains an array of social services where you can define both the name and icon values.

Let’s add a custom filter so that WordPress can display the icons on the front end. Add this code to your plugin.php file:

add_filter( 'block_core_social_link_get_services', 'devblog_social_link_services' );

function devblog_social_link_services(array $services_data) {

	$services_data['imdb'] = [
		'name' => 'IMDB',
		'icon' => '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><path d="M400 32H48C21.5 32 0 53.5 0 80v352c0 26.5 21.5 48 48 48h352c26.5 0 48-21.5 48-48V80c0-26.5-21.5-48-48-48zM21.3 229.2H21c.1-.1 .2-.3 .3-.4zM97 319.8H64V192h33zm113.2 0h-28.7v-86.4l-11.6 86.4h-20.6l-12.2-84.5v84.5h-29V192h42.8c3.3 19.8 6 39.9 8.7 59.9l7.6-59.9h43zm11.4 0V192h24.6c17.6 0 44.7-1.6 49 20.9 1.7 7.6 1.4 16.3 1.4 24.4 0 88.5 11.1 82.6-75 82.5zm160.9-29.2c0 15.7-2.4 30.9-22.2 30.9-9 0-15.2-3-20.9-9.8l-1.9 8.1h-29.8V192h31.7v41.7c6-6.5 12-9.2 20.9-9.2 21.4 0 22.2 12.8 22.2 30.1zM265 229.9c0-9.7 1.6-16-10.3-16v83.7c12.2 .3 10.3-8.7 10.3-18.4zm85.5 26.1c0-5.4 1.1-12.7-6.2-12.7-6 0-4.9 8.9-4.9 12.7 0 .6-1.1 39.6 1.1 44.7 .8 1.6 2.2 2.4 3.8 2.4 7.8 0 6.2-9 6.2-14.4z"/></svg>'
	];

	$services_data['letterboxd'] = [
		'name' => 'Letterboxd',
		'icon' => '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 512"><path d="M521.3 128C586.9 128 640 181.1 640 246.6s-53.1 118.6-118.7 118.6c-42.5 0-79.7-22.3-100.7-55.8c11.4-18.2 18-39.7 18-62.8s-6.6-44.6-18-62.8l0 0 .8-1.2c20.8-32.3 56.8-53.9 97.9-54.6l2 0zM320 128c42.5 0 79.7 22.3 100.7 55.8c-11.4 18.2-18 39.7-18 62.8s6.6 44.6 18 62.8l0 0-.8 1.2c-20.8 32.3-56.8 53.9-97.9 54.6l-2 0c-42.5 0-79.7-22.3-100.7-55.8c11.4-18.2 18-39.7 18-62.8s-6.6-44.6-18-62.8l0 0 .8-1.2c20.8-32.3 56.8-53.9 97.9-54.6l2 0zm-201.3 0c42.5 0 79.7 22.3 100.7 55.8c-11.4 18.2-18 39.7-18 62.8s6.6 44.6 18 62.8l0 0-.8 1.2c-20.8 32.3-56.8 53.9-97.9 54.6l-2 0C53.1 365.1 0 312.1 0 246.6S53.1 128 118.7 128z"/></svg>'
	];

	$services_data['kofi'] = [
		'name' => 'Kofi',
		'icon' => '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M11.351 2.715c-2.7 0-4.986.025-6.83.26C2.078 3.285 0 5.154 0 8.61c0 3.506.182 6.13 1.585 8.493 1.584 2.701 4.233 4.182 7.662 4.182h.83c4.209 0 6.494-2.234 7.637-4a9.5 9.5 0 0 0 1.091-2.338C21.792 14.688 24 12.22 24 9.208v-.415c0-3.247-2.13-5.507-5.792-5.87-1.558-.156-2.65-.208-6.857-.208m0 1.947c4.208 0 5.09.052 6.571.182 2.624.311 4.13 1.584 4.13 4v.39c0 2.156-1.792 3.844-3.87 3.844h-.935l-.156.649c-.208 1.013-.597 1.818-1.039 2.546-.909 1.428-2.545 3.064-5.922 3.064h-.805c-2.571 0-4.831-.883-6.078-3.195-1.09-2-1.298-4.155-1.298-7.506 0-2.181.857-3.402 3.012-3.714 1.533-.233 3.559-.26 6.39-.26m6.547 2.287c-.416 0-.65.234-.65.546v2.935c0 .311.234.545.65.545 1.324 0 2.051-.754 2.051-2s-.727-2.026-2.052-2.026m-10.39.182c-1.818 0-3.013 1.48-3.013 3.142 0 1.533.858 2.857 1.949 3.897.727.701 1.87 1.429 2.649 1.896a1.47 1.47 0 0 0 1.507 0c.78-.467 1.922-1.195 2.623-1.896 1.117-1.039 1.974-2.364 1.974-3.897 0-1.662-1.247-3.142-3.039-3.142-1.065 0-1.792.545-2.338 1.298-.493-.753-1.246-1.298-2.312-1.298"/></svg>'
	];

	$services_data['signal'] = [
		'name' => 'Signal',
		'icon' => '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M12 0q-.934 0-1.83.139l.17 1.111a11 11 0 0 1 3.32 0l.172-1.111A12 12 0 0 0 12 0M9.152.34A12 12 0 0 0 5.77 1.742l.584.961a10.8 10.8 0 0 1 3.066-1.27zm5.696 0-.268 1.094a10.8 10.8 0 0 1 3.066 1.27l.584-.962A12 12 0 0 0 14.848.34M12 2.25a9.75 9.75 0 0 0-8.539 14.459c.074.134.1.292.064.441l-1.013 4.338 4.338-1.013a.62.62 0 0 1 .441.064A9.7 9.7 0 0 0 12 21.75c5.385 0 9.75-4.365 9.75-9.75S17.385 2.25 12 2.25m-7.092.068a12 12 0 0 0-2.59 2.59l.909.664a11 11 0 0 1 2.345-2.345zm14.184 0-.664.909a11 11 0 0 1 2.345 2.345l.909-.664a12 12 0 0 0-2.59-2.59M1.742 5.77A12 12 0 0 0 .34 9.152l1.094.268a10.8 10.8 0 0 1 1.269-3.066zm20.516 0-.961.584a10.8 10.8 0 0 1 1.27 3.066l1.093-.268a12 12 0 0 0-1.402-3.383M.138 10.168A12 12 0 0 0 0 12q0 .934.139 1.83l1.111-.17A11 11 0 0 1 1.125 12q0-.848.125-1.66zm23.723.002-1.111.17q.125.812.125 1.66c0 .848-.042 1.12-.125 1.66l1.111.172a12.1 12.1 0 0 0 0-3.662M1.434 14.58l-1.094.268a12 12 0 0 0 .96 2.591l-.265 1.14 1.096.255.36-1.539-.188-.365a10.8 10.8 0 0 1-.87-2.35m21.133 0a10.8 10.8 0 0 1-1.27 3.067l.962.584a12 12 0 0 0 1.402-3.383zm-1.793 3.848a11 11 0 0 1-2.345 2.345l.664.909a12 12 0 0 0 2.59-2.59zm-19.959 1.1L.357 21.48a1.8 1.8 0 0 0 2.162 2.161l1.954-.455-.256-1.095-1.953.455a.675.675 0 0 1-.81-.81l.454-1.954zm16.832 1.769a10.8 10.8 0 0 1-3.066 1.27l.268 1.093a12 12 0 0 0 3.382-1.402zm-10.94.213-1.54.36.256 1.095 1.139-.266c.814.415 1.683.74 2.591.961l.268-1.094a10.8 10.8 0 0 1-2.35-.869zm3.634 1.24-.172 1.111a12.1 12.1 0 0 0 3.662 0l-.17-1.111q-.812.125-1.66.125a11 11 0 0 1-1.66-.125"/></svg>'
	];

	$services_data['youtube-music'] = [
		'name' => 'Youtube Music',
		'icon' => '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M12 0C5.376 0 0 5.376 0 12s5.376 12 12 12 12-5.376 12-12S18.624 0 12 0zm0 19.104c-3.924 0-7.104-3.18-7.104-7.104S8.076 4.896 12 4.896s7.104 3.18 7.104 7.104-3.18 7.104-7.104 7.104zm0-13.332c-3.432 0-6.228 2.796-6.228 6.228S8.568 18.228 12 18.228s6.228-2.796 6.228-6.228S15.432 5.772 12 5.772zM9.684 15.54V8.46L15.816 12l-6.132 3.54z"/></svg>'
	];

	return $services_data;
}

Now refresh that same page and see the changes in action:

That’s much better! Especially since it actually matches what you see in the editor. But there’s one more step to really make this shine.

Adding colors to icons

If you’re building a site where you set your Social Icons block to a single background and foreground color, you may not need this step. If you’re building a site that uses the brand colors of the services you’ve registered or a general-audience plugin, you need to add a bit of CSS.

The first step is to revisit your src/index.js file to import your stylesheet. Add this code to the top of the file:

import './style.css';

Note that src/style.css becomes build/style-index.css when it’s run through the build process.

Now, enqueue your stylesheet to ensure that it’s loaded in both the editor and on the front end. Add this code to plugin.php:

add_action( 'init', 'devblog_enqueue_block_assets' );

function devblog_enqueue_block_assets() {
	$dir = untrailingslashit( plugin_dir_path( __FILE__ ) );
	$url = untrailingslashit( plugin_dir_url( __FILE__ ) );

	if ( file_exists( "{$dir}/build/index.asset.php" )) {
		$asset = include "{$dir}/build/index.asset.php";

		wp_enqueue_block_style('core/social-links', [
			'handle' => 'devblog-block-social-links',
			'src'    => "{$url}/build/style-index.css",
			'path'   => "{$dir}/build/style-index.css",
			'ver'    => $asset['version']
		]);
	}
}

Before styling social icons, it’s important to ensure that you’re adhering to each service’s brand guidelines. Please check those to get the right color codes to add to your stylesheet. For this tutorial, I’ve grabbed the current brand colors for the services I’ve shown.

There are two cases that you need to account for when styling icons in the Social Icons block:

When the block has the Logos Only block style variation, you should use the primary brand color to style the icon.
And when it doesn’t have the variation, you must define both the background color and the icon color.

Add this code to build/style.css:

/* IMDB */
:where(.wp-block-social-links.is-style-logos-only) .wp-social-link-imdb {
	color: #000000;
}

:where(.wp-block-social-links:not(.is-style-logos-only)) .wp-social-link-imdb {
	background-color: #F5C518;
	color: #000000;
}

/* Ko-fi */
:where(.wp-block-social-links.is-style-logos-only) .wp-social-link-kofi {
	color: #72A5F2;
}

:where(.wp-block-social-links:not(.is-style-logos-only)) .wp-social-link-kofi {
	background-color: #72A5F2;
	color: #ffffff;
}

/* Letterboxd */
:where(.wp-block-social-links.is-style-logos-only) .wp-social-link-letterboxd {
	color: #202830;
}

:where(.wp-block-social-links:not(.is-style-logos-only)) .wp-social-link-letterboxd {
	background-color: #3B45FD;
	color:#fff;
}

/* Signal */
:where(.wp-block-social-links.is-style-logos-only) .wp-social-link-signal {
	color: #3B45FD;
}

:where(.wp-block-social-links:not(.is-style-logos-only)) .wp-social-link-signal {
	background-color: #3B45FD;
	color:#fff;
}

/* YouTube Music */
:where(.wp-block-social-links.is-style-logos-only) .wp-social-link-youtube-music {
	color: #FF0000;
}

:where(.wp-block-social-links:not(.is-style-logos-only)) .wp-social-link-youtube-music {
	background-color: #FF0000;
	color:#fff;
}

Now you can see your custom icons with the associated brand colors:

All that’s left to do is have fun by rolling out the social services and icons that you need for your next project!

Props to @bph and @psykro for feedback and reviewing this article.

5 responses to “Registering custom social icons in WordPress 6.9”

Michael Sumner

August 20, 2025

Great article, thanks for sharing. It’s been really handy to see tutorials like this as it helps make the documentation friendlier to arrive into. And this becomes a journey for new WordPress developers in the future to see how easy it is to get this all set up and customizable and how extensible it is with descriptions along the way.

Sybre Waaijer

August 20, 2025

Why haven’t you considered building middleware that can allow this code…

“`php
register_icon( [
‘icon’ => ‘<svg…’,
‘name’ => ‘kofi’,
‘title’ => ‘Ko-fi’,
] );
“`

…instead of having developers create all sorts of abominations every time they want to conflict with Gutenberg? Nothing so far has been easy, while everything could have been.

1. George Mamadashvili
  
  August 21, 2025
  
  There’s a separate proposal for icon registration. The Social Icons block will use that API when it’s ready. Link: https://github.com/WordPress/gutenberg/discussions/53510.
  
  Currently, there are no singular block-specific APIs in WP core for various reasons.
  
2. Alberto Prado
  
  September 22, 2025
  
  I agree with this comment. I don’t dislike Gutenberg (I already have a couple of blogs that use the block editor for everything), but it’s incredible that such a simple modification requires so much code. This code doesn’t seem like poetry; it’s a whole encyclopedia.
  
  1. Justin Tadlock
    
    September 23, 2025
    
    It’s fewer than two dozen lines of code for the actual registration. Almost everything else in the tutorial is just boilerplate plugin setup, which is necessary for any plugin.
    
    Should it require even that much code? Maybe not, but let’s avoid hyperbole.

Registering custom social icons in WordPress 6.9

Plugin setup

Adding your first custom icon

Registering on the front end

Adding colors to icons

5 responses to “Registering custom social icons in WordPress 6.9”

Leave a Reply Cancel reply

Have an idea for a new post?

Learn how to contribute

Review tips and guidelines

Subscribe to the Blog

Plugin setup

Registering social icons in the editor

Adding your first custom icon

Adding multiple social icons

Registering on the front end

Adding colors to icons

5 responses to “Registering custom social icons in WordPress 6.9”

Leave a Reply Cancel reply

Have an idea for a new post?

Learn how to contribute

Review tips and guidelines

Subscribe to the Blog