How to Use WP_Query in WordPress: Syntax and Examples

Use WP_Query in WordPress to create custom queries for posts by passing an array of parameters to its constructor. Then loop through the results with have_posts() and the_post() to display the posts as needed.

Syntax

The WP_Query class is used to fetch posts based on parameters you specify. You create a new instance by passing an array of query arguments. Then you use a loop to check if posts exist and display them.

• Arguments array: Defines filters like post type, category, number of posts.
• have_posts(): Checks if there are posts to show.
• the_post(): Sets up post data for template tags.

php

<?php
$args = [
    'post_type' => 'post',
    'posts_per_page' => 5,
    'category_name' => 'news'
];
$query = new WP_Query($args);

if ($query->have_posts()) {
    while ($query->have_posts()) {
        $query->the_post();
        // Display post content here
    }
    wp_reset_postdata();
} else {
    // No posts found
}
?>

Example

This example fetches the latest 3 posts from the 'news' category and displays their titles and excerpts.

php

<?php
$args = [
    'post_type' => 'post',
    'posts_per_page' => 3,
    'category_name' => 'news'
];
$query = new WP_Query($args);

if ($query->have_posts()) {
    echo '<ul>';
    while ($query->have_posts()) {
        $query->the_post();
        echo '<li><a href="' . get_permalink() . '">' . get_the_title() . '</a><br>';
        echo get_the_excerpt() . '</li>';
    }
    echo '</ul>';
    wp_reset_postdata();
} else {
    echo 'No news posts found.';
}
?>

Output

<ul><li><a href="https://example.com/news-post-1">News Post 1</a><br>This is the excerpt of news post 1.</li><li><a href="https://example.com/news-post-2">News Post 2</a><br>This is the excerpt of news post 2.</li><li><a href="https://example.com/news-post-3">News Post 3</a><br>This is the excerpt of news post 3.</li></ul>

Common Pitfalls

Common mistakes when using WP_Query include:

• Not calling wp_reset_postdata() after the loop, which can break other queries or template tags.
• Using query_posts() instead of WP_Query, which is discouraged.
• Forgetting to check have_posts() before looping.
• Passing incorrect or unsupported query parameters.

php

<?php
// Wrong way: missing wp_reset_postdata()
$query = new WP_Query(['posts_per_page' => 2]);
if ($query->have_posts()) {
    while ($query->have_posts()) {
        $query->the_post();
        the_title();
    }
}
// This can cause issues with other loops

// Right way:
$query = new WP_Query(['posts_per_page' => 2]);
if ($query->have_posts()) {
    while ($query->have_posts()) {
        $query->the_post();
        the_title();
    }
    wp_reset_postdata();
}
?>

Quick Reference

Here is a quick reference for common WP_Query parameters:

Parameter	Description	Example Value
post_type	Type of content to query	'post', 'page', 'custom_post_type'
posts_per_page	Number of posts to return	5, -1 (all posts)
category_name	Category slug to filter posts	'news', 'events'
orderby	Field to order posts by	'date', 'title', 'rand'
order	Order direction	'ASC' or 'DESC'

Key Takeaways

Create a new WP_Query with an array of parameters to fetch posts.

Always use have_posts() and the_post() in a loop to access posts.

Call wp_reset_postdata() after your custom loop to avoid conflicts.

Use correct query parameters to get the desired posts.

Avoid using query_posts() as it can cause unexpected behavior.