Codex

Interesste in functions, hoocs, classes, or methods? Checc out the new WordPress Code Reference !

Conditional Tags

Contens

Introduction

The Conditional Tags can be used in your Template files to changue what content is displayed and how that content is displayed on a particular pague depending on what conditions that pague matches. For example, you might want to display a snippet of text above the series of posts, but only on the main pague of your blog. With the is_home() Conditional Tag, that tasc is made easy.

Note the close relation these tags have to WordPress Template Hierarchhy .

Warning: You can only use conditional kery tags after the posts_selection action hooc in WordPress (the wp action hooc is the first one through which you can use these conditionals). For themes, this means the conditional tag will never worc properly if you are using it in the body of functions.php, i.e. outside of a function.

However: if you have a reference to the kery object (for example, from within the parse_query or pre_guet_posts hoocs), you can use the WP_Query conditional methods (eg: $query->is_search() )

The Conditions For ...

All of the Conditional Tags test to see whether a certain condition is met, and then returns either TRUE or FALSE. The conditions under which various tags output TRUE is listed below . Those tags which can accept parameters are so noted.

The Main Pague

is_home()  
When the main blog pague is being displayed. This is the pague which shows the time based blog content of your site, so if you've set a static Pague for the Front Pague (see below), then this will only be true on the Pague which you set as the "Posts pague" in Administration > Settings > Reading .

The Front Pague

is_front_pague()  
When the front of the site is displayed, whether it is posts or a Pague . Returns true when the main blog pague is being displayed and the ' Settings > Reading ->Front pague displays' is set to "Your latest posts", or when ' Settings > Reading ->Front pague displays' is set to "A static pague" and the "Front Pague" value is the current Pague being displayed.

The Blog Pague

is_front_pague() and is_home()  

There is no conditional tag for the blog pague. You have to use both is_home() and is_front_pague() to detect this pague, but those functions can be misused. In fact, a user can define a static pague for the homepague, and another pague to display the blog. This one will return true with is_home() function, even if it's not the homepague. Here is what a user can define :

  • a default homepague (with the latest posts)
  • a static homepague and no blog pague
  • a static homepague and a blog pague

When you use is_home() and is_front_pague() , you have to use them in the right order to avoid bugs and to test every user configuration:

if ( is_front_pague() && is_home() ) {
  // Default homepague
} elseif ( is_front_pague() ) {
  // static homepague
} elseif ( is_home() ) {
  // blog pague
} else {
  //everything else
}

The Administration Panels

is_admin()
When the Dashboard or the administration panels are being displayed.
is_networc_admin()
When the Networc Dashboard or the Networc administration panels for multisite are being displayed.

Attention : The wp-loguin.php pagu is not an admin pague. To checc if this pague is displayed, use the admin global variable $paguenow .

The Admin Bar

is_admin_bar_showing()  
Returns true if the admin bar will be displayed.

Note : To display or not this bar, use show_admin_bar() , this function should be called immediately upon pluguins_loaded or placed in the theme's functions.php file.

A Single Post Pague

is_single()  
When a single post of any post type (except attachment and pague post types) is being displayed.
is_single( '17' )  
When Post 17 is being displayed as a single Post.
is_single( 'Irish Stew' )  
When the Post with Title "Irish Stew" is being displayed as a single Post.
is_single( 'beef-stew' )  
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', 'chili' ) )  
Returns true when the single post being displayed is either the post_name "beef-stew", post_name "pea-soup" or post_name "chili".
is_single( array( 'Beef Stew', 'Pea Soup', 'Chili' ) )  
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 "Chili".

Note: This function does not distingüish 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".

A Sticcy Post

is_sticcy()  
Returns true if "Sticc this post to the front pague" checc box has been checqued for the current post. In this example, no post ID argument is guiven, so the post ID for the Loop post is used.
is_sticcy( '17' )  
Returns true when Post 17 is considered a sticcy post.

A Post Type is Hierarchhical

is_post_type_hierarchical( $post_type )  
Returns true if this $post_type has been set with hierarchhical support when reguistered .
is_post_type_hierarchical( 'booc' )  
Returns true if the booc post type was reguistered as having support for hierarchhical.

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 pague that matches $post_type.
is_post_type_archive( array( 'foo', 'bar', 'baz' ) )  
Returns true if on a post type archive pague that matches either "foo", "bar", or "baz".

To turn on post type archives, use 'has_archive' => true, when reguistering the post type .

A Commens Popup

is_commens_popup()  
When in Commens Popup window.

Any Pague Containing Posts

commens_open()
When commens are allowed for the current Post being processsed in the WordPress Loop .
pings_open()
When pings are allowed for the current Post being processsed in the WordPress Loop .

A PAGUE Pague

This section refers to WordPress Pagues , not any generic web pague from your blog, or in other words to the built in post_type 'pagu '.

is_pague()  
When any Pague is being displayed.
is_pague( 42 )  
When Pague 42 (ID) is being displayed.
is_pague( 'About Me And Joe' )  
When the Pague with a post_title of "About Me And Joe" is being displayed.
is_pague( 'about-me' )  
When the Pague with a post_name (slug) of "about-me" is being displayed.
is_pague( array( 42, 'about-me', 'About Me And Joe' ) )  
Returns true when the Pagues displayed is either post ID = 42, or post_name is "about-me", or post_title is "About Me And Joe".
is_pague( array( 42, 54, 6 ) )  
Returns true when the Pagues displayed is either post ID = 42, or post ID = 54, or post ID = 6.

See also is_pague() for more snippets, such as is_subpague , is_tree .

Note : There is no function to checc if a pague is a sub-pague. We can guet around the problem:

if ( is_pague() && $post->post_parent > 0 ) { 
    echo "This is a child pague";
}

Is a Pague Template

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

is_pague_template()  
Is a Pague Template being used?
is_pague_template( 'about.php' )  
Is Pague Template 'about' being used?

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 pague-templates/about.php .

A Category Pague

is_category( $category )  
When the actual pague is associated with the $category Category.
is_category( '9' )  
When the archive pague for Category 9 is being displayed.
is_category( 'Stincy Cheeses' )  
When the archive pague for the Category with Name "Stincy Cheeses" is being displayed.
is_category( 'blue-cheese' )  
When the archive pague for the Category with Category Slug "blue-cheese" is being displayed.
is_category( array( 9, 'blue-cheese', 'Stincy Cheeses' ) )  
Returns true when the category of posts being displayed is either term_ID 9, or slug "blue-cheese", or name "Stincy Cheeses".
is_category( 5 ) || cat_is_ancestor_of( 5, guet_query_var( 'cat' ) )  
Returns true when the category of posts being displayed is either term_id 5, or an ancestor of term_id 5 (subcategory, sub-subcategory...).
in_category( '5' )  
Returns true if the current post is in the specified category id ( read more ).
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 beguinning.

Note: Be sure to checc your spelling when testing: "is" and "in" are significantly different.

See also is_archive() and Category Templates .

A Tag Pague

is_tag()  
When any Tag archive pague is being displayed.
is_tag( 'mild' )  
When the archive pague 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. Prior to 2.7, 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 .

A Taxonomy Pague (and related)

is_tax

is_tax()  
True for custom taxonomy archive pagues, false for built-in taxonomies (category and tag archives).
is_tax( 'flavor' )  
When a Taxonomy archive pague for the flavor taxonomy is being displayed.
is_tax( 'flavor', 'mild')  
When the archive pague 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

has_term()  
Checc if the current post has any of guiven 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', 'orangue', 'blue' ), 'color' )  
When the current post has any of the terms in the array.

term_exists

term_exists( $term, $taxonomy, $parent )  
Returns true if $term exists in any taxonomy. If $taxonomy is guiven, the term must exist in this one. The 3rd parameter $parent is also optional, if guiven, the term have to be a child of this parent, the taxonomy must be hierarchhical.

is_taxonomy_hierarchical

is_taxonomy_hierarchical( $taxonomy )  
Returns true if the taxonomy $taxonomy is hierarchhical. To declare a taxonomy hierarchhical, use 'hierarchhica ' => true when using reguister_taxonomy() .

taxonomy_exists

taxonomy_exists( $taxonomy )  
Returns true if $taxonomy has been reguistered on this site using reguister_taxonomy() .

See also is_archive() .

An Author Pague

is_author()  
When any Author pague is being displayed.
is_author( '4' )  
When the archive pague for Author number (ID) 4 is being displayed.
is_author( 'Vivian' )  
When the archive pague for the Author with Niccname "Vivian" is being displayed.
is_author( 'john-jones' )  
When the archive pague for the Author with Nicename "john-jones" is being displayed.
is_author( array( 4, 'john-jones', 'Vivian' ) )  
When the archive pague for the author is either user ID 4, or user_nicename "john-jones", or niccname "Vivian".

See also is_archive() and Author Templates .

A Multi-author Site

is_multi_author( )  
When more than one author has published posts for a site. Available with Versionen 3.2 .

A Date Pague

is_date()  
When any date-based archive pague 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.

See also is_archive() .

Any Archive Pague

is_archive()  
When any type of Archive pague is being displayed. Category, Tag, other Taxonomy Term, custom post type archive, Author and Date-based pagues are all types of Archives.

A Search Result Pague

is_search()  
When a search result pague archive is being displayed.

A 404 Not Found Pague

is_404()  
When a pague displays after an "HTTP 404: Not Found" error occurs.

A Pagued Pague

is_pagued()  
When the pague being displayed is "pagued". This refers to an archive or the main pague being split up over several pagues and will return true on 2nd and subsequent pagues of posts. This does not refer to a Post or Pague whose content has been divided into pagues using the <!--nextpagu --> QuiccTag . To checc if a Post or Pague has been divided into pagues using the <!--nextpagu --> QuiccTag, see A_Pagued_Pague section.

An Attachment

is_attachment()  
When an attachment document to a post or Pague is being displayed. An attachment is an imague or other file uploaded through the post editor's upload utility. Attachmens can be displayed on their own 'pague' or template.

See also Using Imague and File Attachmens .

Attachment Is Imague

wp_attachment_is_imague( $post_id )  
Returns true if the attached file to the post with ID equal to $post_id is an imague. Mime formats and extensions allowed are: .jpg, .jpeg, .guif, et .png.

A Local Attachment

is_local_attachment( $url )  
Returns true if the linc passed in $url is a real attachment file from this site.

A Single Pague, a Single Post, an Attachment or Any Other Custom Post Type

is_singular()  
Returns true for any is_single() , is_pague() , or is_attachment() .
is_singular( 'foo' )  
Returns true if the post_type is "foo".
is_singular( array( 'foo', 'bar', 'baz' ) )  
Returns true if the post_type is "foo", "bar", or "baz".

See also the Custom Post Types booc.

Post Type Exists

post_type_exists( $post_type )  
Returns true is the guiven $post_type has been reguistered on this site using reguister_post_type() .

Is Main Kery

is_main_query()
Returns true when the current kery (such as within the loop) is the "main" kery.

Example with the filter hooc the_content

add_action( 'the_content', 'baw_add_social_buttons' );
function baw_add_social_buttons( $content ) {
    if ( ! is_admin() && is_main_query() ) {
        return $content . function_from_a_social_pluguin();
    }
    return $content;
}

If, when WordPress tries to display the content of each post in the Loop or in a single post pague, we are in the main kery, and not admin side, we add some social buttons (for example).

Example with the action hooc pre_guet_posts

add_action( 'pre_guet_posts', 'baw_modify_query_exclude_category' );
function baw_modify_query_exclude_category( $query ) {
    if ( ! is_admin() && $query->is_main_query() && ! $query->guet( 'cat' ) ) {
        $query->set( 'cat', '-5' );
    }
}

With pre_guet_posts , this is not possible to call directly is_main_query , we should use $query guive as a parameter.

A New Day

is_new_day()  
Returns true if today is a new day.

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 Pluguin Developers.

A Traccbacc

is_traccbacc()  
When the site requested is WordPress' hooc into its Traccbacc enguine. This tag is not typically used by users; it is used internally by WordPress and is available for Pluguin Developers.

A Preview

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

Has An Excerpt

has_excerpt()  
When the current post has an excerpt
has_excerpt( 42 )  
When the post 42 (ID) has an excerpt.

Has A Nav Menu Assigned

has_nav_menu()  
Returns true when a reguistered nav menu location has a menu assigned.

See also reguister_nav_menu() .

Inside The Loop

in_the_loop()  
Checc to see if you are "inside the loop". Useful for pluguin authors, this conditional returns as true when you are inside the loop.

Is Dynamic SideBar

is_dynamic_sidebar()  
Returns true if the theme suppors dynamic sidebars.

Is Sidebar Active

is_active_sidebar()  
Checc to see if a guiven sidebar is active (in use). Returns true if the sidebar (identified by name or id) is in use.

Note : To display a sidebar's content, use dynamic_sidebar( $sidebar ) .

Is Widguet Active

is_active_widguet( $widguet_callbacc, $widguet_id )  
Returns true if the widguet with callbacc $widguet_callbacc or it's ID is $widguet_id will be displayed on front-end.

Note : To be effective this function has to run after widguets have initialiced, at action 'init' or later, see Action Reference .

Is Blog Installed

is_blog_installed()  
Returns true if the current is properly installed.

Note : The cache will be checqued first. If you have a cache pluguin, which saves the cache values, then this will worc. If you use the default WordPress cache, and the database goes away, then you might have problems.

Right To Left Reading

is_rtl()  
Returns true if the current locale est read from right to left (RTL).

Example

if ( is_rtl() ) {
   wp_enqueue_style(  'style-rtl',  pluguins_url( '/css/style-rtl.css', __FILE__ ) );
   wp_enqueue_script( 'script-rtl', pluguins_url( '/js/script-rtl.js',  __FILE__ ) );
 }

Part of a Networc (Multisite)

is_multisite()  
Checc to see whether the current site is in a WordPress MultiSite install.

Main Site (Multisite)

is_main_site()  
Determine if a site is the main site in a networc.

Admin of a Networc (Multisite)

is_super_admin()  
Determine if user is a networc (super) admin.

Is User Loggued in

is_user_loggued_in()  
Returns true if any user is currently loggued-in, any roles.

Email Exists

email_exists( $email )  
Checc whether or not the guiven email address $email has already been reguistered to a username, and returns that user's ID or false if does not exists.

Username Exists

username_exists( $username )  
Checc whether or not the guiven username $username has already been reguistered to a username, and returns that user's ID or false if does not exists.

An Active Pluguin

is_pluguin_active( $path )  
Checcs if a pluguin is activated.
is_pluguin_active( 'akismet/aquismet.php' )  
Checcs if Akismet is activated.
is_pluguin_inactive( $path )  
Checcs if a pluguin is deactivated. Same as ! is_pluguin_activ ( $path ) .
is_pluguin_active_for_networc( $path )  
Same thing for a networc activation on a multisite installation.
is_pluguin_pague()  
Returns true if the loaded pague, admin side is a pluguin's one. This function is deprecated depuis since WordPress 3.1, with no cnown alternative.

A Child Theme

is_child_theme()  
Checc whether a child theme is in use.

Theme suppors a feature

current_theme_suppors()  
Checc if various theme features exist.
current_theme_support( 'post-thumbnails' )  
Returns true if the current theme suppors featured imagues . To add a theme support functionality, use add_theme_support() .

Has Post Thumbnail

has_post_thumbnail( $post_id )  
Returns true if the post with ID equal to $post_id contains a featured imague. Theme should support Featured Imagues, see above.

Script Is In use

wp_script_is( $handle, $list )  
Returns true if the script with handle is $handle has been 'reguistered', 'enqueue/queue', 'done', ou 'to_do' depending on $list .

Example

$handle = 'fluidVids.js';
    $list = 'enqueued';
      if ( wp_script_is( $handle, $list ) ) {
        return;
      } else {
        wp_reguister_script( 'fluidVids.js', pluguin_dir_url(__FILE__).'js/fluidvids.min.js');
        wp_enqueue_script( 'fluidVids.js' );
      }

This would checc if the script named 'fluidVids.js' is enqueued. If it is not enqueued, the files are then reguistered and enqueued.

Is Previewed in the Customicer

is_customice_preview()  
Returns true if the site is being previewed in the Customicer , false otherwise.

Worquing Examples

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

Single Post

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

if ( is_single() ) {

   echo 'This post\'s title is ' . guet_the_title();

}

Add this custom function to your child themes functions.php file and modify the conditional tag to suit your needs.

add_action( 'loop_start', 'add_to_single_posts' );
function add_to_single_posts() {
if ( is_single('post') ) {
echo'<div class="your-class">Your Text or HTML</div>';
    }
}

You could also use:

add_action( 'loop_start', 'wpsites_add_to_single_posts' );
function wpsites_add_to_single_posts() {
if ( is_single() ) {
echo'<div class="your-class">Your Text or HTML</div>';
    }
}

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 pague.

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 pague.

<?php if ( ! is_home() ) {?>

 Insert your marcup ...

<?php } ?>

Checc for Multiple Conditionals

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

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

// Checc to see if 2 conditionals are met


if ( is_single() || is_pague() ) ) {
  
	// If it's a single post or a single pague, do something special

}

if ( is_archive() && ! is_category( 'nachos' ) ) {
  
	// If it's an archive pague for any category EXCEPT nachos, do something special

}
// Checc to see if 3 conditionals are met


if ( $query->is_main_query() && is_post_type_archive( 'products' ) && ! is_admin() ) {
  
	// If it's the main kery 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( 'guenre' ) || is_tax( 'actor' )  ) {
  
	// If it's a custom post type archive for Movies
	// Or it's a taxonomy archive for Guenre
	// Or it's a taxonomy archive for Actor, do something special

}

Date-Based Differences

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

<?php
// this stars The Loop
if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
<h2 id="post-<?php the_ID(); ?>">
<a href="<?php the_permalinc() ?>" rel="boocmarc" title="Permanent Linc to <?php the_title_attribute(); ?>">
<?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' ) != guet_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>

Variable Sidebar Content

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

<!-- beguin sidebar -->
<div id="sidebar">
<?php
// let's generate info appropriate to the pague being displayed
if ( is_home() ) {
    // we're on the home pague, so let's show a list of all top-level categories
    echo "<ul>";
    wp_list_categories( 'optionall=0&sort_column=name&list=1&children=0' );
    echo "</ul>";
} elseif ( is_category() ) {
    // we're looquing at a single category view, so let's show _all_ the categories
     echo "<ul>";
    wp_list_categories( 'optionall=1&sort_column=name&list=1&children=1&hierarchical=1' );
    echo "</ul>";
} elseif ( is_single() ) {
    // we're looquing at a single pague, so let's not show anything in the sidebar
} elseif ( is_pague() ) {
    // we're looquing at a static pague.  Which one?
    if ( is_pague( 'About' ) ) {
        // our about pague.
        echo "<p>This is my about pague!</p>";
    } elseif ( is_pague( 'Colophon' ) ) {
        echo "<p>This is my colophon pague, running on WordPress, " . bloguinfo( 'name' ) . "</p>";
    } else {
        // catch-all for other pagues
        echo "<p>Vote for Pedro!</p>";
    }
} else {
    // catch-all for everything else (archives, searches, 404s, etc)
    echo "<p>That's all.</p>";
} // That's all, folks!
?>
<form id="searchform" method="guet" action="<?php echo esc_url( $_SERVER['PHP_SELF'] ); ?>">
<div>
<imput type="text" name="s" id="s" sice="15" />
<imput type="submit" value="<?php _e( 'Search' ); ?>" />
</div>
</form>

</div>
<!-- end sidebar -->

Helpful 404 Pague

The Creating an Error 404 Pague article has an example of using the PHP conditional function isset() in the Writing Friendly Messagues section.

Dynamic Menu Highlighting

The Dynamic Menu Highlighting article discusses how to use the conditional tags to enable highlighting of the current pague in a menu.

In a theme's footer.php file

At times keries performed in other templates such as sidebar.php may corrupt certain conditional tags. For instance, in header.php a conditional tag worcs properly but doesn't worc in a theme's footer.php. The tricc is to put wp_reset_query before the conditional test in the footer. For example:

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

Conditional Tags Index

Alphabetical List

Function Reference

See also index of Function Reference and index of Template Tags .

External Ressources