is_main_query()

Determines whether the query is the main query.


Description

For more information on this and similar theme functions, check out the Conditional Tags article in the Theme Developer Handbook.


Top ↑

Return

(bool) Whether the query is the main query.


Top ↑

More Information

The is_main_query() function is a conditional function that can be used to evaluate whether the current query (such as within the loop) is the “main” query (as opposed to a secondary query).

This function is most commonly used within hooks to distinguish WordPress’ main query (for a page, post, or archive) from a custom/secondary query.

is_main_query() may be used with both front-end queries (theme templates, plugins, etc.), as well as admin queries. It will return true if the current query is the main query, and false if not.

Top ↑

Usage


if ( is_main_query() ) {
// do stuff
}

Top ↑

Under the Hood

This function does not accept any parameters. Instead, it automatically compares the $wp_query object (i.e., the “current query”) with the $wp_the_query object (the “main query”)

This function is an alias for the method WP_Query::is_main_query(). In filter or action hook callbacks that are passed the WP_Query object, such as ‘pre_get_posts‘, it is circular to call this function. Instead, directly call the passed object’s method. For example, if your filter callback assigns the passed WP_Query object to $query, you would call the method like so:
$query->is_main_query()

Top ↑

Example

add_action( 'pre_get_posts', 'foo_modify_query_exclude_category' );
function foo_modify_query_exclude_category( $query ) {
    if ( ! is_admin() && $query->is_main_query() && ! $query->get( 'cat' ) )
        $query->set( 'cat', '-5' );
}

Top ↑

Source

File: wp-includes/query.php

function is_main_query() {
	global $wp_query;

	if ( 'pre_get_posts' === current_filter() ) {
		_doing_it_wrong(
			__FUNCTION__,
			sprintf(
				/* translators: 1: pre_get_posts, 2: WP_Query->is_main_query(), 3: is_main_query(), 4: Documentation URL. */
				__( 'In %1$s, use the %2$s method, not the %3$s function. See %4$s.' ),
				'<code>pre_get_posts</code>',
				'<code>WP_Query->is_main_query()</code>',
				'<code>is_main_query()</code>',
				__( 'https://developer.wordpress.org/reference/functions/is_main_query/' )
			),
			'3.7.0'
		);
	}

	return $wp_query->is_main_query();
}


Top ↑

Changelog

Changelog
Version Description
3.3.0 Introduced.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    Contributed by Codex

    Example of using WP_Query->is_main_query() instead of is_main_query() (invalid)

    /**
     * If the global query is for a category, exclude category 5.
     *
     * @param WP_Query $query Global WP_Query instance.
     */
    function wpdocs_modify_query_exclude_category( $query ) {
        if ( ! is_admin() && $query->is_main_query() && ! $query->get( 'cat' ) )
            $query->set( 'cat', '-5' );
    }
    add_action( 'pre_get_posts', 'wpdocs_modify_query_exclude_category' );
    

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