WP_Query retrieves WordPress posts using criteria such as author, category, taxonomy and custom fields. Its parameters let you choose which posts appear and how they are ordered.
The examples below explain common WP_Query parameters and how to combine them.
Author Parameters
With WP_Query, you can query posts based on their associated authors using the following parameters:
author– Accepts a single author ID or a comma-separated list of IDs. To exclude certain authors, prefix their IDs with a minus sign (e.g.,'author' => '-1,-2,-3').author_name– Use the author’s user_nicename (not the display name).author__in– An array of author IDs to include.author__not_in– An array of author IDs to exclude.
$args = array(
'author' => '1,2,3',
'author_name' => 'sajdoko',
'author__in' => array(2, 6),
'author__not_in' => array(2, 6),
);
$the_query = new WP_Query($args);
Category Parameters
To query posts based on categories, WP_Query offers several flexible parameters:
cat– Use the category ID to include or exclude categories. Exclude by prefixing the ID with a minus sign (e.g.,'cat' => '-12,-34,-56').category_name– Use category slugs to filter posts.category__and– Display posts that are in all of the specified categories.category__inandcategory__not_in– Use arrays of category IDs to include or exclude specific categories.
$args = array(
'cat' => '-12,-34,-56',
'category_name' => 'staff, news',
'category__and' => array(2, 6),
);
$the_query = new WP_Query($args);
Tag Parameters
Querying posts by tags is also straightforward in WP_Query:
tag– Use tag slugs to find posts.tag_id– Use a tag’s ID.tag__andandtag__in– Use arrays of tag IDs to include or require all specified tags.tag_slug__andandtag_slug__in– Use arrays of tag slugs to filter posts.
$args = array(
'tag' => 'cooking',
'tag__in' => array(2, 6),
);
$the_query = new WP_Query($args);
Taxonomy Parameters
Taxonomy queries allow you to query posts by custom taxonomies and terms. You can combine multiple taxonomy queries using logical relationships ('AND' or 'OR').
$args = array(
'tax_query' => array(
'relation' => 'AND',
array(
'taxonomy' => 'color',
'field' => 'slug',
'terms' => array('red', 'blue'),
),
array(
'taxonomy' => 'actor',
'field' => 'id',
'terms' => array(103, 115),
'operator' => 'NOT IN',
),
),
);
$the_query = new WP_Query($args);
Post and Page Parameters
WP_Query can also retrieve specific posts or pages using IDs, slugs, or parent-child relationships:
p– Use the post ID to get a specific post.name– Use the post slug.post_parentandpost_parent__in– Use these to query child posts of specific parent posts.
$args = array(
'p' => 1,
'post_parent' => 1,
'post__in' => array(1, 2, 3),
);
$the_query = new WP_Query($args);
Pagination Parameters
Control how many posts appear per page and handle pagination effectively:
posts_per_page– Number of posts to display per page.paged– Current page number.offset– Number of posts to skip.
$args = array(
'posts_per_page' => 10,
'paged' => get_query_var('paged'),
'offset' => 3,
);
$the_query = new WP_Query($args);
Order & Orderby Parameters
Sort posts based on different criteria:
order– Specify'ASC'(ascending) or'DESC'(descending).orderby– Sort by'date','title','rand','meta_value', etc.
$args = array(
'orderby' => 'date',
'order' => 'DESC',
);
$the_query = new WP_Query($args);
Date Parameters
Retrieve posts from specific time periods:
year,monthnum,day– Specify posts from a particular year, month, or day.date_query– Perform complex date queries.
$args = array(
'year' => 2023,
'monthnum' => 9,
'day' => 23,
);
$the_query = new WP_Query($args);
Conclusion
As you can see, WP_Query is an incredibly versatile class that lets you query posts in countless ways. Whether you need to fetch posts by author, category, custom taxonomy, or even specific custom fields, WP_Query can do the job.
Once you get comfortable with these parameters, you’ll be able to customize your WordPress queries to suit any project needs. Don’t forget to check the official WP_Query documentation for even more examples and details.
Have any questions or custom queries you’re struggling with? Drop a comment below, and I’ll be happy to help!