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
| Argument | Example | Meaning |
|---|---|---|
| post_type | 'page', array( 'post', 'book' ) | Which content type |
| posts_per_page | 10 | How many posts (-1 for all, use with care) |
| paged | get_query_var( 'paged' ) | Page number for pagination |
| category_name, cat | 'news', 2 | Category by slug or ID |
| tag | 'beginner' | Tag slug |
| author | 1 | Author ID |
| s | 'wordpress' | Search keyword |
| post__in, post__not_in | array( 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: