is_main_query()
Determines whether the query is the main query.
Contents
Description Description
For more information on this and similar theme functions, check out the Conditional Tags article in the Theme Developer Handbook.
Return Return
(bool)
Source Source
File: wp-includes/query.php
function is_main_query() {
if ( 'pre_get_posts' === current_filter() ) {
$message = sprintf(
/* translators: 1: pre_get_posts, 2: WP_Query->is_main_query(), 3: is_main_query(), 4: Link to codex is_main_query() page. */
__( '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://codex.wordpress.org/Function_Reference/is_main_query' )
);
_doing_it_wrong( __FUNCTION__, $message, '3.7.0' );
}
global $wp_query;
return $wp_query->is_main_query();
}
Expand full source code Collapse full source code View on Trac
Changelog Changelog
| Version | Description |
|---|---|
| 3.3.0 | Introduced. |
More Information 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.
Usage Usage
if ( is_main_query() ) {
// do stuff
}
Under the Hood 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()
Example 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' );
}
User Contributed Notes User Contributed Notes
You must log in before being able to contribute a note or feedback.
Example of using
WP_Query->is_main_query()instead ofis_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' );