How does the ‘Display Site Title and Tagline’ control in Theme Customizer work – WordPress

You might have seen the ‘Display Site Title and Tagline’ control in the Theme Customizer. It looks something like this-

This function toggles the visibility of the Site Title and tagline. Earlier, it used to happen using the refresh of the preview window but later on, jQuery has been used to toggle the visibility of the Title and Tagline using the control. But what really goes on behind the scenes. This is a completely unique control as unlike other controls, it affects the value of another control. Let’s take a look at it. For the sake of convenience, I will be referring the ‘Display Site Title and Tagline’ control as the DST control.
In WordPress, the state of DST control can be accessed using the function display_header_text(). Unlike other controls, the value of this control can’t be accessed directly using get_theme_mod(). This makes it convenient to use in a PHP environment but on the other hand, if you wish to try your hands in the JS API, its value can’t be accessed directly using wp.customize resulting in a severe headache if you are not familiar with the working of this control.
The DST control toggles the state of the header_textcolor setting. If DST is enabled, the header_textcolor returns whatever value is stored in it from the Color Palette and when it is disabled, the header_textcolor setting returns the value ‘blank’. Literally, the string 'blank' is stored in the setting. Take a look at the display_header_text() function –

[php]function display_header_text() {
if ( ! current_theme_supports( ‘custom-header’, ‘header-text’ ) )
return false;</code>

$text_color = get_theme_mod( ‘header_textcolor’, get_theme_support( ‘custom-header’, ‘default-text-color’ ) );
return ‘blank’ !== $text_color;

It is clear as to what is happening with the DST control. If the theme does not support the custom header, it will return false. In the end, function checks the condition 'blank' !== $text_color and returns a boolean value accordingly.
Take a note of the ‘blank’ value that is stored in header_textcolor setting whenever DST is disabled. This value is used to toggle the site title and tagline as evident in custom-header.php file.
Now, in PHP, it is relatively to check the value of the DST control using a simple function display_header_text() but in JS API, where everything depends on the accessing the values of settings and controls, we have to check for the ‘blank’ value which is stored in header_textcolor.
In twenty seventeen theme, the following jQuery code has been used to toggle the Site Title and tagline visibility-
wp.customize( ‘header_textcolor’, function( value ) {
value.bind( function( to ) {
if ( ‘blank’ === to ) {
$( ‘.site-title, .site-description’ ).css({
clip: ‘rect(1px, 1px, 1px, 1px)’,
position: ‘absolute’
// Add class for different logo styles if title and description are hidden.
$( ‘body’ ).addClass( ‘title-tagline-hidden’ );
} else {

// Check if the text color has been removed and use default colors in theme stylesheet.
if ( ! to.length ) {
$( ‘#twentyseventeen-custom-header-styles’ ).remove();
$( ‘.site-title, .site-description’ ).css({
clip: ‘auto’,
position: ‘relative’
$( ‘.site-branding, .site-branding a, .site-description, .site-description a’ ).css({
color: to
// Add class for different logo styles if title and description are visible.
$( ‘body’ ).removeClass( ‘title-tagline-hidden’ );

Without going into much detail, I will only say that the string ‘blank’ is checked against the value stored in header_textcolor setting and used to toggle the visibility of the Title and Tagline depending on the value stored in it.

Hope I was able to explain the inner functioning of the DST control as it can be hard for a beginner to grasp initially.

Leave a comment

Your email address will not be published. Required fields are marked *