Title: query_posts Published: April 25, 2014 Last modified: February 24, 2026 --- # query_posts( array|string $query ): 󠀁[WP_Post](https://developer.wordpress.org/reference/classes/wp_post/)󠁿[]|int[] ## In this article * [Description](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#description) * [Parameters](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#parameters) * [Return](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#return) * [More Information](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#more-information) * [Usage](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#usage) - [Preserving Existing Query Parameters](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#preserving-existing-query-parameters) - [Combining Parameters](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#combining-parameters) * [Caveats](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#caveats) - [Alters Main Loop](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#alters-main-loop) - [Secondary Loops](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#secondary-loops) - [Pagination](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#pagination) - [Additional SQL Queries](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#additional-sql-queries) * [Resources](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#resources) * [Source](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#source) * [Related](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#related) * [Changelog](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#changelog) * [User Contributed Notes](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#user-contributed-notes) [ Back to top](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#wp--skip-link--target) Sets up The Loop with query parameters. ## 󠀁[Description](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#description)󠁿 Note: This function will completely override the main query and isn’t intended for use by plugins or themes. Its overly-simplistic approach to modifying the main query can be problematic and should be avoided wherever possible. In most cases, there are better, more performant options for modifying the main query such as via the [‘pre_get_posts’](https://developer.wordpress.org/reference/hooks/pre_get_posts/) action within [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/). This must not be used within the WordPress Loop. ## 󠀁[Parameters](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#parameters)󠁿 `$query`array|stringrequired Array or string of [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/) arguments. ## 󠀁[Return](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#return)󠁿 [WP_Post](https://developer.wordpress.org/reference/classes/wp_post/)[]|int[] Array of post objects or post IDs. ## 󠀁[More Information](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#more-information)󠁿 [⌊Flowchart illustrating why query_posts() should be avoided⌉⌊Flowchart illustrating why query_posts() should be avoided⌉[ Credit: Andrey Savchenko (rarst.net) / CC-By-SA. [query_posts()](https://developer.wordpress.org/reference/functions/query_posts/) is a way to alter the main query that WordPress uses to display posts. It does this by putting the main query to one side, and replacing it with a new query. To clean up after a call to query_posts, make a call to [wp_reset_query()](https://developer.wordpress.org/reference/functions/wp_reset_query/), and the original main query will be restored. It should be noted that using this to replace the main query on a page can increase page loading times, in worst case scenarios more than doubling the amount of work needed or more. While easy to use, the function is also prone to confusion and problems later on. See the note further below on caveats for details. For general post queries, use [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/) or [get_posts()](https://developer.wordpress.org/reference/functions/get_posts/). It is **_strongly_** recommended that you use the ‘pre_get_posts’ action instead, and alter the main query by checking [is_main_query()](https://developer.wordpress.org/reference/functions/is_main_query/). For example, on the homepage, you would normally see the latest 10 posts. If you want to show only 5 posts (and don’t care about pagination), you can use [query_posts()](https://developer.wordpress.org/reference/functions/query_posts/) like so: ```php query_posts( 'posts_per_page=5' ); ``` Here is similar code using the ‘pre_get_posts’ action in functions.php : ```php function wpdocs_five_posts_on_homepage( $query ) { if ( $query->is_home() && $query->is_main_query() ) { $query->set( 'posts_per_page', 5 ); } } add_action( 'pre_get_posts', 'wpdocs_five_posts_on_homepage' ); ``` ## 󠀁[Usage](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#usage)󠁿 ```php // The Query query_posts( $args ); // The Loop while ( have_posts() ) : the_post(); echo '
  • '; the_title(); echo '
    • '; endwhile; // Reset Query wp_reset_query(); ``` Place a call to [query_posts()](https://developer.wordpress.org/reference/functions/query_posts/) in one of your [Template](https://codex.wordpress.org/Templates) files before [The Loop](https://codex.wordpress.org/The Loop) begins. The [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/) object will generate a new SQL query using your parameters. When you do this, WordPress ignores the other parameters it receives via the URL (such as page number or category). ### 󠀁[Preserving Existing Query Parameters](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#preserving-existing-query-parameters)󠁿 If you want to preserve the original query parameter information that was used to generate the current query, and then add or over-ride some parameters, you can use the **$query_string** global variable in the call to [query_posts()](https://developer.wordpress.org/reference/functions/query_posts/). For example, to set the display order of the posts without affecting the rest of the query string, you could place the following before [The Loop](https://codex.wordpress.org/The Loop): ```php global $query_string; query_posts( $query_string . '&order=ASC' ); ``` When using [query_posts()](https://developer.wordpress.org/reference/functions/query_posts/) in this way, the quoted portion of the parameter _must_ begin with an ampersand (&). Or alternatively, you can merge the original query array into your parameter array: ```php global $wp_query; $args = array_merge( $wp_query->query_vars, array( 'post_type' => 'product' ) ); query_posts( $args ); ``` ### 󠀁[Combining Parameters](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#combining-parameters)󠁿 You may have noticed from some of the examples above that you combine parameters with an ampersand (&), like so: ```php query_posts( 'cat=3&year=2004' ); ``` Posts for category 13, for the current month on the main page: ```php if ( is_home() ) { query_posts( $query_string . '&cat=13&monthnum=' . date( 'n', current_time( 'timestamp' ) ) ); } ``` At 2.3 this combination will return posts belong to both Category 1 AND 3, showing just two (2) posts, in descending order by the title: ```php query_posts( array( 'category__and' => array(1,3), 'posts_per_page' => 2, 'orderby' => 'title', 'order' => 'DESC' ) ); ``` The following returns all posts that belong to category 1 and are tagged “apples”. ```php query_posts( 'cat=1&tag=apples' ); ``` You can search for several tags using “+”. In this case, all posts belong to category 1 and tagged as “apples” and “oranges” are returned. ```php query_posts( 'cat=1&tag=apples+oranges' ); ``` ## 󠀁[Caveats](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#caveats)󠁿 [query_posts()](https://developer.wordpress.org/reference/functions/query_posts/) is only one way amongst many to query the database and generate a list of posts. Before deciding to use [query_posts()](https://developer.wordpress.org/reference/functions/query_posts/), be sure to understand the drawbacks. ### 󠀁[Alters Main Loop](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#alters-main-loop)󠁿 [query_posts()](https://developer.wordpress.org/reference/functions/query_posts/) is meant for altering the main loop. It does so by replacing the query used to generate the main loop content. Once you use [query_posts()](https://developer.wordpress.org/reference/functions/query_posts/), your post-related global variables and template tags will be altered. Conditional tags that are called after you call [query_posts()](https://developer.wordpress.org/reference/functions/query_posts/) will also be altered – this may or may not be the intended result. ### 󠀁[Secondary Loops](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#secondary-loops)󠁿 To create secondary listings (for example, a list of related posts at the bottom of the page, or a list of links in a sidebar widget), try making a new instance of [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/) or use [get_posts()](https://developer.wordpress.org/reference/functions/get_posts/) . If you must use [query_posts()](https://developer.wordpress.org/reference/functions/query_posts/), make sure you call [wp_reset_query()](https://developer.wordpress.org/reference/functions/wp_reset_query/) after you’re done. ### 󠀁[Pagination](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#pagination)󠁿 Pagination won’t work correctly, unless you set the ‘paged’ query var appropriately: [adding the paged parameter](https://codex.wordpress.org/Pagination#Adding_the_.22paged.22_parameter_to_a_query) ### 󠀁[Additional SQL Queries](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#additional-sql-queries)󠁿 If you use query_posts within a template page, WordPress will have already executed the database query and retrieved the records by the time it gets to your template page (that’s how it knew which template page to serve up!). So when you over-ride the default query with [query_posts()](https://developer.wordpress.org/reference/functions/query_posts/), you’re essentially throwing away the default query and its results and re-executing another query against the database. This is not necessarily a problem, especially if you’re dealing with a smaller blog- based site. Developers of large sites with big databases and heavy visitor traffic may wish to consider alternatives, such as modifying the default request directly( before it’s called). The ‘request’ filter can be used to achieve exactly this. The ‘parse_query’ and the ‘pre_get_posts’ filters are also available to modify the internal `$query` object that is used to generate the SQL to query the database. ## 󠀁[Resources](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#resources)󠁿 * For more in-depth discussion of how WordPress generates and handles its queries, review these articles: [Query Overview](https://codex.wordpress.org/Query_Overview) and [Custom Queries](https://codex.wordpress.org/Custom_Queries) * Customize the Default Query properly using ‘pre_get_posts’ – [Bill Erickson – Customize the WordPress Query](http://www.billerickson.net/customize-the-wordpress-query/#example-category) or [John James Jacoby – Querying Posts Without query_posts](http://developer.wordpress.com/2012/05/14/querying-posts-without-query_posts/) * You don’t know Query [– Slides from WordCamp Netherlands 2012 by Andrew Nacin](http://www.slideshare.net/andrewnacin/you-dont-know-query-wordcamp-netherlands-2012) ## 󠀁[Source](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#source)󠁿 ```php function query_posts( $query ) { $GLOBALS['wp_query'] = new WP_Query(); return $GLOBALS['wp_query']->query( $query ); } ``` [View all references](https://developer.wordpress.org/reference/files/wp-includes/query.php/) [View on Trac](https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-includes/query.php#L97) [View on GitHub](https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-includes/query.php#L97-L100) ## 󠀁[Related](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#related)󠁿 | Uses | Description | | [WP_Query::__construct()](https://developer.wordpress.org/reference/classes/wp_query/__construct/)`wp-includes/class-wp-query.php` | Constructor. | ## 󠀁[Changelog](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#changelog)󠁿 | Version | Description | | [1.5.0](https://developer.wordpress.org/reference/since/1.5.0/) | Introduced. | ## 󠀁[User Contributed Notes](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#user-contributed-notes)󠁿 1. [Skip to note 5 content](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#comment-content-379) 2. [Codex](https://profiles.wordpress.org/codex/) [ 11 years ago ](https://developer.wordpress.org/reference/functions/query_posts/#comment-379) 3. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fquery_posts%2F%23comment-379) Vote results for this note: 2[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fquery_posts%2F%23comment-379) 4. **Override the main query with all posts in a specific category** The “Blog pages show at most” parameter in `Settings > Reading` can influence your results. To overcome this, add the `posts_per_page` parameter. For example: 5. ```php query_posts( array( 'category_name' => 'my-category-slug', 'posts_per_page' => -1 ) ); ``` 6. This will return ALL posts from the category. If you have a lot of posts (see: thousands), using a realistically high number instead of -1 for performance reasons. 7. However, for subcategories (or child categories), `category_name` doesn’t always work. Rather use `category-slug` instead. See [is_category()](https://developer.wordpress.org/reference/functions/is_category/). 8. ```php if ( is_category( 'category-slug' ) ) : query_posts( array( 'category_name' => 'my-category-slug', 'posts_per_page' => -1 ) ); endif; ``` 9. The same precautions apply when using -1. 10. * It appears you’re using PHP code to modify the WordPress query based on a specific category slug. However, using query_posts is not recommended, as it can interfere with the main query and cause unexpected issues. A more modern and recommended approach is to use the pre_get_posts action hook to modify the main query before it is executed. Here’s an example: function custom_category_query( $query ){ if ( is_category( ‘my-category-slug’ ) && $query->is_main_query() ) { $query- >set( ‘posts_per_page’, -1 ); } } add_action( ‘pre_get_posts’, ‘custom_category_query’);} add_action( ‘pre_get_posts’, ‘custom_category_query’ ); This code checks if the current query is the main query and if the category being viewed is ‘my- category-slug’. If both conditions are met, it sets the posts_per_page parameter to -1, which means all posts will be displayed. Remember to replace ‘[my-category-slug](https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=68&ved=0CGsQFjAHODw&url=https://targeted-visitors.com/product/buy-organic-traffic&ei=Lm5YUoCgF4fJrAeMhICQBg&usg=AFQjCNHHQg4e0Uknr2fbGSCGhWUYS7F4Lw&sig2=UkuqTXVPTksD1dED_3Bl_w&bvm=bv.53899372,d.bmk&cad=rja)‘ with your actual category slug. Always test any code modifications on a staging site before implementing them on a live site to avoid unintended consequences. * [james MORANIZ](https://profiles.wordpress.org/james4r564/) [2 years ago](https://developer.wordpress.org/reference/functions/query_posts/#comment-6888) 11. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fquery_posts%2F%3Freplytocom%3D379%23feedback-editor-379) 12. [Skip to note 6 content](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#comment-content-381) 13. [Codex](https://profiles.wordpress.org/codex/) [ 11 years ago ](https://developer.wordpress.org/reference/functions/query_posts/#comment-381) 14. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fquery_posts%2F%23comment-381) Vote results for this note: 1[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fquery_posts%2F%23comment-381) 15. **Passing variables to query_posts** You can pass a variable to the query with several methods, depending on your needs. As with other examples, place these above your Loop: 16. _Example 1_ 17. In this example, we concatenate the query before running it. First assign the variable, then concatenate and then run it. Here we’re pulling in a category variable from elsewhere. 18. ```php // assign the variable as current category $categoryvariable = $cat; // concatenate the query $args = 'cat=' . $categoryvariable . '&orderby=date&order=ASC'; // run the query query_posts( $args ); ``` 19. _Example 2_ 20. In this next example, the double quotes tell PHP to treat the enclosed as an expression. For this example, we are getting the current month and the current year, and telling` query_posts()` to bring us the posts for the current month/year, and in this case, listing in ascending order so we get the oldest post at the top of the page. 21. ```php $current_year = date('Y'); $current_month = date('m'); query_posts( "cat=22&year=$current_year&monthnum=$current_month&order=ASC" ); ``` 22. _Example 3_ 23. This example explains how to generate a complete list of posts, dealing with pagination. We can use the default `$query_string` telling `query_posts()` to bring us a full posts listing. We can also modify the `posts_per_page` query parameter from -1 to the number of posts you want to show on each page; in this last case, you’ll probably want to use `posts_nav_link()` to navigate the generated archive. 24. ```php query_posts( $query_string . '&posts_per_page=-1' ); ``` 25. _Example 4_ 26. If you don’t need to use the `$query_string` variable, another method exists that is more clear and readable, in some more complex cases. This method puts the parameters into an array. The same query as in Example 2 above could be done like this: 27. ```php $args = array( 'cat' => 22, 'year' => $current_year, 'monthnum' => $current_month, 'order' => 'ASC' ); query_posts( $args ); ``` 28. As you can see, with this approach, every variable can be put on its own line, for easier reading. 29. _Example 5_ 30. It is even possible to use the array style (Example 4) to query multiple taxonomies. Simply supply the taxonomy slug with a string of comma-separated values (each value being one term). In the example below, we will get all movie posts starring either Bruce Campbell _or_ Chuck Norris. 31. ```php $args = array( 'post_type'=> 'movie', 'actor' => 'Bruce Campbell, Chuck Norris', 'order' => 'ASC' ); query_posts( $args ); ``` 32. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fquery_posts%2F%3Freplytocom%3D381%23feedback-editor-381) 33. [Skip to note 7 content](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#comment-content-377) 34. [Codex](https://profiles.wordpress.org/codex/) [ 11 years ago ](https://developer.wordpress.org/reference/functions/query_posts/#comment-377) 35. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fquery_posts%2F%23comment-377) Vote results for this note: 0[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fquery_posts%2F%23comment-377) 36. **Exclude Categories From Your Home Page** Placing this code in `index.php` file will cause the home page to display posts from all categories _except_ category ID 3. 37. ```php if ( is_home() ) { query_posts( 'cat=-3' ); } ``` 38. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fquery_posts%2F%3Freplytocom%3D377%23feedback-editor-377) 39. [Skip to note 8 content](https://developer.wordpress.org/reference/functions/query_posts/?output_format=md#comment-content-32) 40. [Siobhan](https://profiles.wordpress.org/siobhan/) [ 12 years ago ](https://developer.wordpress.org/reference/functions/query_posts/#comment-32) 41. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fquery_posts%2F%23comment-32) Vote results for this note: -2[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fquery_posts%2F%23comment-32) 42. ```php // assign the variable as current category $categoryvariable = $cat; // concatenate the query $args = 'cat=' . $categoryvariable . '&orderby=date&order=ASC'; // run the query query_posts( $args ); ``` 43. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fquery_posts%2F%3Freplytocom%3D32%23feedback-editor-32) You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fquery_posts%2F) before being able to contribute a note or feedback.