Changing Page Titles with the wp_title Filter

Ever needed to update your WordPress page titles dynamically? Have you, a plugin developer, ever wanted to add something to each page title? Does your theme need to customize the way page titles look for SEO purposes? If your WordPress version is 4.3 or before: it’s time to talk about wp_title() and the wp_title filter.

The wp_title Filter

wp_title() Is a function called in most older themes to get the title for each page. That function calls the wp_title filter and returns its output.

So: in most older themes you can harness the wp_title filter to manipulate the page title!

All you need to do is listen for the filter and return your title in the callback.

// functions.php or in a plugin file
add_filter('wp_title', 'ijae_wp_title', 10, 2);

function ijae_wp_title($title, $separator, $sepLocation) {
    return "Hello World!"; // all page titles will say "Hello World!"
}

And that’s really all there is to the wp_title filter!

What If the wp_title Filter Isn’t Working?

Check your theme files for a call to wp_title(). If you can’t find it: it’s possible your WordPress version is 4.4 or newer, or your theme doesn’t support changing page titles with the wp_title filter.

If your WordPress version is 4.4 or newer: you can try using the pre_get_document_title filter and its counterparts: document_title_separator and document_title_parts.

pre_get_document_title works almost exactly like wp_title used to.

pre_get_document_title filters the page title before it gets fully generated. Anything returned to this filter will be used as the page title.

add_filter('pre_get_document_title', 'ijae_pre_get_document_title', 10, 1);
function ijae_pre_get_document_title($title) {
    return "Hello World!"; // every page title is now "Hello World!"
}

If you’d like to exercise a little more control, use document_title_separator, which controls the separator like this:

add_filter('document_title_separator', 'ijae_document_title_separator', 10, 1);
function ijae_document_title_separator($separator) {
    return " -><- "; // defaults to "-"
}

Or use the document_title_parts filter which returns all parts of the title in an array:

add_filter('document_title_parts', 'ijae_document_title_parts', 10, 1);
function ijae_document_title_parts( $titleParts ) {
    /*
     $titleParts (array) The document title parts.
        'title'
            (string) Title of the viewed page.
        'page'
            (string) Optional. Page number if paginated.
        'tagline'
            (string) Optional. Site description when on home page.
        'site'
            (string) Optional. Site title when not on home page.
     */
    return [
        'title'     =>  'Hello McWorldy',
        'page'      =>  123,
        'tagline'   =>  'The Hello Worldy Place',
        'site'      =>  'The Hello Worldy Site',
    ];
}

Conclusion

There you have it: you can now update your titles dynamically in any version of WordPress.

Before WordPress 4.4 came out: you could almost always use the wp_title filter to get the job done.

With 4.4 came a new way to modify page titles and many themes have adopted it and made the switch.

If you need help creating WordPress plugins, check out my primer on developing plugins for WordPress. It has everything you’ll need to get going on your first plugin.

Leave a Reply

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