All You Need to Know About the New WordPress Site Icon API

By Jérémy Heleine
We teamed up with SiteGround
To bring you the latest from the web and tried-and-true hosting, recommended for designers and developers. SitePoint Readers Get Up To 65% OFF Now

With the release of version 4.3, WordPress introduced Site Icons, which allows users to define an icon that represents their website. As often occurs, this new concept has an associated API.

This article will delve into Site Icons, beginning by defining what they are. Then, we will play with this brand new API, which is essentially composed of four functions and two filters. This doesn’t sound like much, but you’ll see that it is definitely enough!

What Is a Site Icon?

Good news: if you’ve worked with the web for a while, then you probably already know what a Site Icon is. In fact, it is just the name WordPress has given to an icon we all know well: the favicon.

A favicon is the image displayed on the browser’s tab when your website is opened. In addition, when you save a shortcut to a webpage on the home screen of your smartphone, your mobile OS uses your favicon so that the same generic icon is not displayed for every website.

Once set up, the Site Icon will also be displayed on your administration panel, which was, until now didn’t have a favicon.

By defining a Site Icon, you therefore define your website’s favicon. The good news is that, as a user or a theme developer, you don’t have to do anything to activate the feature. In fact, the display of the Site Icon is activated by default in WordPress 4.3: the call for the right function is done when the wp_head action occurs and every theme must call this action.

This means one thing: if you want to try what we do in this article, you can do it without changing your current theme. The only thing you must do before following this tutorial is update your WordPress installation to version 4.3 (see our article about updating your WordPress installation if you haven’t already done so.

How To Define a Site Icon

Defining a new Site Icon can be achieved by using the Theme Customizer. You have two ways to access this customizer:

  • By using the administration menu, the customizer is located in the ‘Appearance’ menu, with the second entry named ‘Customize’
  • By hitting the ‘Customize’ button in the administration bar, which appears at the top of every page of your website once you are logged in (this button is new to WordPress 4.3)

theme customizer

The Theme Customizer consists of a preview of your website, with a sidebar on the left allowing you to customize some details. For the purposes of this tutorial, we’re interested in the ‘Site Identity’ menu option.

If you have already used the Theme Customizer, you might have noticed a change: the ‘Site Title & Tagline’ menu option has been replaced by ‘Site Identity’. This new name reflects the changes made to this menu option: you can now set not only your site’s title and tagline, but also its Site Icon.

If it’s the first time you have played with Site Icons, WordPress will show you the text ‘No file selected’ and you will be able to select an image to use as your Site Icon by hitting the ‘Select File’ button right below.

set site icon

A media window will then be opened. You already know this window, as it is the same as you see everywhere you can select a media file. You can select an already uploaded image, or you can upload a new one. To ensure you have a good image quality in every context, you should upload an image which is, according to WordPress, “at least 512 pixels wide and tall”.

Once you’ve selected your image, you can choose to crop it and only select the square to really use as your Site Icon. Note that cropping this image won’t alter the original file, so you can crop it without worrying about the display of your original file, if you chose an existing image file.


Next, once you’ve selected the square that you want to use, hit the ‘Crop Image’ button in the bottom right corner of the window and wait for the magic to happen!

WordPress will automatically resize your image to the dimensions that needs (for example, WordPress will create a 512 pixels wide square, even if your image is smaller than 512 pixels).

To save the change you just made, hit the ‘Save & Publish’ button at the top of the Theme Customizer. Now you should see your brand new favicon on every page of your website.

You can remove and change the Site Icon at any stage, by using the Theme Customizer.

change site icon

Retrieving the Current Site Icon

Retrieving your current site icon is all automatic. As a theme or plugin developer, you don’t have to worry about the Site Icon for its basic usage: once the image is selected, WordPress will automatically display it as a favicon.

However, if you need to retrieve the current Site Icon for any reason in your theme or your plugin, it’s possible. For example, if you’re developing a theme, you can show your own favicon manager in an administration panel if the user hasn’t defined a Site Icon (you can also redirect them to the Theme Customizer).

WordPress Site Icon Functions API

At the moment, WordPress provides four functions in the Site Icon public API. We will review each of them.

Knowing If a Site Icon Is Set

The first function we’ll see is has_site_icon(). As its name suggests, this function allows you to see whether a Site Icon is set. That way you can indicate to your users to set a Site Icon.

This function returns a boolean: true if a Site Icon is set, false otherwise.

if (has_site_icon()) {
	// User set a Site Icon, do something awesome!
else {
	// User didn't set a Site Icon, do something else. But still awesome.

Retrieving the Site Icon URLs

WordPress provides two functions that enable us to retrieve the current Site Icon URLs: get_site_icon_url() and site_icon_url(). As we said above, WordPress generates several files in different sizes for a Site Icon. That’s why there is no error in the title of this part: there are several URLs we can retrieve.

We will begin with get_site_icon_url(). It can be used without a parameter: it will then return the current Site Icon, in its 512 pixels size.

if (has_site_icon())
	echo 'Site Icon';

But, we can also pass to this function three parameters. All of them are optional.

The first parameter is the ID of the blog on which you want the Site Icon; this is useful when Multisite is enabled. By default, this parameter is set to null and the current site is retrieved. In most cases, that’s the behavior we want, so you can continue to pass null as the first parameter.

The second parameter is more interesting, as it defines the wanted size for the Site Icon. You can indicate any size you want, but remember that WordPress won’t generate a new image for you: it will instead return the lower size, which is greater than the value you indicated if you indicated a value lower than 512. If you indicated a value greater or equal than 512, it will always return the 512 pixel version of the image.

For example, the following won’t display a 200 pixels wide image, but will instead display a 270 pixel wide version (with the default generated sizes).

if (has_site_icon())
	echo 'Site Icon';

Finally, the third parameter is the URL of the image you want to see if no Site Icon is found. It’s a good way to define a fallback URL without having to test by ourselves if the returned URL is empty or not.

The second function we can cite when we talk about retrieving a Site Icon is site_icon_url(). It echoes the URL of the current Site Icon, retrieved with get_site_icon_url(). It can be used in the same way.

Echoing the Meta Tags

The last function we’ll look at is the one used by WordPress during the wp_head action: it directly echoes all the meta tags needed to indicate to the browser (or the OS on a smartphone) the available sizes for the favicon. This function is wp_site_icon() and it does not accept any parameter.

// We should be in the head tag

Defining Your Own Site Icon Sizes

By default, WordPress generates several sizes when you crop your Site Icon. It uses four different sizes for generating the meta tags:

  • A 32 pixels wide image for the classic favicon (in a browser)
  • A 180 pixels wide image for using as app icon in iOS
  • A 192 pixels wide image for using as Android or Chrome app icon
  • A 270 pixels wide image for using as a tile in Windows.

The four corresponding meta tags are all generated in the wp_site_icon() function, but what if you want to add your own sizes?

It is possible to add your own sizes, thanks to two new filters, available with WordPress 4.3 and dedicated to the Site Icon API.

The first filter is named site_icon_image_sizes and can be used to indicate the sizes you need for the Site Icon in your theme or plugin. The callback function must except for one parameter: an array containing the current sizes, which will be generated. It must return an array containing the sizes to generate (you can override the existing array, but you should just add your own).

function add_my_site_icon_sizes($sizes) {
    $sizes[] = 64;

    return $sizes;
add_filter('site_icon_image_sizes', 'add_my_site_icon_sizes');

Without using them, adding new sizes is useless. That’s why we find a second filter: site_icon_meta_tags, called when WordPress generates the meta tags corresponding to the Site Icon (in wp_site_icon()).

For this filter, your callback function must except for an array containing all the current meta tags and must return the new tags to display. Once again, if you can override the existing array, you shouldn’t do this (unless you really think that the tags generated by default are useless).

function add_my_site_icon_meta_tags($tags) {
    $tags[] = sprintf('', esc_url(get_site_icon_url(null, 64)));

    return $tags;
add_filter('site_icon_meta_tags', 'add_my_site_icon_meta_tags');

In Conclusion

With four functions and two filters, the WordPress Site Icon API is not as extensive as some other APIs, but you can see that a range of options is covered, from generating your own icon sizes, through to displaying them.

That being said, you shouldn’t use this API to display any images other than the favicon; this is not the purpose for which it has been built, and as wp_site_icon() is called by default, some side effects could be observed.

You can retrieve the filters used in this article in a little plugin available right here. Note that this example is freely inspired from the one provided by the WordPress team to introduce us to this new API.

We teamed up with SiteGround
To bring you the latest from the web and tried-and-true hosting, recommended for designers and developers. SitePoint Readers Get Up To 65% OFF Now
  • lucanos

    Which brain donor on the WordPress project decided to invent a new term just for the sake of it? Why not just use the existing vocabulary and call it a “favicon”?

    • Katie Keith

      I quite like the term ‘Site Icon’ as it’s intuitive for people who aren’t familiar with WordPress and web design. ‘Favicon’ is a widely used term, but a lot of non-technical people (which includes a lot of WordPress users) still don’t know what it means.

      • lucanos

        But which is a better solution? To create a new term when a well established one already exists, potentially creating confusion for all (as “favicon”-savvy people wonder what the hell a “Site Icon” is, and as “non-technical people” wonder why tools designed to help them design “Site Icons” are all titled “Favicon Generator”). Or to try and bump up the general knowledge of even those “non-technical people” by familiarising them with industry standard terms?

        If you were wanting to teach someone carpentry, you could certainly teach them to use the “thingy” to make holes in doors, but wouldn’t it be easier to teach them that the tool they need is called a “holesaw”? Same difference here.

        • Katie Keith

          Hmm, that’s a good analogy about the holesaw. We shouldn’t use jargon just because everyone else does, but it’s also important to use correct terminology. Site Icon is certainly more descriptive than Favicon, but I do see your point.

          • I think Site Icon fits well as a term since the feature is more than just a favicon. It also bundles Apple Touch icon and and other kind of icon that represents the site.

            Btw I recently wrote a tiny plugin that enhances the new Site Icon functionality by automatically including additional icon types to improve cross-browser/cross-device support. Feel free to test it, I would be happy to get some feedback. :)

          • Thanks for sharing Felix, I’ll check it out – looks cool! :)

  • Here is a method how you can get paid fifty five bucks every hour… After being without work for six-months , I started earning over this internet site and now I possibly could not be happier. After 3 months doing this my income is around five-thousand $per month -Check Link on _M_Y-PROFILE_ for more information

  • mkturner

    Thanks for exploring this new functionality and explaining it here for us so that we may benefit.

  • Katie Keith

    Site icons are a welcome new feature to the WordPress core. It’s great that WordPress automatically converts the 512px icon into various smaller sizes to minimise page load times, as they do with other types of image. It will be interesting to see whether WordPress theme authors start phasing off the favicons which are commonly added via the theme options panel as people should be using the Site Icon instead – and if they do this, will people’s existing favicons break?

    • WordPress automatically adds the `link` tags with `wp_head()`. Theme developers adds their own `link` tags. Difficult question!
      I guess that it depends on the way the browsers must manage several `link` tags for the same thing (I must admit that I don’t know what the specs say about that). Of course, I think that themes should abandon their existing systems, as Site Icons are complete so there is no need to have another system.

  • This doesn’t seem to be an option in wordpress 4.4. Any ideas how I can change the site icon now?

    • You mean that you don’t see the Site Option in the customizer?

      Pretty weird, as I’m using WordPress 4.4 and I see it. Are you sure you have the rights to edit it?

  • Diana-Alina Gazdac

    I cannot see the option in WordPress. I have 4.4.1 and Parallax One theme..If i installed your plugin, how can I set up my fav icon? Thanks in advance.

    • There’s nothing to do to activate the feature and the plugin I provide is just an example plugin, here to show how to personalize the sizes of the Site Icon so it won’t help you. What sections do you see in the Theme Customizer?

  • Tom Nunan

    Using this approach, however, it seems impossible to vary the site icon with theme. I want my site icon to match the color scheme of my theme (and I use 2 different themes). Is it possible?

    • I don’t see any way to do what you want with the Site Icon, as it’s not directly theme-related. In your case, the theme must define the favicon, and it’s not the goal of the Site Icon API.

  • Nico Kaiser

    Anyone else notice that this breaks ssl because of ‘Mixed content’? Unfortunately get_site_icon_url doesn’t take is_ssl into account and delivers alsways http. Because of that chrome marks the connection insecure.

    • Nico Kaiser

      update: this only seems to happen in admin!

  • Can anyone tell me how this new “Site Icon” feature is supposed to work? I get to the point where the file is uploaded and I get a dialog box that offers to crop the image. The problem is 1) my image doesn’t need to be cropped and 2) there’s no “Save” button (or “Done” or anything similar), only a “Crop” button and the upper right corner X to close the dialog. If I click “Crop” I get an error (Error cropping this image, bla bla bla) and if I hit the X it closes. Either way, my image is not saved as a Site Icon (even though it is saved in the media library. This happens in Chrome AND Firefox. I haven’t used WordPress in a couple of years and I’m frustrated with what seems like buggy, poor design and feature bloat.