How To: Customize WordPress Widget Title

Recently, several readers of WPSyntax.com have asked how to customize their WordPress widget titles. The questions we’ll answer today include:

• How can I add an image to my widget title?
• How can I make my widget title two different colors?
• How can I to add link in a widget title?
• Can I make text widget header a link?
• Is there a way to make a widget title clickable?

To answer the questions above, we’ll demonstrate 4 ways to customize your WordPress widget title that range from simple CSS to an advanced method that involves overriding the text widget class in order to make your widget title clickable.

Background Info

By default, WordPress does not allow you to enter HTML into your widget titles. Let me back up to be a little more clear. You can enter HTML into your widget titles, but by default, WordPress will strip out all of your HTML code when you go to save your widget settings.

Take a look at the image below to see four variations of the widget title to give you an idea as to what customizations are possible using the four methods we’re about to cover.

Custom WordPress Widget Title – Method 1

The first customization (shown above) is the easiest of all four methods. By simply using CSS, you can make numerous design tweaks to your widget title.

CSS Code

The CSS code below is what was used on an older website of mine running WordPress and the Genesis Framework. Your specific class name and/or selector might be different.

.widget-area .widget_recent_entries h4 {
    background: url("images/bg-posts.png") no-repeat scroll left 6px transparent;
    padding-left: 40px;
}
.widget-area h4 {
    border-bottom: 4px double #ccc;
    border-top: 4px double #ccc;
    font-size: 24px;
}

Unfortunately, this particular method will not allow you to make a widget title a hyperlink or clickable. You need to skip down to method 4 if you want to learn how to make your widget title clickable.

Custom WordPress Widget Title – Method 2

The technique shown above comes from Brian Gardner’s website. When I asked how he accomplished the customization, he simply said “@rickrduncan It’s simple — just re-registered the primary sidebar adding the span class like so — http://b.rian.cc/RCHQU6.”

For users of the Genesis Framework, simply copy the code below and paste it into your theme’s functions.php file.

Php Code

Place this code into your theme’s functions.php file.

/** Register widget areas */
/** Source: www.wpsyntax.com */
genesis_register_sidebar(array(
	'name'			=> 'Primary Sidebar',
	'id'				=> 'sidebar',
	'description'	=> 'This is the primary sidebar if you are using a two or three column site layout option.',
	'before_title'	=> '<h4 class="widgettitle"><span class="sidebar-title">','after_title'=>'</span></h4>'
));

HTML Code

This is the HTML code generated by WordPress. As you can see in the code below, the Php code that you entered into functions.php will add a <SPAN> tag with the class name “sidebar-title” inside your H4 title tag.

<h4 class="widgettitle">
<span class="sidebar-title">Recent Posts</span>
</h4>

CSS Code

This is the CSS code that will likely need to be customized for your specific implementation.

.widgettitle {
    background: url("images/lines.png") repeat scroll 0 0 transparent;
    text-align: center;
}
.sidebar-title {
    padding: 0 0.5rem;
}

This customization is really easy and quick to implement. Take note however that it encompasses everything (every word in the H4 tag) into the “SPAN” tag.

Some people have asked how to put only the first word into a <SPAN> tag. Well, that’s easy too and it’s our third tutorial on how to customize the WordPress widget title.

Custom WordPress Widget Title – Method 3

As seen in the image above, our third method demonstrates how to wrap the first word of a WordPress widget title into a <SPAN> tag.

To accomplish this customization, you need to add a filter and a custom function into your theme’s functions.php file. This can be used for all users of WordPress and those using the Genesis Framework.

Php Code

Place this code into your theme’s functions.php file.

/** Wrap first word of widget title into a span tag */
/** Source: www.wpsyntax.com */
function child_span_widgets( $old_title ) {
	$title = explode( " ", $old_title, 2 );
	$titleNew = "<span>$title[0]</span> $title[1]";
	return $titleNew;
}
add_filter ( 'widget_title', 'child_span_widgets' );

HTML Code

The HTML code shown below is what’s generated by WordPress.

<h4 class="widgettitle">
<span>Recent</span>
Posts
</h4>

CSS Code

The CSS below that makes the first word Orange and underlines both the entire title and the orange portion.

.widgettitle {
    border-bottom: 1px solid #DDDDDD;
}

.widgettitle span {
    border-bottom: 1px solid #F0591A;
    color: #F0591A;
    display: block;
    float: left;
    margin: 0 5px 0 0;
}

Now go to your widget of choice and simply enter two or more words and the first word will be wrapped in a <SPAN> tag using your style defined in the CSS.

This method gives you a little more control over the styling of your widget title by allowing you to customize the first word. But what about if you want to put any HTML you wanted into the widget title? Keep reading as method #3 does just that!

Custom WordPress Widget Title – Method 3

This is by far the most difficult yet robust method in order to customize your WordPress widget title. Using this technique, you can enter HTML directly into the title of your widget. You can make your text widget header a link which will of course make it clickable.

The image below shows a snippet of HTML code entered directly into the widget title text-box.

WordPress core is using the Php function strip_tags() when saving the widget title into the database. This causes your HTML or any Php code to be stripped away from the widget title.

Since I haven’t been able to locate a filter to use in the functions.php file that would allow us to save HTML into the widget title, the method we’ll use involves overriding the standard text widget plugin. This method is going to be upgrade safe and called from our theme’s functions.php file. We’re only covering the “text widget” for our example but these steps can be duplicated for any other widget you want to override.

Step 1

Fire up your favorite text editor and create a new file named custom_widgets.php.

Inside your WordPress folder, locate and open the file wp-includes/default-widgets.php. Look for the entire class declaration code, starting with:

 class WP_Widget_Text extends WP_Widget { 

and copy the entire class code into the file you created that we named custom_widgets.php.

Next, rename the class, by changing the class declaration to:

 class WP_Widget_Text_Custom extends WP_Widget_Text { 

Step 2

Instruct WordPress to use our custom widget code for text widgets instead of the standard version supplied by WordPress. Copy the code below and paste it into your theme’s functions.php file.

if ( include( 'custom_widgets.php' ) ){
     add_action( "widgets_init", "load_custom_widgets" );
}
function load_custom_widgets() {
    unregister_widget( "WP_Widget_Text" );
    register_widget( "WP_Widget_Text_Custom" );
}

NOTE: The code you copied above needs to be placed into your theme’s functions.php file anywhere after:

require_once( get_template_directory() . '/lib/init.php' );

At this point, if everything is saved as-is nothing new is happening and hopefully nothing is broken. Since we haven’t done anything except to override the standard plugin text widget, everything should still be working without errors and without saving HTML.

Step 3

Now the magic happens! Since we now have our own version of the text widget plugin working we’ll make some tweaks to it in order to allow HTML code be entered and saved into the widget title.

Inside of custom_widgets.php locate the function update( $new_instance, $old_instance ) and find the line of code:

 $instance['title'] = strip_tags($new_instance['title']); 

Replace it with:

if (current_user_can('unfiltered_html')){
     $instance['title'] = $new_instance['title'];
}
else {
     strip_tags($new_instance['title']);
}

The code above first runs a security check to make sure the user is allowed to enter HTML (learn more at codex) and if true will save the content with the HTML intact. Otherwise the data is saved but the HTML is stripped out.

Now locate function form( $instance ) and find the line of code:

 $title = strip_tags($instance['title']); 

and replace it with:

 $title = $instance['title']; 

To make it easier on you, I’ve created a zip file of custom_widgets.php that you can download here.

In closing: While this method is upgrade safe there is always the possibility that a security patch can come out that impacts the file default-widget.php. If this happens, you might be required you to update your custom implementation to take advantage of the security changes. You can keep up with the WordPress changelogs here.