wp_title( string $sep = '»', bool $display = true, string $seplocation = '' )

Display or retrieve page title for all areas of blog.

Contents

Description Description

By default, the page title will display the separator before the page title, so that the blog title will be before the page title. This is not good for title display, since the blog title shows up on most tabs and not what is important, which is the page that the user is looking at.

There are also SEO benefits to having the blog title after or to the ‘right’ of the page title. However, it is mostly common sense to have the blog title to the right with most browsers supporting tabs. You can achieve this by using the seplocation parameter and setting the value to ‘right’. This change was introduced around 2.5.0, in case backward compatibility of themes is important.

Parameters Parameters

$sep

(string) (Optional) default is '»'. How to separate the various items within the page title.

Default value: '»'

$display

(bool) (Optional) Whether to display or retrieve title.

Default value: true

$seplocation

(string) (Optional) Direction to display title, 'right'.

Default value: ''

Top ↑

Return Return

(string|null) String on retrieve, null when displaying.

Top ↑

Source Source

File: wp-includes/general-template.php 

function wp_title( $sep = '»', $display = true, $seplocation = '' ) {
	global $wp_locale;

	$m        = get_query_var( 'm' );
	$year     = get_query_var( 'year' );
	$monthnum = get_query_var( 'monthnum' );
	$day      = get_query_var( 'day' );
	$search   = get_query_var( 's' );
	$title    = '';

	$t_sep = '%WP_TITLE_SEP%'; // Temporary separator, for accurate flipping, if necessary

	// If there is a post
	if ( is_single() || ( is_home() && ! is_front_page() ) || ( is_page() && ! is_front_page() ) ) {
		$title = single_post_title( '', false );
	}

	// If there's a post type archive
	if ( is_post_type_archive() ) {
		$post_type = get_query_var( 'post_type' );
		if ( is_array( $post_type ) ) {
			$post_type = reset( $post_type );
		}
		$post_type_object = get_post_type_object( $post_type );
		if ( ! $post_type_object->has_archive ) {
			$title = post_type_archive_title( '', false );
		}
	}

	// If there's a category or tag
	if ( is_category() || is_tag() ) {
		$title = single_term_title( '', false );
	}

	// If there's a taxonomy
	if ( is_tax() ) {
		$term = get_queried_object();
		if ( $term ) {
			$tax   = get_taxonomy( $term->taxonomy );
			$title = single_term_title( $tax->labels->name . $t_sep, false );
		}
	}

	// If there's an author
	if ( is_author() && ! is_post_type_archive() ) {
		$author = get_queried_object();
		if ( $author ) {
			$title = $author->display_name;
		}
	}

	// Post type archives with has_archive should override terms.
	if ( is_post_type_archive() && $post_type_object->has_archive ) {
		$title = post_type_archive_title( '', false );
	}

	// If there's a month
	if ( is_archive() && ! empty( $m ) ) {
		$my_year  = substr( $m, 0, 4 );
		$my_month = $wp_locale->get_month( substr( $m, 4, 2 ) );
		$my_day   = intval( substr( $m, 6, 2 ) );
		$title    = $my_year . ( $my_month ? $t_sep . $my_month : '' ) . ( $my_day ? $t_sep . $my_day : '' );
	}

	// If there's a year
	if ( is_archive() && ! empty( $year ) ) {
		$title = $year;
		if ( ! empty( $monthnum ) ) {
			$title .= $t_sep . $wp_locale->get_month( $monthnum );
		}
		if ( ! empty( $day ) ) {
			$title .= $t_sep . zeroise( $day, 2 );
		}
	}

	// If it's a search
	if ( is_search() ) {
		/* translators: 1: separator, 2: search phrase */
		$title = sprintf( __( 'Search Results %1$s %2$s' ), $t_sep, strip_tags( $search ) );
	}

	// If it's a 404 page
	if ( is_404() ) {
		$title = __( 'Page not found' );
	}

	$prefix = '';
	if ( ! empty( $title ) ) {
		$prefix = " $sep ";
	}

	/**
	 * Filters the parts of the page title.
	 *
	 * @since 4.0.0
	 *
	 * @param array $title_array Parts of the page title.
	 */
	$title_array = apply_filters( 'wp_title_parts', explode( $t_sep, $title ) );

	// Determines position of the separator and direction of the breadcrumb
	if ( 'right' == $seplocation ) { // sep on right, so reverse the order
		$title_array = array_reverse( $title_array );
		$title       = implode( " $sep ", $title_array ) . $prefix;
	} else {
		$title = $prefix . implode( " $sep ", $title_array );
	}

	/**
	 * Filters the text of the page title.
	 *
	 * @since 2.0.0
	 *
	 * @param string $title Page title.
	 * @param string $sep Title separator.
	 * @param string $seplocation Location of the separator (left or right).
	 */
	$title = apply_filters( 'wp_title', $title, $sep, $seplocation );

	// Send it out
	if ( $display ) {
		echo $title;
	} else {
		return $title;
	}
}

Expand full source code Collapse full source code View on Trac

Top ↑

Changelog Changelog

Changelog
Version Description
1.0.0 Introduced.

Top ↑

More Information More Information

Top ↑

Best practices Best practices

Plugins might use the wp_title filter to generate a value. While it is possible to construct a “title” by doing things such as concatenating with bloginfo (the Site Name), if you do not use the wp_title function in your theme, you will likely have errors or unexpected behavior.

Top ↑

Return Values Return Values

The function returns a concatenated string. It always queries the database for a default string; the value of the default string depends on the type of post or page:

Single post
the title of the post
Date-based archive 
the date (e.g., “2006”, “2006 – January”)
Category
the name of the category
Author page 
the public name of the user

The function then prepends or appends the sep string and returns the entire value.

Top ↑

Top ↑

Uses Uses

Uses
Uses Description
wp-includes/general-template.php: wp_title_parts

Filters the parts of the page title.
wp-includes/l10n.php: __()

Retrieve the translation of $text.
wp-includes/formatting.php: zeroise()

Add leading zeros when necessary.
wp-includes/general-template.php: single_post_title()

Display or retrieve page title for post.
wp-includes/general-template.php: post_type_archive_title()

Display or retrieve title for a post type archive.
wp-includes/general-template.php: single_term_title()

Display or retrieve page title for taxonomy term archive.
wp-includes/general-template.php: wp_title

Filters the text of the page title.
wp-includes/query.php: is_single()

Determines whether the query is for an existing single post.
wp-includes/query.php: is_search()

Determines whether the query is for a search.
wp-includes/query.php: is_404()

Determines whether the query has resulted in a 404 (returns no results).
wp-includes/query.php: is_home()

Determines whether the query is for the blog homepage.
wp-includes/query.php: is_front_page()

Determines whether the query is for the front page of the site.
wp-includes/query.php: is_page()

Determines whether the query is for an existing single page.
wp-includes/query.php: is_category()

Determines whether the query is for an existing category archive page.
wp-includes/query.php: is_tag()

Determines whether the query is for an existing tag archive page.
wp-includes/query.php: is_tax()

Determines whether the query is for an existing custom taxonomy archive page.
wp-includes/query.php: is_author()

Determines whether the query is for an existing author archive page.
wp-includes/query.php: get_query_var()

Retrieve variable in the WP_Query class.
wp-includes/query.php: is_post_type_archive()

Determines whether the query is for an existing post type archive page.
wp-includes/query.php: get_queried_object()

Retrieve the currently-queried object.
wp-includes/query.php: is_archive()

Determines whether the query is for an existing archive page.
wp-includes/class-wp-locale.php: WP_Locale::get_month()

Retrieve the full translated month by month number.
wp-includes/taxonomy.php: get_taxonomy()

Retrieves the taxonomy object of $taxonomy.
wp-includes/plugin.php: apply_filters()

Call the functions added to a filter hook.
wp-includes/post.php: get_post_type_object()

Retrieves a post type object by name.
Show 20 more uses Hide more uses

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 11You must log in to vote on the helpfulness of this note
    Contributed by Dave Clements —

    wp_title() was originally to be deprecated in 4.4, but was reinstated while efforts were made to identify the unintended ways in which the function was being used to ensure that the deprecation wouldn’t break them. With the likelihood that wp_title() will be deprecated in the near future, it is recommended that you instead use its replacement: the title-tag theme feature.

  2. Skip to note 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 7You must log in to vote on the helpfulness of this note
    Contributed by Fahid Javid —

    Following is the recommended way instead of wp_title() function.

    /*
 * Let WordPress manage the document title.
 * By adding theme support, we declare that this theme does not use a
 * hard-coded <title> tag in the document head, and expect WordPress to
 * provide it for us.
 */
add_theme_support( 'title-tag' );;

    It should be placed in the functions.php file with after_setup_theme action hook.

  3. Skip to note 3 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 4You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Zero-character sep
    The sep string may be zero characters, which will remove » from the returned value. To do this, set the sep parameter to zero characters, for example:

    <title><?php wp_title(''); ?></title>

    If the title of the post is “Hello world!”, then the function will return:

    Hello world!

  4. Skip to note 4 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Customizing with the filter
    If you want to change the way that the title displays on different pages you can use a filter.

    /**
 * Filters wp_title to print a neat <title> tag based on what is being viewed.
 *
 * @param string $title Default title text for current view.
 * @param string $sep   Optional separator.
 * @return string The filtered title.
 */
function wpdocs_theme_name_wp_title( $title, $sep ) {
	if ( is_feed() ) {
		return $title;
	}
	
	global $page, $paged;

	// Add the blog name
	$title .= get_bloginfo( 'name', 'display' );

	// Add the blog description for the home/front page.
	$site_description = get_bloginfo( 'description', 'display' );
	if ( $site_description && ( is_home() || is_front_page() ) ) {
		$title .= " $sep $site_description";
	}

	// Add a page number if necessary:
	if ( ( $paged >= 2 || $page >= 2 ) && ! is_404() ) {
		$title .= " $sep " . sprintf( __( 'Page %s', '_s' ), max( $paged, $page ) );
	}
	return $title;
}
add_filter( 'wp_title', 'wpdocs_theme_name_wp_title', 10, 2 );

    Expand full source codeCollapse full source code

  6. Skip to note 6 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Covering Homepage
    If you are using a custom homepage with custom loops and stuff or a custom front-page, you will have an empty wp_title. Here goes a neat hack to add the description/tagline at the wp_title place on homepage:

    <title><?php wp_title(''); ?></title>

    Then in your functions.php file in your theme:

    add_filter( 'wp_title', 'wpdocs_hack_wp_title_for_home' );

/**
 * Customize the title for the home page, if one is not set.
 *
 * @param string $title The original title.
 * @return string The title to use.
 */
function wpdocs_hack_wp_title_for_home( $title )
{
  if ( empty( $title ) && ( is_home() || is_front_page() ) ) {
    $title = __( 'Home', 'textdomain' ) . ' | ' . get_bloginfo( 'description' );
  }
  return $title;
}

    Expand full source codeCollapse full source code

    You can format this string as you want of course.

  7. Skip to note 7 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by johnmichaelgrey —

    Just wanted to check line 833 for mis-spelling:

    $t_sep = ‘%WP_TITILE_SEP%’; // Temporary separator, for accurate flipping, if necessary

    Is WP_TITILE_SEP spelled correctly? I might have thought it to be WP_TITLE_SEP

    I noticed this in my WP php file, and then again here.

You must log in before being able to contribute a note or feedback.