Custom Logo

New in 4.5 is the ability for users to add a logo to their sites (if their theme has declared support for it). It’s an addition to the Custom Header and Custom Background features which themes have to declare support for as well, and works pretty much just like them.

To register support, a theme would add the following call in a callback to the after_setup_theme action:

function theme_prefix_setup() {
	add_theme_support( 'custom-logo' );
}
add_action( 'after_setup_theme', 'theme_prefix_setup' );

Theme support for custom logos accepts five parameters, added in an arguments array:

  • height
    (int) Expected logo height in pixels.
    Themes can use built-in image sizes (like thumbnail) or register a custom image size and use that.

  • width
    (int) Expected logo width in pixels.

  • flex-height
    (boolean) Whether to allow for a flexible height.
    Showing the logo in a vertical sidebar (like Twenty Fifteen) is a good example for when a flexible height can make sense.

  • flex-width
    (boolean) Whether to allow for a flexible width.
    If a theme has room horizontally, flex-width gives users more freedom in how their logo can be displayed. Example:

    add_theme_support( 'custom-logo', array(
       'height'      => 175,
       'width'       => 400,
       'flex-width' => true,
    ) );
    
  • header-text
    (array) Class name(s) of elements to hide.
    This parameter is only important for (the very few) themes that do not also support hiding the header text in custom headers. Themes can pass an array of class names here for all elements constituting header text that could be replaced by a logo.

    add_theme_support( 'custom-logo', array(
       'header-text' => array( 'site-title', 'site-description' ),
    ) );
    

Not only will this enable the Customizer control to add a custom logo, it will also add a body class of wp-custom-logo that can be used to style the logo if present. Important: When adding support in your theme, please make sure to test setting a new logo in the customizer with your theme active and in Live Preview. You also want to make sure that the theme has styles in place to accommodate logos that don’t have your custom image size (if you chose to add one), like images that have been uploaded before your theme was activated or updated, since they default to the full size.

To manage displaying a custom logo in the front-end, these three template tags can be used:

  • get_custom_logo( $blog_id = 0 )
    Returns markup for a custom logo.
  • the_custom_logo( $blog_id = 0 )
    Displays markup for a custom logo.
  • has_custom_logo( $blog_id = 0 )
    Returns a boolean true/false, whether a custom logo is set or not.

To be able to use the new template tags and maintain backwards compatibility with older versions of WordPress it is recommended to wrap these functions in a function_exists() call, similar to how Twenty Sixteen does it:

function twentysixteen_the_custom_logo() {
   if ( function_exists( 'the_custom_logo' ) ) {
      the_custom_logo();
   }
}

The latest two default themes will be updated with support for this brand new feature as soon as WordPress 4.5 ships. Themes that have been using Jetpack’s Site Logo implementation will not need to be updated—Jetpack will do a migration behind the scenes to work with it out of the box.

A small under the hood goodie: Custom logos utilizes the Customizer’s brand new Selective Refresh feature, allowing for super fast changes without having to reload the entire preview. It also let’s users shift-click the logo in the preview to open the corresponding customizer section.

Alert: [EDIT]: As of [37077], Custom Logo does not support the size argument anymore. Specifying the logo size in individual arguments has the advantage of only creating a special image file for the specific logo used (and not every image uploaded), and providing more parity with how Custom Header works.