WordPress WP_Query Class

WP_Query is the class which gets posts from the database. WordPress uses it for the main query, and you can create your own objects of it to show any list of posts: latest posts, posts of a category, featured items or related posts.

A first WP_Query example

Let us make some sample posts, with two categories and a custom field called views:

$query = new WP_Query( array(
	'post_type'      => 'post',
	'category_name'  => 'tutorials',
	'posts_per_page' => 5,
) );

echo 'Found: ' . $query->found_posts . "\n";
if ( $query->have_posts() ) {
	while ( $query->have_posts() ) {
		$query->the_post();
		echo '- ' . get_the_title() . "\n";
	}
}
wp_reset_postdata();
Output

Found: 2
– Learn hooks
– Learn WP_Query

Always call wp_reset_postdata() after your loop, to give the main query back to WordPress.

Common arguments

ArgumentExampleMeaning
post_type'page', array( 'post', 'book' )Which content type
posts_per_page10How many posts (-1 for all, use with care)
pagedget_query_var( 'paged' )Page number for pagination
category_name, cat'news', 2Category by slug or ID
tag'beginner'Tag slug
author1Author ID
s'wordpress'Search keyword
post__in, post__not_inarray( 5, 6 )Include or exclude IDs
orderby, order'date', 'DESC'Sorting
meta_key, meta_value'views'Custom field filter
post_status'publish'Status of the posts

Order by a custom field

$query = new WP_Query( array(
	'meta_key'       => 'views',
	'orderby'        => 'meta_value_num',
	'order'          => 'DESC',
	'posts_per_page' => 3,
) );
foreach ( $query->posts as $p ) {
	echo $p->post_title . ' (' . get_post_meta( $p->ID, 'views', true ) . " views)\n";
}
Output

Learn WP_Query (450 views)
WordPress 7 released (120 views)
Site update (90 views)

Date, meta and taxonomy queries

Use the arrays date_query, meta_query and tax_query for the complex filters:

$query = new WP_Query( array(
	'date_query' => array(
		array( 'after' => '2026-03-02', 'inclusive' => true ),
	),
	'meta_query' => array(
		array( 'key' => 'views', 'value' => 100, 'compare' => '>=', 'type' => 'NUMERIC' ),
	),
	'tax_query'  => array(
		array( 'taxonomy' => 'category', 'field' => 'slug', 'terms' => array( 'tutorials' ) ),
	),
) );
foreach ( $query->posts as $p ) {
	echo $p->post_date . ' | ' . $p->post_title . "\n";
}
echo 'Total: ' . $query->found_posts;
Output

2026-03-02 10:00:00 | Learn WP_Query
Total: 1

Useful properties

  • $query->found_posts: total number of posts which match (all pages).
  • $query->post_count: number of posts on the current page.
  • $query->max_num_pages: total pages, used for pagination.
  • $query->request: the SQL query which WordPress made (good for debugging).

Change the main query: pre_get_posts

Do not use query_posts(). To change the main query, use the pre_get_posts hook:

add_action( 'pre_get_posts', function ( $query ) {
	if ( ! is_admin() && $query->is_main_query() && $query->is_home() ) {
		$query->set( 'posts_per_page', 3 );
	}
} );
Note: Asking for posts_per_page => -1 on a site with thousands of posts is slow. Always limit the number, and use the fields => 'ids' argument if you only need the IDs. Next: Conditional Tags.

Congratulations! Chapter Finished. Learn more about the similar topics:
Exercises & Assignments
Build and activate a minimal classic theme
Show the three latest posts with WP_Query
Load a stylesheet with wp_enqueue_style and a version
Show a message only on the front page
Create a child theme which changes the footer
Interview Questions & Answers
What is a WordPress theme?
What are commonly used WordPress theme functions?
Which function is used to get the home URL in WordPress?
Which are the necessary files for a WordPress theme?
What is the use of the wp_head() function in WordPress?
What is the WordPress Loop?
What is the difference between is_home() and is_front_page()?