do_action_ref_array( 'pre_get_posts', WP_Query $this )

Fires after the query variable object is created, but before the actual query is run.

Contents

Description Description

Note: If using conditional tags, use the method versions within the passed instance (e.g. $this->is_main_query() instead of is_main_query()). This is because the functions like is_main_query() test against the global $wp_query instance, not the passed one.

Parameters Parameters

$this

(WP_Query) The WP_Query instance (passed by reference).

Top ↑

Source Source

File: wp-includes/class-wp-query.php

View on Trac

Top ↑

Changelog Changelog

Changelog
Version Description
2.0.0 Introduced.

Top ↑

More Information More Information

Top ↑

Targeting the right query Targeting the right query

Be aware of the queries you are changing when using the pre_get_posts action. Make use of conditional tags to target the right query. For example, its recommended to use the the is_admin() conditional to not change queries in the admin screens. With the $query->is_main_query() conditional from the query object you can target the main query of a page request. The main query is used by the primary post loop that displays the main content for a post, page or archive. Without these conditionals you could unintentionally be changing the query for custom loops in sidebars, footers, or elsewhere.

Example targeting the main query for category archives:

add_action( 'pre_get_posts', 'target_main_category_query_with_conditional_tags' );

function target_main_category_query_with_conditional_tags( $query ) {

	if ( ! is_admin() && $query->is_main_query() ) {
		// Not a query for an admin page.
		// It's the main query for a front end page of your site.

		if ( is_category() ) {
			// It's the main query for a category archive.

			// Let's change the query for category archives.
			$query->set( 'posts_per_page', 15 );
		}
	}
}

Expand full source codeCollapse full source code

Top ↑

Default main query arguments Default main query arguments

The main query (object) already has some default properties set depending on the page request. For example, for single posts the $query->is_single property is set to true. This means you can’t simply change a single post or page query into an archive of posts query (or the other way around). To achieve this you’ll have to reset these properties in the query object itself. Unless you are intimately familiar with these settings and are willing to coordinate them yourself, it’s suggested that you replace the main query by using WP_Query in the page.php or single.php (child) theme template files.

Top ↑

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
    Contributed by seabluetom — 
    
/**
*
*		The Code below will modify the main WordPress loop, before the queries fired,
*	to only show posts in the halloween category on the home page.
*
*/
	function sbt_exclude_category($query){
		
		if ( $query->is_home() && $query->is_main_query() && ! is_admin() ) {
			
			$query->set( 'category_name', 'halloween' );
		}
	}
	add_action('pre_get_posts','sbt_exclude_category');

    Expand full source codeCollapse full source code

  2. Skip to note 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by saddamcrr7 —

    Example for how to universally adjust queries for an ‘event’ post type:

    function university_adjust_queries($query){
   if ( ! is_admin() && is_post_type_archive( 'event' ) && $query->is_main_query() ) {
        $query->set( 'meta_key', 'event_date' );
        $query->set( 'orderby', 'meta_value_num' );
        $query->set( 'order', 'ASC');
        $query->set( 'meta_query', array(
            array(
                'key'     => 'event_date',
                'compare' => '>=',
                'value'   => date('Ymd'),
                'type'    => 'numeric',
            )
        ) );
   }
}
add_action( 'pre_get_posts', 'university_adjust_queries' );

    Expand full source codeCollapse full source code

You must log in before being able to contribute a note or feedback.