Contents
Introduction — What the loop is and why you might override it
WordPresss Loop is the engine that processes and displays posts for the main query in templates. By default the main query is created by WP core using URL parameters, the template hierarchy, and rules. There are many cases where you need a different set of posts in a template: a custom archive, a homepage layout with mixed post types, a related-posts block, a widget, or a custom pagination scheme. The recommended, robust way to get custom collections of posts in templates is WP_Query. This article explains every practical detail about overriding the Loop with WP_Query in a PHP template, plus best practices, pitfalls, performance considerations, security tips and multiple real-world examples.
When to use WP_Query vs pre_get_posts vs query_posts
- WP_Query — Use when you want a custom, secondary query or when you want to run and control a completely separate loop inside a template. It returns a new object without mutating the global main query.
- pre_get_posts — The best place to modify the main query before WordPress runs it. If you need to change which posts appear for archives, home, search, etc., prefer pre_get_posts in functions.php — it avoids replacing globals in templates and maintains pagination integrity.
- query_posts — Avoid. It replaces the global query in a heavy-handed way and causes subtle bugs with pagination and performance. It’s essentially deprecated for template use.
Core concepts you must understand
- have_posts() / the_post() — The Loop control functions that advance the current WP_Query object.
- global wp_query — The main query object used by template tags and pagination functions by default. If you completely replace it, be sure to restore the original object or adjust calls that rely on it.
- wp_reset_postdata() — Use after custom WP_Query loops to restore global post and related template tags to the state expected by the main query. This is essential for nested loops.
- wp_reset_query() — Restores global wp_query and global post. Typically only necessary if you used query_posts or you swapped the global query object yourself.
- pagination — When paginating a custom WP_Query you must pass the correct paged parameter and use functions that read the object’s max_num_pages (e.g., paginate_links with custom_query->max_num_pages). If you replace global wp_query, some helpers may work automatically, but careful restoration is required.
Basic WP_Query usage (simple custom loop)
Standard pattern for a secondary loop in a template file. Important steps: instantiate WP_Query, run the loop, and then call wp_reset_postdata().
lt?php
args = array(
post_type =gt post,
posts_per_page =gt 5,
orderby =gt date,
order =gt DESC,
)
custom_query = new WP_Query( args )
if ( custom_query-gthave_posts() ) :
while ( custom_query-gthave_posts() ) : custom_query-gtthe_post()
// Template tags work here: the_title(), the_content(), get_permalink(), etc.
?gt
lth2gtlta href=lt?php echo esc_url( get_permalink() ) ?gtgtlt?php the_title() ?gtlt/agtlt/h2gt
lt?php
endwhile
// Pagination or other UI can use custom_query-gtmax_num_pages
else :
echo ltpgtNo posts found.lt/pgt
endif
// Restore global post data (very important)
wp_reset_postdata()
?gt
Why wp_reset_postdata() is required
the_post() sets up global post, global more and internal pointers. If you dont restore the original post with wp_reset_postdata(), template tags after the custom loop will reference the last post from your custom query instead of the main querys post.
Replacing the main Loop with WP_Query (swap global)
Sometimes you intentionally want to override the main loop used by the template (for example a page that normally shows the latest posts but you want a custom selection while still keeping template compatibility with functions that read global wp_query). You have two better options:
- Use pre_get_posts to alter the main query before WordPress runs it. This is the preferred method.
- If you must replace the global query in the template, you can swap the global wp_query and wp_the_query temporarily. After the loop, restore them.
Example of swapping globals inside a template:
lt?php
// Save originals
global wp_query, wp_the_query
original_query = wp_query
original_the_query = wp_the_query
// Build a custom query to act as the main query for the template
custom_args = array(
post_type =gt array( post, project ),
posts_per_page =gt 10,
paged =gt max( 1, get_query_var( paged ) ),
)
wp_query = new WP_Query( custom_args )
wp_the_query = wp_query // some template helpers read wp_the_query
if ( have_posts() ) :
while ( have_posts() ) : the_post()
// This acts like the main loop now.
the_title( lth2gt, lt/h2gt )
the_excerpt()
endwhile
// Example pagination that depends on wp_query:
the_posts_pagination()
else :
echo ltpgtNo posts found.lt/pgt
endif
// Clean up: restore the original main query
wp_query = original_query
wp_the_query = original_the_query
wp_reset_postdata()
?gt
Notes: this approach should be used conservatively. Replacing the global main query can cause theme or plugin functions that expect the original main query to behave differently. Prefer pre_get_posts if you can.
Modifying the main query using pre_get_posts (recommended)
pre_get_posts gives you a clean, performance-friendly method to alter the main query before its executed. Use conditional checks to avoid affecting admin queries and REST API calls.
lt?php
// place in functions.php or a plugin
function my_modify_main_query( query ) {
if ( is_admin() ! query-gtis_main_query() ) {
return
}
// Example: modify home page list
if ( query-gtis_home() ) {
query-gtset( posts_per_page, 8 )
query-gtset( post_type, array( post, news ) )
// add tax_query or meta_query as needed
}
}
add_action( pre_get_posts, my_modify_main_query )
?gt
Why pre_get_posts is preferable for main-query changes
- It runs before WP executes the SQL, maintaining proper pagination and global variables.
- It avoids monkey-patching global variables in templates.
- It is the canonical, documented approach to alter the main query safely.
Advanced WP_Query parameters and examples
Common arguments and advanced features you will use often:
- post_type — post, page, custom post type name, or array of types.
- posts_per_page — number of posts -1 for all (beware memory).
- paged — required for pagination use max( 1, get_query_var(paged) ).
— date, title, meta_value_num, rand, or array syntax. - meta_query — build complex queries by meta key / value conditions.
- tax_query — filter by categories, tags or custom taxonomies.
- offset — skip N posts combined with pagination requires careful math.
- no_found_rows — set to true to skip SQL_CALC_FOUND_ROWS and speed up queries when you dont need pagination.
- fields — ids or id=>parent to return smaller result sets for performance-sensitive code.
Complex example: meta_query tax_query ordering by meta value
lt?php
paged = max( 1, absint( get_query_var( paged ) ) )
args = array(
post_type =gt product,
posts_per_page =gt 12,
paged =gt paged,
meta_key =gt _price,
orderby =gt meta_value_num,
order =gt ASC,
meta_query =gt array(
relation =gt AND,
array(
key =gt _stock_status,
value =gt instock,
compare =gt =,
),
array(
key =gt _featured,
value =gt 1,
compare =gt =,
),
),
tax_query => array(
array(
taxonomy =gt product_cat,
field =gt slug,
terms =gt array( clothing, accessories ),
operator =gt IN,
),
),
)
products = new WP_Query( args )
if ( products-gthave_posts() ) {
while ( products-gthave_posts() ) {
products-gtthe_post()
// product template partial
}
// paginate using products-gtmax_num_pages
}
wp_reset_postdata()
?gt
Pagination with a custom WP_Query
To achieve correct pagination you must pass the right paged argument and use the query objects max_num_pages for building pagination links.
lt?php
paged = max( 1, absint( get_query_var( paged ) ) )
args = array(
post_type =gt post,
posts_per_page =gt 6,
paged =gt paged,
)
custom = new WP_Query( args )
if ( custom-gthave_posts() ) :
while ( custom-gthave_posts() ) : custom-gtthe_post()
the_title( lth3gt, lt/h3gt )
endwhile
big = 999999999 // need an unlikely integer
echo paginate_links( array(
base =gt str_replace( big, %#%, esc_url( get_pagenum_link( big ) ) ),
format =gt ?paged=%#%,
current =gt paged,
total =gt custom-gtmax_num_pages,
prev_text =gt lt,
next_text =gt gt,
) )
endif
wp_reset_postdata()
?gt
Front page vs static front page pagination note
If your site uses a static front page, get_query_var(paged) may return 0 and you might need to check both paged and page query vars depending on the context (main query on front page uses page). A robust approach:
lt?php paged = max( 1, get_query_var( paged ), get_query_var( page ) ) ?gt
Offset with pagination — the tricky bit
Using an offset with paged queries breaks the default pagination calculation. If you need an offset and paged results you must manually compute the offset or use separate queries for the first page. Example pattern: display N sticky/featured posts at top and then run a paged query excluding those posts (or use offset with a custom calculation).
lt?php // Example: show 3 pinned posts, then a paged listing excluding them pinned_ids = array( 12, 34, 56 ) // discovered earlier with a separate query or logic // Show pinned pin_args = array( post__in =gt pinned_ids, orderby =gt post__in, posts_per_page =gt -1, ) pin_query = new WP_Query( pin_args ) // display pinned posts... wp_reset_postdata() // Now a paged query that excludes pinned IDs paged = max( 1, absint( get_query_var( paged ) ) ) main_args = array( post__not_in =gt pinned_ids, posts_per_page =gt 10, paged =gt paged, ) main_query = new WP_Query( main_args ) // paged loop... wp_reset_postdata() ?gt
Performance considerations and speed tips
- Use no_found_rows =gt true when you do not need pagination. This avoids an expensive COUNT() query.
- Use fields =gt ids to fetch only post IDs when you only need IDs for further processing.
- Index your custom meta keys used in meta_query where possible (external DB tuning required) meta queries are slower than taxonomy queries.
- Caching: use object caching for expensive repeated queries. Transients are useful for caching calculated query outputs.
- Limit posts_per_page avoid -1 on large sites where results can be huge.
- Avoid returning large resultsets to PHP for processing — let SQL filter as much as possible.
Security and sanitization
- Never pass unsanitized user input into WP_Query arguments without validation/sanitization — especially meta queries and taxonomy slugs. Use absint() for numeric values like paged, posts_per_page, and sanitize_text_field() for text input before using in a query.
- Escape output when rendering template tags: esc_html(), esc_attr(), esc_url() as appropriate.
- When building URLs for pagination use esc_url() / get_pagenum_link() helpers.
Common mistakes and how to avoid them
- Forgetting wp_reset_postdata() when using a custom WP_Query. Symptoms: template tags show wrong post data after loop.
- Using query_posts() instead of pre_get_posts or WP_Query. Symptoms: broken pagination, unexpected results, performance issues.
- Not passing paged for paginated custom queries. Symptoms: page 2 shows same results as page 1 or 404s.
- Using offset with paged but not adjusting the pager math. Symptoms: incorrect results, missing items on pages.
- Not checking is_main_query() inside pre_get_posts and accidentally modifying admin queries or REST queries.
get_posts vs WP_Query
get_posts() is a wrapper for WP_Query that returns an array of posts and sets suppress_filters =gt true by default. It is convenient for short tasks and will not set up global post data (you get raw post objects). If you need loop template functions or pagination, prefer WP_Query.
Sticky posts handling
WP_Query respects sticky posts by default on the home/blog index. To ignore sticky posts, set ignore_sticky_posts =gt true. To manually place sticky posts at the top, query them separately and then exclude them from the main query.
Examples: real-world templates
Example 1 — A homepage template replacing the default loop using pre_get_posts (recommended)
lt?php
// functions.php
function my_homepage_query( query ) {
if ( query-gtis_home() query-gtis_main_query() ! is_admin() ) {
query-gtset( posts_per_page, 8 )
query-gtset( post_type, array( post, news ) )
query-gtset( meta_key, _homepage_priority )
query-gtset( orderby, meta_value_num )
query-gtset( order, DESC )
}
}
add_action( pre_get_posts, my_homepage_query )
?gt
Example 2 — Template with two loops: featured and paged list
lt?php
// In a template file
// 1) Featured posts (non-paged)
featured = new WP_Query( array(
post_type =gt post,
posts_per_page =gt 3,
meta_key =gt _is_featured,
meta_value =gt 1,
) )
if ( featured-gthave_posts() ) {
echo ltsection class=featuredgt
while ( featured-gthave_posts() ) {
featured-gtthe_post()
the_title( lth2gt, lt/h2gt )
}
echo lt/sectiongt
}
wp_reset_postdata()
// 2) Main paged list excluding featured
featured_ids = wp_list_pluck( featured-gtposts, ID )
paged = max( 1, absint( get_query_var( paged ) ) )
main = new WP_Query( array(
post__not_in =gt featured_ids,
posts_per_page =gt 10,
paged =gt paged,
) )
if ( main-gthave_posts() ) {
while ( main-gthave_posts() ) {
main-gtthe_post()
the_title( lth3gt, lt/h3gt )
}
// paginate using main-gtmax_num_pages...
}
wp_reset_postdata()
?gt
Troubleshooting checklist
- Is your custom query using the correct paged value? Confirm with var_dump if needed.
- Did you call wp_reset_postdata() after the custom loop?
- Are you using query_posts anywhere? Replace it with pre_get_posts or WP_Query.
- If pagination fails, are you modifying the main query late in the load (use pre_get_posts instead)?
- Are you inadvertently running filters that change SQL? Check suppress_filters or plugin filters.
- Are you returning huge result sets (posts_per_page =gt -1)? That may cause memory/timeouts.
Further references
Official documentation and reference is indispensable for checking every available argument and behavior: WP_Query reference and pre_get_posts hook.
Final best-practices summary
- Prefer pre_get_posts for altering the main query.
- Use WP_Query for secondary or isolated loops always run wp_reset_postdata() afterwards.
- Pass paged for paginated queries and use query-gtmax_num_pages for pagination links.
- Avoid query_posts it is not recommended.
- Sanitize inputs, escape outputs, and use performance flags like no_found_rows and fields when appropriate.
- Test for sticky posts, offsets and front-page page vs paged differences.
With the concepts, code patterns and edge-case notes provided here you can confidently override the Loop using WP_Query in templates while maintaining WordPresss expectations for pagination, template tags and plugin compatibility.
|
|
Acepto donaciones de BAT's mediante el navegador Brave 🙂 |