WordPress WP_Query Class

WordPress WP_Query Class consists of various functions that pull data from the WordPress database when we use The Loop in WordPress template files.

As a WordPress developer, we often need to fetch WordPress content (posts, pages, categories etc) based on different parameters. Here, WP_Query plays an important role to write custom queries and display posts as per our requirement. We can pass an array of arguments before Loop, and the $query object will build the SQL query based on those arguments.

WP_Query allows us to perform complex database queries safely because it works with its own instance and does not modify global variables unlike query_posts(). WP_Query and get_posts() are the correct methods when we need to build multiple queries on the same page. This is also useful when we need to query custom posts (such as sliders, services, products etc).

WP_Query Example:

Let us suppose we have registered a News section in WordPress dashboard using custom post types. Now, we want to fetch recent 6 news in any WordPress template file. WP_Query is the best way to achieve this.

We will pass ‘post_type‘ and ‘posts_per_page‘ parameters in WP_Query before WordPress Loop. Inside Loop, we can use template tags to display News Title and News Content. Here is an example.

// Build Query to fetch 6 news post types
$args = array(
    'post_type'   => 'news',
    'posts_per_page' => 6,
$custom_query = new WP_Query( $args );
// The Loop
if ( $custom_query->have_posts() ) {
    while ( $custom_query->have_posts() ) {
} else {
    // no posts found
/* Restore original Post Data */

WP_Query Arguments:

WP_Query supports numerous arguments to fetch WordPress content based on Category, Author, Post Type, Tag, Status, Date, Order etc. Here, you will see examples related to commonly used WP_Query Arguments.

Default parameter values:

There are some default values assigned for the common arguments.

  • posts_per_page – Defaults value is 10 and the number can be changed in the reading settings of posts.
  • post_type – Defaults value is post
  • post_status – Defaults value is publish
  • orderby – Defaults value is date
  • order – Defaults value is DESC

By looking at these parameters, we know that by default WP_Query fetch ‘posts’ type content with ‘publish’ status and latest posts are displayed first. You can change them as per your requirement.

Category Parameters:

You can include or exclude posts based on category id and category name.

Display posts from category id 3, 4 or 6:

$custom_query = new WP_Query( array( 'cat' => '3,5,6' ) );

Display posts from certain category name:

$custom_query = new WP_Query( array( 'category_name' => 'entertainment, sports' ) );

Author Parameters:

You can display posts from certain author id and names.

Display posts from certain author id:

$custom_query = new WP_Query( array( 'author' => '1,4,5' ) );

Display posts from certain author name:

$custom_query = new WP_Query( array( 'author_name' => 'admin, guest, robin' ) );

Post & Page Parameters:

You can use multiple parameters to show particular posts and pages.

Display single post by ID:

$custom_query = new WP_Query( array( 'p' => 2 ) );

Show page by ID:

$custom_query = new WP_Query( array( 'page_id' => 1 ) );

Display post/page by slug:

$custom_query = new WP_Query( array( 'name' => 'contact-us' ) );

Show child pages using parent page ID:

$custom_query = new WP_Query( array( 'post_parent' => 3 ) );

Display pages in draft:

$custom_query = new WP_Query( array( 'post_type' => 'page', 'post_status' => 'draft' ) );

Other commonly used parameters:

Display all posts:

$custom_query = new WP_Query( array( 'posts_per_page'=> -1 ) );

Display WooCommerce products from certain product category:

$custom_query = new WP_Query( array( 'post_type' => 'product', 'posts_per_page' => 10, 'product_cat' => 'hoodies' ) );

However, it is recommended to use WooCommerce functions such as wc_get_products() to fetch products data.

For more details on WP_Query and Parameters, you can read WP_Query documentations.

Congratulations! Chapter Finished. Learn more about the similar topics:
Exercises & Assignments
No Content Found.
Interview Questions & Answers
No Content Found.