Table of contents
What is the WordPress wp_query?How to use wp_queryWP_Query vs query_posts()Examples of wp_query usesGetting started
Get the industry’s fastest WordPress hosting◦ 99.999% uptime
◦ Comprehensive security
◦ 24/7 support
Explore options

WordPress Guide → Database → wp_query

WordPress wp_query and how to use it (with examples)

A young man in glasses working on building a hosted WooCommerce store, a computer at a desk behind him shows computer code

Want more control over the content you display in WordPress? There’s a powerful tool built into core that developers rely on constantly—but it doesn’t always get the spotlight it deserves.

If you’re ready to move past default loops and create custom queries tailored to your content, this is the tool you need to know.

Get fast, reliable hosting for WordPress

Power your site with the industry’s fastest, most optimized WordPress hosting

WordPress.org hosting

What is the WordPress wp_query?

WP_Query is a PHP class that lets you write custom queries to retrieve posts, pages, and other post types from the WordPress database. It’s how you can tell WordPress, “Hey, give me all posts from the ‘News’ category,” or “Show only three products with a custom taxonomy.” Instead of relying on the default query that WordPress loads based on the page or template, WP_Query lets you write your own.

This class gives you full control over what content shows up and how. You can filter by category, tag, author, custom fields, post type, and much more. It’s used throughout themes and plugins to customize the WordPress Loop and output dynamic content.

How to use wp_query

To use WP_Query, you create a new query object with your desired parameters and then loop through the results. Here’s how:

1. Set your query parameters
Use an array to define what posts you want. For example, [‘category_name’ => ‘news’] to grab posts from the “news” category.

2. Create a new WP_Query instance
Instantiate the class with your parameters:

$query = new WP_Query( $args );

3. Loop through the results
Use a standard WordPress loop to display content:

if ( $query->have_posts() ) {

    while ( $query->have_posts() ) {

        $query->the_post();

        // your template tags here

    }

    wp_reset_postdata();

}

4. Reset post data
 Always call wp_reset_postdata() after the custom loop to avoid interfering with other queries on the page.

WP_Query vs query_posts()

query_posts() modifies the main query directly, which can break pagination and cause unexpected side effects. It’s meant for very specific use cases but is generally discouraged.

WP_Query, on the other hand, creates a brand-new query object. This is the preferred and safest method for custom queries because it leaves the global $wp_query untouched and doesn’t interfere with the main loop.

Bottom line: Use WP_Query for custom loops, and avoid query_posts() unless you really know what you’re doing.

Examples of wp_query uses

Here are some practical use cases where WP_Query shines:

1. Show recent posts from a specific category

$args = [‘category_name’ => ‘news’, ‘posts_per_page’ => 5];
$query = new WP_Query( $args );

2. Display custom post types (e.g., “event”)

$args = [‘post_type’ => ‘event’, ‘posts_per_page’ => 10];
$query = new WP_Query( $args );

3. Query by custom field (meta key)

$args = [
    ‘meta_key’ => ‘featured’,
    ‘meta_value’ => ‘yes’
];
$query = new WP_Query( $args );

4. Pull posts by tag or author

$args = [‘tag’ => ‘interview’, ‘author’ => 3];
$query = new WP_Query( $args );

Each of these queries lets you tailor your site’s output to match your design and user experience goals without relying on plugins or rigid templates.

Ready to get started?

Get the fastest, most secure WordPress.org hosting on the market.

All WordPress hosting