Conditional Tags

Conditional Tags can be used in your Template Files to alter the display of content depending on the conditions that the current page matches. They tell WordPress what code to display under specific conditions. Conditional Tags usually work with PHP if /else Conditional Statements.

The code begins by checking to see if a statement is true or false. If the statement is found to be true, the first set of code is executed. If it’s false, the first set of code is skipped, and the second set of code (after the else) is executed instead.

For example, you could ask if a user is logged in, and then provide a different greeting depending on the result.

    if ( is_user_logged_in() ):
        echo 'Welcome, registered user!';
    else:
        echo 'Welcome, visitor!';
    endif;

Note the close relation these tags have to WordPress Template Hierarchy. [to be added, or removed?]

Where to Use Conditional Tags Where to Use Conditional Tags

For a Conditional Tag to modify your data, the information must already have been retrieved from your database, i.e. the query must have already run. If you use a Conditional Tag before there is data, there’ll be nothing to ask the if/else statement about.

It’s important to note that WordPress loads functions.php before the query is run, so if you simply include a Conditional Tag in that file, it won’t work.

Two ways to implement Conditional Tags:

  • place it in a Template File
  • create a function out of it in functions.php that hooks into an action/filter that triggers at a later point

Top ↑

The Conditions For The Conditions For

Listed below are the conditions under which each of the following conditional statements proves to be true. Tags which can accept parameters are noted.

The Main Page The Main Page

is_home()

This condition returns true when the main blog page is being displayed, usually in standard reverse chronological order. If your home page has been set to a Static Page instead, then this will only prove true on the page which you set as the “Posts page” in Settings > Reading.

Top ↑

The Front Page The Front Page

is_front_page()

This condition returns true when the front page of the site is displayed, regardless of whether it is set to show posts or a static page.

Returns true when:

  1. the main blog page is being displayed and
  2. the Settings > Reading -> Front page displays option is set to Your latest posts

OR

  1. when Settings > Reading -> Front page displays is set to A static page and
  2. the Front Page value is the current Page being displayed.

Top ↑

The Administration Panels The Administration Panels

is_admin()

This condition returns true when the Dashboard or the administration panels are being displayed.

Top ↑

A Single Post Page A Single Post Page

is_single()

Returns true when any single Post (or attachment, or custom Post Type) is being displayed. This condition returns false if you are on a page.

is_single( ’17’ )

is_single() can also check for certain posts by ID and other parameters. The above example proves true when Post 17 is being displayed as a single Post.

is_single( ‘Irish Stew’ )

Parameters include Post titles, as well. In this case, it proves true when the Post with title “Irish Stew” is being displayed as a single Post.

is_single( ‘beef-stew’ )

Proves true when the Post with Post Slug “beef-stew” is being displayed as a single Post.

is_single( array( 17, ‘beef-stew’, ‘Irish Stew’ ) )

Returns true when the single post being displayed is either post ID 17, or the post_name is “beef-stew”, or the post_title is “Irish Stew”.

is_single( array( 17, 19, 1, 11 ) )

Returns true when the single post being displayed is either post ID = 17, post ID = 19, post ID = 1 or post ID = 11.

is_single( array( ‘beef-stew’, ‘pea-soup’, ‘chilli’ ) )

Returns true when the single post being displayed is either the post_name “beef-stew”, post_name “pea-soup” or post_name “chilli”.

is_single( array( ‘Beef Stew’, ‘Pea Soup’, ‘Chilli’ ) )

Returns true when the single post being displayed is either the post_title is “Beef Stew”, post_title is “Pea Soup” or post_title is “Chilli”.

Note: This function does not distinguish between the post ID, post title, or post name. A post named “17” would be displayed if a post ID of 17 was requested. Presumably the same holds for a post with the slug “17”.

Top ↑

A Single Post, Page, or Attachment A Single Post, Page, or Attachment

is_singular()

Returns true for any is_single, is_page, and is_attachment. It does allow testing for post types.

Top ↑

A Sticky Post A Sticky Post

is_sticky()

Returns true if the “Stick this post to the front page” check box has been checked for the current post. In this example, no post ID argument is given, so the post ID for the Loop post is used.

is_sticky( ’17’ )
Returns true when Post 17 is considered a sticky post.

Top ↑

A Post Type A Post Type

get_post_type()

You can test to see if the current post is of a certain type by including get_post_type() in your conditional. It’s not really a conditional tag, but it returns the registered post type of the current post.

if ( ‘book’ == get_post_type() ) …

post_type_exists()

Returns true if a given post type is a registered post type. This does not test if a post is a certain post_type. Note: This function replaces a function called is_post_type which existed briefly in 3.0 development.

Top ↑

A Post Type is Hierarchical A Post Type is Hierarchical

is_post_type_hierarchical( $post_type )

Returns true if this $post_type has been set with hierarchical support when registered.

is_post_type_hierarchical( ‘book’ )

Returns true if the book post type was registered as having support for hierarchical.

Top ↑

 A Post Type Archive  A Post Type Archive

is_post_type_archive()

Returns true on any post type archive.

is_post_type_archive( $post_type )

Returns true if on a post type archive page that matches $post_type (can be a single post type or an array of post types).

To turn on post type archives, use ‘has_archive’ => true, when registering the post type.

Top ↑

A Comments Popup A Comments Popup

is_comments_popup()

When in Comments Popup window.

Top ↑

Any Page Containing Posts Any Page Containing Posts

comments_open()

When comments are allowed for the current Post being processed in the WordPress Loop.

pings_open()

When pings are allowed for the current Post being processed in the WordPress Loop.

Top ↑

A “PAGE” Page A “PAGE” Page

This section refers to WordPress Pages, not any generic webpage from your blog, or in other words to the built in post_type ‘page’.

is_page()

When any Page is being displayed.

is_page( ’42’ )

When Page 42 (ID) is being displayed.

is_page( ‘About Me And Joe’ )

When the Page with a post_title of “About Me And Joe” is being displayed.

is_page( ‘about-me’ )

When the Page with a post_name (slug) of “about-me” is being displayed.

is_page( array( 42, ‘about-me’, ‘About Me And Joe’ ) )

Returns true when the Pages displayed is either post ID = 42, or post_name is “about-me”, or post_title is “About Me And Joe”.

is_page( array( 42, 54, 6 ) )

Returns true when the Pages displayed is either post ID = 42, or post ID = 54, or post ID = 6.

Testing for Paginated Pages Testing for Paginated Pages

You can use this code to check whether you’re on the nth page in a Post or Page that has been divided into pages using the <!--nextpage-->
QuickTag. This can be useful, for example, if you wish to display meta-data only on the first page of a post divided into several pages.

Example 1
<?php
  $paged = $wp_query->get( 'page' );
  if ( ! $paged || $paged < 2 ) {
    // This is not a paginated page (or it's simply the first page of a paginated page/post)    } else {
    // This is a paginated page.
} ?>
Example 2
<?php $paged = get_query_var( 'page' ) ? get_query_var( 'page' ) : false;
    if ( $paged == false )  {
    // This is not a paginated page (or it's simply the first page of a paginated page/post) }  else  {
    // This is a paginated page.
    }
?>

Top ↑

Testing for Sub-Pages Testing for Sub-Pages

There is no is_subpage() function, but you can test this with a little code:

Snippet 1

<?php  global $post; // if outside the loop
   if ( is_page() && $post->post_parent ) {
    // This is a subpage
          } else {
    // This is not a subpage
    }
?>

You can create your own is_subpage() function using the code in Snippet 2. Add it to your functions.php file. It tests for a parent page in the same way as Snippet 1, but will return the ID of the page parent if there is one, or false if there isn’t.

Snippet 2

function is_subpage() {
    global $post;                              // load details about this page

    if ( is_page() && $post->post_parent ) {   // test to see if the page has a parent
        return $post->post_parent;             // return the ID of the parent post

    } else {                                   // there is no parent so ...
        return false;                          // ... the answer to the question is false
    }
}

It is advisable to use a function like that in Snippet 2, rather than using the simple test like Snippet 1, if you plan to test for sub-pages frequently.

To test if the parent of a page is a specific page, for instance “About” (page id pid 2 by default), we can use the tests in Snippet 3. These tests check to see if we are looking at the page in question, as well as if we are looking at any child pages. This is useful for setting variables specific to different sections of a web site, so a different banner image, or a different heading.

Snippet 3

<?php if ( is_page( 'about' ) || '2' == $post->post_parent ) {
    // the page is "About", or the parent of the page is "About"
    $bannerimg = 'about.jpg';
} elseif ( is_page( 'learning' ) || '56' == $post->post_parent ) {
    $bannerimg = 'teaching.jpg';
} elseif ( is_page( 'admissions' ) || '15' == $post->post_parent ) {
    $bannerimg = 'admissions.jpg';
} else {
    $bannerimg = 'home.jpg'; // just in case we are at an unclassified page, perhaps the home page
}
?>

Snippet 4 is a function that allows you to carry out the tests above more easily. This function will return true if we are looking at the page in question (so “About”) or one of its sub pages (so a page with a parent with ID “2”).

Snippet 4

function is_tree( $pid ) {      // $pid = The ID of the page we're looking for pages underneath
    global $post;               // load details about this page

    if ( is_page($pid) )
        return true;            // we're at the page or at a sub page

    $anc = get_post_ancestors( $post->ID );
    foreach ( $anc as $ancestor ) {
        if( is_page() && $ancestor == $pid ) {
            return true;
        }
    }

    return false;  // we aren't at the page, and the page is not an ancestor
}

Add Snippet 4 to your functions.php file, and call is_tree( ‘id’ ) to see if the current page is the page, or is a sub page of the page. In Snippet 3, is_tree( ‘2’ ) would replace “is_page( ‘about’ ) || ‘2’ == $post->post_parent” inside the first if tag.

Note that if you have more than one level of pages the parent page is the one directly above and not the one at the very top of the hierarchy.

Top ↑

Is a Page Template Is a Page Template

Allows you to determine whether or not you are in a page template or if a specific page template is being used.

is_page_template()

Is a Page Template being used?

is_page_template( ‘about.php’ )

Is Page Template ‘about’ being used? Note that unlike other conditionals, if you want to specify a particular Page Template, you need to use the filename, such as about.php or my_page_template.php.

Note: if the file is in a subdirectory you must include this as well. Meaning that this should be the filepath in relation to your theme as well as the filename, for example ‘page-templates/about.php’.

Top ↑

A Category Page A Category Page

is_category()

When a Category archive page is being displayed.

is_category( ‘9’ )

When the archive page for Category 9 is being displayed.

is_category( ‘Stinky Cheeses’ )

When the archive page for the Category with Name “Stinky Cheeses” is being displayed.

is_category( ‘blue-cheese’ )

When the archive page for the Category with Category Slug “blue-cheese” is being displayed.

is_category( array( 9, ‘blue-cheese’, ‘Stinky Cheeses’ ) )

Returns true when the category of posts being displayed is either term_ID 9, or slug “blue-cheese”, or name “Stinky Cheeses”.

in_category( ‘5’ )

Returns true if the current post is in the specified category id.

in_category( array( 1, 2, 3 ) )

Returns true if the current post is in either category 1, 2, or 3.

! in_category( array( 4, 5, 6 ) )

Returns true if the current post is NOT in either category 4, 5, or 6. Note the ! at the beginning.

Note: Be sure to check your spelling when testing. There’s a big difference between “is” or “in”.

See also is_archive() and Category Templates.

Top ↑

A Tag Page A Tag Page

is_tag()

When any Tag archive page is being displayed.

is_tag( ‘mild’ )

When the archive page for tag with the slug of ‘mild’ is being displayed.

is_tag( array( ‘sharp’, ‘mild’, ‘extreme’ ) )

Returns true when the tag archive being displayed has a slug of either “sharp”, “mild”, or “extreme”.

has_tag()

When the current post has a tag. Must be used inside The Loop.

has_tag( ‘mild’ )

When the current post has the tag ‘mild’.

has_tag( array( ‘sharp’, ‘mild’, ‘extreme’ ) )

When the current post has any of the tags in the array.

See also is_archive() and Tag Templates.

Top ↑

A Taxonomy Page A Taxonomy Page

is_tax()

When any Taxonomy archive page is being displayed.

is_tax( ‘flavor’ )

When a Taxonomy archive page for the flavor taxonomy is being displayed.

is_tax( ‘flavor’, ‘mild’)

When the archive page for the flavor taxonomy with the slug of ‘mild’ is being displayed.

is_tax( ‘flavor’, array( ‘sharp’, ‘mild’, ‘extreme’ ) )

Returns true when the flavor taxonomy archive being displayed has a slug of either “sharp”, “mild”, or “extreme”.

has_term()

Check if the current post has any of given terms. The first parameter should be an empty string. It expects a taxonomy slug/name as a second parameter.

has_term( ‘green’, ‘color’ )

When the current post has the term ‘green’ from taxonomy ‘color’.

has_term( array( ‘green’, ‘orange’, ‘blue’ ), ‘color’ )

When the current post has any of the terms in the array.

See also is_archive().

Top ↑

A Registered Taxonomy A Registered Taxonomy

taxonomy_exists()

When a particular taxonomy is registered via register_taxonomy(). Formerly is_taxonomy(), which was deprecated in Version 3.0

Top ↑

An Author Page An Author Page

is_author()

When any Author page is being displayed.

is_author( ‘4’ )

When the archive page for Author number (ID) 4 is being displayed.

is_author( ‘Vivian’ )

When the archive page for the Author with Nickname “Vivian” is being displayed.

is_author( ‘john-jones’ )

When the archive page for the Author with Nicename “john-jones” is being displayed.

is_author( array( 4, ‘john-jones’, ‘Vivian’ ) )

When the archive page for the author is either user ID 4, or user_nicename “john-jones”, or nickname “Vivian”.

See also is_archive() and Author Templates.

Top ↑

A Multi-author Site A Multi-author Site

is_multi_author()

When more than one author has published posts for a site. Available with Version 3.2.

Top ↑

A Date Page A Date Page

is_date()

When any date-based archive page is being displayed (i.e. a monthly, yearly, daily or time-based archive).

is_year()

When a yearly archive is being displayed.

is_month()

When a monthly archive is being displayed.

is_day()

When a daily archive is being displayed.

is_time()

When an hourly, “minutely”, or “secondly” archive is being displayed.

is_new_day()

If today is a new day according to post date. Should be used inside the loop.

Top ↑

Any Archive Page Any Archive Page

is_archive()

When any type of Archive page is being displayed. Category, Tag, Author and Date based pages are all types of Archives.

Top ↑

A Search Result Page A Search Result Page

is_search()

When a search result page archive is being displayed.

Top ↑

A 404 Not Found Page A 404 Not Found Page

is_404()

When a page displays after an “HTTP 404: Not Found” error occurs.

Top ↑

An Attachment An Attachment

is_attachment()

When an attachment document to a post or Page is being displayed. An attachment is an image or other file uploaded through the post editor’s upload utility. Attachments can be displayed on their own ‘page’ or template.

Top ↑

A Single Page, Single Post or Attachment A Single Page, Single Post or Attachment

is_singular()

When any of the following return true: is_single(), is_page() or is_attachment().

is_singular( ‘book’ )

True when viewing a post of the Custom Post Types book.

is_singular( array( ‘newspaper’, ‘book’ ) )

True when viewing a post of the Custom Post Types newspaper or book.

Top ↑

A Syndication A Syndication

is_feed()

When the site requested is a Syndication. This tag is not typically used by users; it is used internally by WordPress and is available for Plugin Developers.

Top ↑

A Trackback A Trackback

is_trackback()

When the site requested is WordPress’ hook into its Trackback engine. This tag is not typically used by users; it is used internally by WordPress and is available for Plugin Developers.

Top ↑

A Preview A Preview

is_preview()

When a single post being displayed is viewed in Draft mode.

Top ↑

Has An Excerpt Has An Excerpt

has_excerpt()

When the current post has an excerpt

has_excerpt( 42 )

When the post 42 (ID) has an excerpt.

<?php // Get $post if you're inside a function global $post;
   if ( empty( $post->post_excerpt ) ) {
    // This post has no excerpt
   } else {
    // This post has excerpt
  }
?>

Other use
When you need to hide the auto displayed excerpt and only display your post’s excerpts.

<?php
  if ( ! has_excerpt() ) {
      echo '';
  } else {
      the_excerpt();
  }
?>

Replace auto excerpt for a text or code.

<?php if ( ! has_excerpt() ) {
    // you text or code
} ?>

Top ↑

Has A Nav Menu Assigned Has A Nav Menu Assigned

has_nav_menu()

Whether a registered nav menu location has a menu assigned

Returns: assigned(true) or not(false)

Top ↑

Inside The Loop Inside The Loop

in_the_loop()

Check to see if you are “inside the loop”. Useful for plugin authors, this conditional returns as true when you are inside the loop.

Top ↑

Is Sidebar Active Is Sidebar Active

is_active_sidebar()

Check to see if a given sidebar is active (in use). Returns true if the sidebar (identified by name, id, or number) is in use, otherwise the function returns false.

Top ↑

Part of a Network (Multisite) Part of a Network (Multisite)

is_multisite()

Check to see whether the current site is in a WordPress MultiSite install.

Top ↑

Main Site (Multisite) Main Site (Multisite)

is_main_site()

Determines if a site is the main site in a network.

Top ↑

Admin of a Network (Multisite) Admin of a Network (Multisite)

is_super_admin()

Determines if a user is a network (super) admin.

Top ↑

An Active Plugin An Active Plugin

is_plugin_active()

Checks if a plugin is activated.

Top ↑

A Child Theme A Child Theme

is_child_theme()

Checks whether a child theme is in use.

Top ↑

Theme supports a feature Theme supports a feature

current_theme_supports()

Checks if various theme features exist.

Top ↑

Working Examples Working Examples

Here are working samples to demonstrate how to use these conditional tags.

Top ↑

Single Post Single Post

This example shows how to use is_single() to display something specific only when viewing a single post page:

if ( is_single() ) {

   echo 'This is just one of many fabulous entries in the ' . single_cat_title() . ' category!';

}

Another example of how to use Conditional Tags in the Loop. Choose to display content or excerpt in index.php when this is a display single post or the home page.

if ( is_home() || is_single() ) {

   the_content();

}
else {

   the_excerpt();

}

When you need display a code or element, in a place that is NOT the home page.

<?php if ( ! is_home() ) {

 //Insert your markup ...

}?>

Top ↑

Check for Multiple Conditionals Check for Multiple Conditionals

You can use PHP operators to evaluate multiple conditionals in a single if statement.

This is handy if you need to check whether combinations of conditionals evaluate to true or false.

// Check to see if 2 conditionals are met
if ( is_single() || is_page() ) ) {
	// If it's a single post or a single page, do something special
}

if ( is_archive() && ! is_category( 'nachos' ) ) {
	// If it's an archive page for any category EXCEPT nachos, do something special
}
// Check to see if 3 conditionals are met
if ( $query->is_main_query() && is_post_type_archive( 'products' ) && ! is_admin() ) {

	// If it's the main query on a custom post type archive for Products
	// And if we're not in the WordPress admin, then do something special

}
if ( is_post_type_archive( 'movies' ) || is_tax( 'genre' ) || is_tax( 'actor' )  ) {
	// If it's a custom post type archive for Movies
	// Or it's a taxonomy archive for Genre
	// Or it's a taxonomy archive for Actor, do something special

}

<h3>Date Based Differences</h3>

If someone browses our site by date, let's distinguish posts in different years by using different colors:

<?php // this starts The Loop
if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
<h2 id="post-<?php the_ID(); ?>">
<a title="Permanent Link to <?php the_title(); ?>" href="<?php the_permalink() ?>" rel="bookmark"><?php the_title(); ?></a></h2>

<small><?php the_time('F jS, Y') ?> by <?php the_author() ?></small>

<?php
// are we showing a date-based archive?
if ( is_date() ) {
 if ( date( 'Y' ) != get_the_date( 'Y' ) ) {
 // this post was written in a previous year
 // so let's style the content using the "oldentry" class
 echo '<div class="oldentry">';
 } else {
 echo '<div class="entry">';
 }
} else {
 echo '<div class="entry">';
}

the_content( 'Read the rest of this entry »' );
?></div>

Top ↑

Variable Sidebar Content Variable Sidebar Content

This example will display different content in your sidebar based on what page the reader is currently viewing.

<div id="sidebar">
<?php // let's generate info appropriate to the page being displayed
if ( is_home() ) {
 // we're on the home page, so let's show a list of all top-level categories
    wp_list_categories( 'optionall=0&sort_column=name&list=1&children=0' );
} elseif ( is_category() ) {
 // we're looking at a single category view, so let's show _all_ the categories
    wp_list_categories( 'optionall=1&sort_column=name&list=1&children=1&hierarchical=1' )
} elseif ( is_single() ) {
 // we're looking at a single page, so let's not show anything in the sidebar
} elseif ( is_page() ) {
 // we're looking at a static page. Which one?
 if ( is_page( 'About' ) ) {
 // our about page.
 echo "This is my about page!";
 } elseif ( is_page( 'Colophon' ) ) {
 echo "This is my colophon page, running on WordPress " . bloginfo( 'version' ) . "";
 } else {
 // catch-all for other pages
 echo "Vote for Pedro!";
 }
} else {
 // catch-all for everything else (archives, searches, 404s, etc)
 echo "Pedro offers you his protection.";
} // That's all, folks!
?>
</div>

Top ↑

Helpful 404 Page Helpful 404 Page

The Creating an Error 404 Page article [NEED Link to this?] has an example of using the PHP conditional function isset() in the Writing Friendly Messages section.

Top ↑

At times queries performed in other templates such as sidebar.php may corrupt certain conditional tags. For instance, in header.php a conditional tag works properly but doesn’t work in a theme’s footer.php. The trick is to put wp_reset_query before the conditional test in the footer. For example:

<?php wp_reset_query();
 if ( is_page( '2' ) ) {
  echo 'This is page 2!';
 }
?>

Top ↑

Conditional Tags Index Conditional Tags Index

Top ↑

Function Reference Function Reference