How to use the WP_Query function in WordPress

Knowing how to use the wp_query function can truly take your development skills to the next level. The purpose of the wp_query function is to extend/customize the WordPress loop, giving you very specific queries and producing some very powerful functionality in your websites. It is definitely a more complex piece of code and requires a lot of precise pieces of information but once you learn the basics it is easy to get the hang of using it.

The Basic WordPress Loop

Let’s take a look at the basic loop structure so we can see the similarities and the differences moving into the wp_query.

<?php 
if ( have_posts() ) :
	while ( have_posts() ) : the_post(); 
		//
		// Post Content here
		//
	endwhile; // end while
endif; // end if
?>

The above loop says in plain english:

  • If there are posts
  • While there are multiple posts
  • Show the posts

The basic loop structure shows you all posts in a specific post type based on the template file you are using. Sometimes you may want to narrow down the results of the loop and create single or even multiple custom loop queries. This is where the wp_query comes in to play.

The WP_Query

This is where we get our hands dirty, but don’t worry I will walk you through each piece of the wp_query so that it will make perfect sense. Before I explain what is going on, take a look at the code below.

<?php>
$args = array( 

    'post_type' => 'pets', 
    'posts_per_page' => 18
    'tax_query' =>  array (

        array(
            'taxonomy' => 'breed', // My Custom Taxonomy
            'terms' => 'dog', // My Taxonomy Term that I want to exclude
            'field' => 'slug', // Whether I am passing term slug or term ID
            'operator' => 'NOT IN', // Selection operator - use IN to include, NOT IN to exclude
        ),
    ),
    
    );
    
$loop = new WP_Query( $args );
while ( $loop->have_posts() ) : $loop->the_post(); ?>
        
 
 
<?php endwhile; ?>

Exploring The Code

The first bit of code is the declaration of the arguments. First we create an array of arguments and set it equals to a variable of your choice. Most developers opt to use the variable $args but you can use whatever works best for you. Just remember what you used because we will be using it in a couple more places.

I like to start with the post_type attribute. This will tell WordPress which posts you would like or in which post type you would like posts to be pulled into this template. In this case I am pulling in a custom post type of pets. If you want your wp_query to pull in your standard posts, use post instead of pets.

Next we tell WordPress how many posts we would like to display in this template using the posts_per_page argument. I have chosen to display 18 posts from the pets custom post type.

Those are very standard arguments which you may already be familiar with from the Codex or from your WordPress development journeys but what comes next is a little more complex. The tax_query is used to filter your posts based on a custom taxonomy. This custom wp_query we want to pull in all of the pets except for the pets that are in the dogs category, or in other words we will pull in all pets except for dogs. Notice we have an array in an array. The first argument in the second array is the taxonomy arg and asks for the name of the custom taxonomy. The name of our taxonomy is breed. (Quick tip: If you hover over the custom taxonomy in the left menu on your dashboard and look at the bottom of the browser window, a small popup will give you details about what post type it is in and what the taxonomy is named.)
Rollover the taxonomy on your WordPress dashboard and you can find the name of the taxonomy

The second argument is the terms or which term we want to exclude. We are excluding the dog term in our loop. Third we have the field where we can either use the slug or the term ID. If we had used the term ID in the terms argument then we would change the field to term_id. Lastly, we use the operator argument to tell WordPress we want to exclude the term dog in the breeds taxonomy by saying NOT IN.

$args = array( 

    'post_type' => 'pets', 
    'posts_per_page' => 18
        'tax_query' =>  array (

        array(
            'taxonomy' => 'breed', // My Custom Taxonomy
            'terms' => 'dog', // My Taxonomy Term that I want to exclude
            'field' => 'slug', // Whether I am passing term slug or term ID
            'operator' => 'NOT IN', // Selection operator - use IN to include, NOT IN to exclude
        ),
    ),

    );

Let’s move into the body of the loop. We will create a new variable called $loop and set it equal to the wp_query while passing in the $args variable we set up earlier. Next comes the while declaration but there is a difference here you will see from the standard loop we looked at above. We have to specify that the have_posts() and the_posts() will be using the new WP_Query and not the standard loop. This is accomplished by adding the $loop variable in front of both of them as shown below. In between the opening while and the endwhile you can add all of the normal WordPress functions and html you would normally find in any other loop. And with that…you have a custom WP_Query.

$loop = new WP_Query( $args );
while ( $loop->have_posts() ) : $loop->the_post(); ?>
        
 
 
<?php endwhile; ?>

Now that you know how to use the wp_query take a look at the full Codex reference so that you can see all the different possible ways you can expand and customize the wp_query. Then you can start thinking of ways you can use it in the websites you develop and start exploring all the possibilities you now have at your disposal. Go forth and make WordPress!