Themes: changes related to get_custom_logo() in WordPress 5.5

Unlinking the custom logo on the homepage

Logo images inserted using get_custom_logo() or the_custom_logo() will no longer link to the homepage when visitors are on that page. In an effort to maintain the styling given to the linked image, the unlinked logo image is inside a span tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.) with the same “custom-logo-link” class.

Many themes include both a logo and a site title, and then the logo is decoration alongside the site title. Because decorative images do not need their purpose to be described, the unlinked logo’s alt attribute is empty. In cases where the site title is not present, the logo alt text may require custom handling. See code examples below for ways to override the default behavior.

Theme authors who use the a tag as a CSSCSS Cascading Style Sheets. selector instead of the .custom-logo-link class are encouraged to duplicate their selector to also select the span tag, or to directly select the .custom-logo-link class. A theme directory search found 183 themes that use a.custom-logo-link for styling.

Please verify whether this change makes the logo display any differently on the homepage, as well as whether the empty alt text should be appropriate.

For more details, see the related ticketticket Created for both bug reports and feature development on the bug tracker. on TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress.: #37011

New logo image attributes filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output.

Themes can use the get_custom_logo_image_attributes filter to override default attributes for the logo image or to set additional attributes.

For example, if a theme combines the logo image plus the site title (as actual text) within a link and/or heading tag, then having the site title as the logo’s alt text would be redundant. In that case, this is one way to empty the alt text so screen readers only announce the actual text:

add_filter( 'get_custom_logo_image_attributes', 'my_logo_remove_alt_text', 10, 1 );
function my_logo_remove_alt_text( $custom_logo_attr ) {
	$custom_logo_attr["alt"] = "";
	return $custom_logo_attr;
}

To check whether a user has customized the alt text before emptying it, the filter could be similar to this:

add_filter( 'get_custom_logo_image_attributes', 'my_logo_alt_custom_or_empty', 10, 2 );
function my_logo_alt_custom_or_empty( $custom_logo_attr, $custom_logo_id ) {
	$logo_alt = get_post_meta( $custom_logo_id, '_wp_attachment_image_alt', true );
	if ( empty( $logo_alt ) ) {
		$custom_logo_attr["alt"] = "";
	}
	return $custom_logo_attr;
}

If a user has customized the alt text value, this can restore it on the homepage:

add_filter( 'get_custom_logo_image_attributes', 'my_logo_homepage_maybe_alt', 10, 2 );
function my_logo_homepage_maybe_alt( $custom_logo_attr, $custom_logo_id ) {
	$logo_alt = get_post_meta( $custom_logo_id, '_wp_attachment_image_alt', true );
	if ( ! empty ( $logo_alt ) && is_front_page() ) {
		$custom_logo_attr["alt"] = $logo_alt;
	}
	return $custom_logo_attr;
}

If the site title is appropriate as a fallback on the homepage in a certain theme, a filter like this could be used:

add_filter( 'get_custom_logo_image_attributes', 'my_logo_homepage_restore_alt', 10, 2 );
function my_logo_homepage_restore_alt( $custom_logo_attr, $custom_logo_id ) {
	$logo_alt = get_post_meta( $custom_logo_id, '_wp_attachment_image_alt', true );
	if ( is_front_page() ) {
		if ( ! empty ( $logo_alt ) ) {
			$custom_logo_attr["alt"] = $logo_alt;
		} else {
			$custom_logo_attr["alt"] = get_bloginfo( 'name', 'display' );
		}
	}
	return $custom_logo_attr;
}

For more details, see the related ticket on Trac: #36640


Props: @joedolson for adding to the explanation and for review; also @audrasjb, @desrosj, @williampatton, and @poena for review

#5-5, #dev-notes