Conditional tags are functions used in WordPress themes and plugins to display content, or perform actions, based upon whether a certain condition is true or not. A condition can be anything; it might be a condition for whether the user is currently viewing the homepage, or a condition for whether the user is currently logged-in. It could also be a condition for whether a visitor is on a mobile device. If you are not actively using conditional tags in your development, you should be; they are an extremely useful tool to have in your arsenal.

Basics – The Format and Syntax of a Conditional Tag

There is no limit to the number of conditional tags available, since developers can easily create their own, but they all have the same basic appearance and syntax. They follow the format below:

IF ( SOME CONDITION IS TRUE )  {
    DO THIS STUFF HERE
}

If the condition we have specified (in the parentheses) is true or valid, do whatever comes next inside of the curly brackets. If the condition is NOT true, then the stuff in the curly brackets will be ignored.

We can also specify that our “stuff” should only happen if a condition is NOT true. The way we do this is by adding a “!” to the start of our condition, like this:

IF ( ! SOME CONDITION IS TRUE )  {
    DO THIS STUFF HERE
}

This says “if some condition is NOT true/valid”, do the stuff in the curly brackets.

Another common conditional form to use is IF/ELSE. First a condition is checked and “stuff” is done if the condition is true, but if the condition is NOT true, then other “stuff” is done.

IF ( SOME CONDITION IS TRUE )  {
    DO THIS STUFF HERE
} ELSE {
    DO OTHER STUFF HERE
}

There are additional forms, but we will start with just these three for now.

Using a Real Template Tag

In a moment I will give detailed example of some of the common template tags used, but first let us take a look at a simple, but real, example.

One of the very common uses for conditional tags is for determining whether a site visitor is on a specific page. For example, we might want to display some additional content in our sidebar if the visitor is on our “About” page. To do this, we can use the conditional tag called is_page(). The format of this tag, and most others, looks like this:

if( is_page( THE PAGE IDENTIFIER ) ) {
   // do this "stuff" here
}

The “THE PAGE IDENTIFIER” is just a place holder. In a real application, this is replaced with one of four things:

  • The title of the page
  • The ID number of the page
  • The unique slug of the page
  • A mixed array of page titles, IDs, and slugs (we won’t go into this for now)

Let’s assume that we are going to use the page title for now, as that is the simplest to find. In this case, our page title is “About”, so that is what we will use:

if( is_page( 'About' ) ) {
   echo 'This content is only shown on the About page'; 
}

This will output This content is only shown on the About page, but only when the visitor is viewing the about page. Now let’s say that we want to output some text on the about page, as we have done, but also on the Contact page. Above I mentioned that we can do IF/ELSE conditionals, and that is what we can easily use to stringing conditionals to together, like this:

if( is_page( 'About' ) ) {
   echo 'This content is only shown on the About page'; 
} elseif( is_page( 'Contact' ) ) {
   echo 'This is Contact-only page content'; 
}

By combining the two statements, we have the following logic:

IF ON ABOUT PAGE > OUTPUT THIS
OTHERWISE, IF ON THE CONTACT PAGE > OUTPUT THIS
IF NOT ON EITHER OF THESE PAGES > DO NOTHING

Exploring Some Common WordPress Template Tags

There dozens and dozens of conditional tags included with WordPress, and I highly recommend that you browse through them on the Conditional Tags Codex page. I am going to talk about and walk through perhaps a dozen of the most commonly used.

1. is_home()

This is a very common tag, but it is also very commonly misused, or at least misunderstood. You can use this tag to detect whether a visitor is on the blog page or not. As WordPress began as a blogging engine, the main blog page often acted as the site’s landing, or home, page. This tag will check for whatever page you have set as “Page for Posts” in the Reading section of the WordPress settings. It will also return true when on the site’s home page if you have the home page set to “Display Latest Posts”.

if( is_home() ) {
	echo 'Display this content on the blog page only';	
}

2. is_front_page()

This is the tag that will “truly” check whether a visitor is on the home/front page. As its name suggests, is_front_page() will return true when a visitor is looking at the site’s front page, regardless of whether your home page is set to “Display Latest Posts” or to “Static Page”.

if( is_front_page() ) {
	echo 'Display this content on the front/home page only';	
}

3. is_single()

This is used to detect when we are viewing a “single” blog post. For example, if we are viewing the complete details of the default “Hello World” blog post, then this conditional will return true. If you are familiar with theme development, and the WordPress template hierarchy, then this tag is more or less synonymous with the single.php file.

if( is_single() ) {
	echo 'This displays when viewing a single blog post';	
}

Unlike is_home() and is_front_page(), this tag can accept parameters for the post title, slug, ID, or a mixed array of these. For example, if we wanted to only output content for the “Hellow World” post, we can do this:

if( is_single('Hello World') ) {
	echo 'This displays when viewing a single blog post';	
}

Or, if we wanted to output something only for the blog post with an ID of 97, we can do this:

if( is_single(97) ) {
	echo 'This displays when viewing a single blog post';	
}

You might notice that the first example has the post title wrapped in single quotes. This is because “Hello World” is a string, whereas 97 is an integer. If you don’t wrap the single in single or double quotes, you will get a syntax error.

We can also combine both of our examples into one, for when we want to display the content on both Hello World and post ID 97:

if( is_single( array(97, 'Hello World') ) ) {
	echo 'This displays when viewing the "Hello World" post and the post with an ID of 97';	
}

Note, this tag does NOT return true when viewing the complete details/content of a Page.

4. is_page()

As used in our first example, this lets us check if we are viewing a Page item. Look at the example above if you want a simple example. If we want to check if we are on any of the specified pages, we can use an array, like I did in the last example of is_single():

if( is_page( array('my-page-slug', 'Contact') ) ) {
	echo 'This displays when viewing the "Contact" page and the page with a slug of "my-page-slug"';	
}

5. is_singular()

This tag is sort of a combination of is_single() and is_page(). It returns true anytime we are viewing a single blog post, a page, an attachment, or any custom post type. For example, the following will return true if we are on a page, post, attachment page, or custom post type details page:

if( is_singular() ) {
	echo 'This displays anytime we are viewing a details page';	
}

Essentially, is_singular() works for checking if we are viewing the details for anything. One of the great things about is_singular(), is that we can also use it to check if we are on the details page for a specific custom post type, like so:

if( is_singular( 'movies' ) ) {
	echo 'This displays when viewing a movies detail page';	
}

6. is_category()

The is_category() tag can be used to determine when we are viewing a category archive page. For example, we can use is_category() to output extra information anytime we are viewing the archives for a category, like this:

if( is_category() ) {
	echo 'This displays when viewing any category archive page';
}

Just like we have been able to check for specific posts or pages, we can also check for only specific categories. We can pass a parameter for category title, slug, ID, or, just as before, a mixed array of titles, slugs, and/or IDs.

For a single category:

if( is_category( 'Horror' ) ) {
	echo 'This displays when viewing the "Horror" category archives';
}

For multiple categories

if( is_category( array( 'Horror', 'love-and-drama', 67 ) ) ) {
	echo 'This displays when viewing the "Horror" category, the "Love and Drama" category, and the category with an ID of 67';
}

This tag has a nearly identical sister conditional of Post Tags.

7. has_tag()

Unlike is_category() and is_tag(), which are used for checking for tag/category archives, this conditional allows us to determine if the currently-being-viewed item has a specific tag applied to it. Let’s say we want to output some special content, such as an image, anytime a post has been tagged with the “Featured” tag:

if( has_tag( 'Featured' ) ) {
	echo 'This displays when a post has the featured tag';
}

We can also check for the existence of multiple tags by using an array:

if( has_tag( array( 'Featured', 'another-tag' ) ) ) {
	echo 'This displays when a post has the featured or another-tag tag';
}

8. is_search()

This is a very useful conditional that can be used for determining if we are viewing a search results screen.

if( is_search() ) {
	echo 'This displays when viewing search results';
}

So Many More

I have only listed 8 of the commonly used conditionals, and there are many, many more. There is a conditional tag for just about anything you want to check for in WordPress, and that is only with the default conditional tags that are included with WordPress core.

Writing Your Own Conditional Statements

If you are a developer, it is very common for you to create your own conditional tags. I, for example, make conditional tags all the time while writing plugins. In Easy Digital Downloads, as an example, I wrote a conditional tag that checks whether the plugin is being used in Test or Live mode. The tag looks like this:

if( edd_is_test_mode() ) {
    // EDD is being used in test mode
} else {
    // EDD is being used in live mode
}

This particular condition is used everywhere through the plugin in order to alter the information that is displayed (or the function of the plugin) based upon what mode is currently enabled.

A conditional tag is nothing more than a function that returns either TRUE or FALSE. Let’s take a look at the conditional I mentioned a moment ago for edd_is_test_mode(). The function itself is extremely simple:

function edd_is_test_mode() {
	global $edd_options;
	if(isset($edd_options['test_mode']))
		return true;
	return false;
}

The plugin settings are stored in the $edd_options global, which is an array, and the option that defines test mode is stored in the array key “test_mode”. The option itself is a checkbox. If the option is present, then we are in test mode, and so the function returns TRUE. If the option “test_mode” is NOT present, then we are in live mode, and so we return false.

That’s it. Very simple.

Do you write your own conditional tags often? How about you tell everyone about some of the ones you have made for your plugins or themes.

  1. Patrick Miravalle

    I found this to be a pretty informational tutorial. I’m just beginning to dive into WordPress theme and plugin development, and this is going to help me out tremendously.

    Thanks, Pippin!

  2. Evan Payne

    I use conditional tags to help with theme development. I suppose there’s a plugin for this, or one I could make, but I usually just insert a few conditional tags to check whether or not I’m logged in. If so, I display the work in progress theme, if not, I display whatever holding page I wish. This helps on redesigns as well, allowing me to work with the same content, on the same server, without scaring the public at large. The tags I use are:

    if ( is_user_logged_in() ) {
    // if the visitor is logged in, this bit will be displayed.
    } else {
    // if the visitor is NOT logged in, this bit will be displayed.
    }

    • Pippin

      That’s a good example. Is_user_logged_in is also great for creating “My Account” type pages.

  3. bobschecter

    Thank you Obi Wan, I look forward to the next lesson.

    • Pippin

      Ha, glad to help.

  4. John

    Could this be used with meta boxes in a custom post type? Say… if meta box is checked do something awesome?

    • Pippin

      Absolutely! That is the basis for this tutorial.

  5. gnmd

    This seems a bit old. Yet, I just need a function for conditionally display content based on date.

    1- I want to display content based on days (Monday, Tuesday …):


    This Monday!

    2- I want to display content based on months (January, February …):


    This February!

    This is correct to use in WordPress template files or having another ways?
    Thanks!

    • Pippin

      That should work fine.

  6. Carolyn

    You’ve explained this so clearly. I was thrilled to find this, Pippin.

    By removing the code from your initial example, you’ve decreased the intimidation factor for all of us who aren’t familiar with it. (And I love that you explain the !,)

    IF ( ! SOME CONDITION IS TRUE ) {
    DO THIS STUFF HERE
    }

    Then, by introducing the tags and explaining them one at a time and using solid real-life examples, you make it seem possible (for non-coders like me) to actually learn the code behind WordPress.

    I’m looking forward to reading more of your tutorials. Do you teach classes too?

    • Pippin

      Glad to hear it was helpful!

      I’ve never taught a formal class but I speak at WordCamps a lot.

  7. geomagas

    Great tutorial!

    I collected a bunch of Conditional Tags and made a plugin that provides an [if] shortcode for authors to be able to conditionally include content. It’s even extendable by adding filters for custom (and more complex) conditions!

    I’ve just managed to upload it on WordPress.org, so for anyone interested, here it is:
    http://wordpress.org/plugins/if-shortcode/

    Enjoy!

    • Raju

      Thanks Bro After Long Time i find Correct Information

  8. Mandy Puniya

    Hi sir, I want to insert adsense ads in the first post of index pages with the help of conditional tags, how can I do so?

    Please help. Thanks in advance.

  9. Jonas Lundman

    A common issue is that we are calling some of the conditionals in out functions.php, and they are not yet set. Like if( is_admin() add_filter( … works, but if( is_author() add_filter( .. NOT WORKING YET.

    Do you (?) have a EARLIEST hook where all the basic conditionals are set, I mean, WHERE is this “Doing it wrong, before query is set..” avoided?

Comments are closed.