WordPress
Article

How to Use the WordPress Custom Logo API

By Jérémy Heleine

WordPress users who aren’t necessarily developers can’t always customize their website the way they want. They can choose a theme from thousands that are available (both free and paid), but there’s often frustration that they can’t easily change the logo. Some themes provide options allowing their users to change the logo but it’s not always the case.

To allow all users to change the logo of their website easily, the WordPress team decided to add a new feature in WordPress 4.5: Custom Logo. Using this feature, any WordPress user will now be able to change their logo via the Theme Customizer.

If you’re a developer, you’ll want to know how to make use of the Custom Logo feature in your theme. The good news is that it’s not complicated, so you won’t have any excuse to not allow your user to customize their logo! In this article, we’ll look at how a user can change their logo with the Custom Logo feature. Then, we’ll cover how developers can enable the Custom Logo feature using the Custom Logo API.

From a user’s perspective, when the Custom Logo feature is enabled, changing the logo of a website is pretty easy. That was the aim of the feature after all.

The first thing to do is open the Theme Customizer. To do that, you can use the ‘Customize’ entry in the ‘Appearance’ menu in the WordPress dashboard. If you can’t see that entry, that means you don’t have the admin rights to the site to customize the theme (or you are using a very old version of WordPress and you should update it as soon as possible!). You can also access the Customizer thanks to the ‘Customize’ link in the admin top bar on any page of your website.

WordPress Theme Customizer

In the Customizer, go to the ‘Site Identity’ panel and you’ll find the ‘Logo’ section. If it’s the first time you’ve changed the logo, you’ll find a ‘Select logo’ button allowing you to select the logo you want to display on your website.

Hitting this button will open a media window. You can choose any existing image or you can upload a new one. Submit your choice with the ‘Choose logo’ button in the bottom right corner.

Once a logo is chosen, the ‘Logo’ section displays it, above two buttons: one to remove the custom logo, and another to change it.

WordPress Custom Logo API

The advantage of using the Theme Customizer is that you directly see the changes. In fact, right after choosing your logo you’ll see it on your website. You’re the only one who can see these changes, until you save them with the ‘Save & Publish’ button at the top of the Customizer.

Using the Custom Logo API

You can test this feature with WordPress’ default themes, because they allow the use of Custom Logo. If you use another theme, you need this theme to explicitly enable the Custom Logo feature. We’ll now highlight how this can be achieved.

Enabling the Custom Logo Feature

To enable the Custom Logo feature, we actually need to declare support for it. There’s a good reason why this feature is not enabled by default. As we’ll see below, we have to use a specific function to display the Custom Logo. If we don’t use this function, the Custom Logo is not displayed, so it’s useless changing it.

To declare support for the Custom Logo feature we use the add_theme_support() function. The best way to do this is by using a callback function and the after_setup_theme action. Put the following code in the functions.php file of your theme to declare the support for the Custom Logo feature.

function mytheme_setup() {
    add_theme_support('custom-logo');
}

add_action('after_setup_theme', 'mytheme_setup');

Now your users will be able to select a logo. The problem is that it’s not displayed yet. Before we look at how we display the custom logo, I’ll now walk through another useful parameter.

A logo is part of the identity of a website. However, that doesn’t mean that as the theme’s developer, you can’t choose its size. I think it can be fairly important to do this, as a logo that is too big can break the entire theme design, which isn’t what we want.

If you want to control the size of the Custom Logo, you first need to declare the size with add_image_size() which accepts three parameters: the name you want for this size, the width and the height. Then you indicate this size (with the name you chose) as a parameter in the Custom Logo support declaration.

add_image_size('mytheme-logo', 160, 90);
add_theme_support('custom-logo', array(
    'size' => 'mytheme-logo'
));

If the user chooses a smaller logo, then the logo won’t be resized. However, if an image’s dimensions are bigger than what is specified, whether that’s in height and/or width, then then it will be resized. In all cases, WordPress will preserve the original ratio when the image is resized.

So, the Custom Logo won’t be taller or wider than the area provided, but it can be smaller.

If you declare support for the Custom Logo feature, you’ll need to display the user’s selection. To do so, you can use the function the_custom_logo() anywhere you want to see the logo. It will automatically echo the right HTML code to display the logo: an image in the right size, encapsulated into a link redirecting to the homepage.

If, for any reason you want to retrieve this code instead of just echoing it, you can also use get_custom_logo(). Note that, under the hood, the_custom_logo() calls get_custom_logo() to display the user’s logo.

Finally, a third function can help you in your theme: has_custom_logo(). As its name suggests, this function returns a boolean: true if a Custom Logo has been set, false otherwise.

In the following code we display the Custom Logo, if any. We detect the existence of a Custom Logo with has_custom_logo() and, if there’s no logo to show, we only display the site’s name.

<?php
// Display the Custom Logo
the_custom_logo();

// No Custom Logo, just display the site's name
if (!has_custom_logo()) {
    ?>
    <h1><?php bloginfo('name'); ?></h1>
    <?php
}
?>

Note that we don’t use has_custom_logo() before using the_custom_logo(). In fact, if there’s no logo to show, then the_custom_logo() will display an empty string so it’s useless to check the existence of a logo.

Below is another way to do the same thing. We define a function (in the functions.php file for instance) that displays the Custom Logo or only the site’s name. This time, we use function_exists() to ensure our theme remains compatible with older versions of WordPress.

function mytheme_custom_logo() {
    // Try to retrieve the Custom Logo
    $output = '';
    if (function_exists('get_custom_logo'))
        $output = get_custom_logo();

    // Nothing in the output: Custom Logo is not supported, or there is no selected logo
    // In both cases we display the site's name
    if (empty($output))
        $output = '<h1><a href="' . esc_url(home_url('/')) . '">' . get_bloginfo('name') . '</a></h1>';

    echo $output;
}

Then we can call this function anywhere we want, for example in the header.

In Summary

As new versions of WordPress are released, the Theme Customizer becomes more and more useful for end users. Users can now personalize their website without needing to change the code of the theme.

Thanks to the new Custom Logo API, and the Site Icon API we covered in a previous article, the end user can now more easily control the identity of their website, without needing custom development.

  • https://Designworksnw.com/ Rick Cano

    Great article Jeremy, the only item I would add for the regular user is the use of Child Themes with a functions.php file in the child theme director. :)

  • http://exclusive-paper.com JanySmool

    Hello, it is very interesting artical! Can I do it with other platforn!? Also, I think it is very important to use interesting and creative content! How do you think?

  • Ian Mostar

    Great feature WordPress. Clients would be very happy. thanks!

  • Roger Kondrat

    My primary concern is if the logo differs from desktop to a mobile phone. I have a client who has a logo above and text below, but we need the logo on the left and text (company name) on the right. So how would this work with this new API?

    • http://tassedecafe.org Jérémy Heleine

      The simplest solution I think about right now is using a real text to display the company name, so that you’ll be able to place it anywhere you want thanks to a bit of CSS. If the company name is in the image, maybe there’s something to do with responsive images, but I must admit that it’s not a question I thought about before.

      • Roger Kondrat

        Thanks Jeremy I really appreciate your follow up comment. I think I’ll stick with the traditional alternatives then; at least until I can guarantee it’ll work as a CSS designer would expect under the different viewpoints.

        Thanks for the great post!

  • Yajuvendra Pratap Singh

    How to add also this logo upload option in my custom theme options that are managed by both sides

Recommended

Learn Coding Online
Learn Web Development

Start learning web development and design for free with SitePoint Premium!

Instant Website Review

Use Woorank to analyze and optimize your website to improve your website to improve your ranking!

Run a review to see how your site can improve across 70+ metrics!

Get the latest in WordPress, once a week, for free.