Beginners Guide on Learning WP_Query

WP_Query is a powerful tool in WordPress programming. Learning WP_Query opens the door to new dimensions in WordPress. You can fetch posts and pages the way you want and display them according to your need. This tutorial is the beginners guide on learning WP_Query. We will first see how to create an object and then learn looping through the object to retrieve posts.

What is WP_Query?

WP_Query is a predefined class in WordPress that is used to pull the details of posts and pages from database.  WP_Query class is the replacement of the SQL queries for WordPress.

There are two cases when you might need to use WP_Query:

  1. The first case is for finding what type of request WordPress is dealing with. The $is_* properties are designed to hold this info. This case generally occurs when you are developing plugin.
  2. The second case is during loop operation.

Beginners Guide on Learning WP_Query

Understanding the Class and Object.

The WP_Query API uses a programming style called object-oriented programming, or OOP. To understand WP_Query you have to understand the concept of class and objects in OOP.

Class: Class is a way to bind data (properties) and functions (methods) together into a single group. In other word, class is the group or collection of data and functions.

Object: Object is the class variable.  We can create an object for a particular class by using the class name. Object contains the copies of the class data and functions.

In WordPress, WP_Query is a class which is already defined in wp-includes/query.php. So all we need to do is create an object of the WP_Query class. Here is the basic code to create the object of WP_Query class using the keyword ‘new’.

$args = array (
        'tag' => 'Plugins',
$query_obj = new WP_Query($args);

Here $query_obj is the object created which now has the copy of the parameters passed to the class. Now this object $query_obj can be used to return posts with tag ‘plugin’ and category ‘tutorials’.

Looping with WP_Query

When a group of code is executed repeatedly, it is called a loop. The object that we have created above has posts in it. Now we can loop through the object to retrieve the desired posts. Loop using WP_Query through specific object ‘$query_obj’ is done in certain way.

// The Loop
if ( $query_obj->have_posts() ) {
    while ( $query_obj->have_posts() ) {
        //retrive posts
} else {
// no posts found

In this loop the if statement checks if $query_obj object has post in it and while statement will loop until $query_obj has post in it. Now lets see the complete code to display all the posts with tags ‘Plugins’ and categories ‘tutorials’.

$args = array(
    'tag' => 'Plugin',
    'category_name' => 'Tutorial',
$query_obj = new WP_Query( $args );
if ( $query_obj->have_posts() ) : 
    while ( $query_obj->have_posts() ) :
       $query_obj->the_post(); ?>

       <h3><?php the_title(); ?></h3> 
       <em>Posted On: <?php the_time('F j, Y'); ?></em>
       <p><?php echo the_content(); ?></p>

    <?php endwhile; ?>
<?php endif; ?>

<?php wp_reset_postdata(); ?>

This will display those posts which have category ‘tutorial’ and tag ‘plugin’. ‘Tag’ and ‘category_name ’ used here are called parameters. There is a wide variety of parameters list that you can use. The parameters can be author parameter, tag parameter, taxonomy parameter, order parameter and so on. For complete list of the parameters we recommend you check official codex page of WordPress.

Also Read:   How to Create a List of Forbidden Words for WordPress Titles

In the above code we are displaying the title, date and content of the posts using the codes the_title(), the_time() and the_content(). At the end wp_reset_postdata() is used to restore the global $post variable after the secondary loop using new WP_Query.

Now you can explore and use other parameters and display posts with various criteria. This tutorial was the beginners guide on learning WP_Query. I hope it was useful. You can also check our other articles on “How to Add a Custom Sidebar in WordPress.

The following two tabs change content below.

Kantiman Bajracharya

Kantiman Bajracharya is a freelance web developer. He is a computer geek who has a Bachelor’s degree in Computer Engineering. He has earned lots of satisfied customers while working for numerous successful projects. He is also a WordPress theme creator and web article writer. On free time he likes reading philosophy books, traveling and playing chess.

Share This Post