How to Apply pre_get_posts on Custom Post Types in WordPress

To scope a wordpress pre_get_posts custom post type hook, check $query->is_post_type_archive('your_type') inside the callback — it returns true only on that archive URL and the main query. Without a scope check, pre_get_posts fires on every WP_Query in the request (widgets, related posts, REST calls) and leaks your ordering or filter into queries you didn’t mean to touch. This guide shows the three common check forms, the mandatory guards around them, and when to modify tax_query safely.

Last verified: 2026-04-23 on WordPress 6.5 and PHP 8.3. Originally published 2022-07-17, rewritten and updated 2026-04-23.

TL;DR

add_action( 'pre_get_posts', 'how7o_customize_cpt_archive' );

function how7o_customize_cpt_archive( $query ) {
    if ( is_admin() || ! $query->is_main_query() ) {
        return;
    }

    if ( $query->is_post_type_archive( 'custom_post_type' ) ) {
        $query->set( 'meta_key', 'votes' );
        $query->set( 'orderby', 'meta_value_num' );
        $query->set( 'order', 'DESC' );
    }
}

The three guards that belong on every pre_get_posts

• is_admin() — skip the hook in the WordPress admin. The admin list tables are their own WP_Querys; unless you specifically want to alter them, stay out.
• $query->is_main_query() — skip secondary queries. Widgets, block queries, related posts, REST API endpoints all fire through WP_Query and hit the hook too. The main query is the one WordPress built from the URL.
• A scope check for the specific page(s) you want to affect — one of the three forms below.

Skip any of these and the customization leaks. The cost of the guards is one extra condition per request.

Check 1 — $query->is_post_type_archive()

if ( $query->is_post_type_archive( 'event' ) ) {
    // runs on /events/ URL, main query
}

Returns true when the request is the custom-post-type archive (typically /events/ if your CPT uses has_archive => true). Doesn’t fire for single posts of that type, taxonomy archives, or search results that happen to include that type. This is the form you want 90% of the time.

Check 2 — is_post_type_archive() conditional tag

if ( is_post_type_archive( 'event' ) ) {
    // same result as $query->is_post_type_archive('event')
}

Same semantics, global function form. $query->is_post_type_archive() is more explicit inside a pre_get_posts callback — it’s obviously asking about the query being processed, not some ambient global state — so prefer the method form. The global tag is there for compatibility with older codebases.

Check 3 — $query->get('post_type')

if ( $query->get( 'post_type' ) === 'event' ) {
    // fires any time a query targets the 'event' post type
}

Reads the post_type query var directly. Fires anywhere the query specifies that post type — archive pages, some REST endpoints, explicit new WP_Query(['post_type' => 'event']) calls. Use this when you want the customization to apply broadly, not just on the archive URL. Combine with is_main_query to still avoid affecting secondary queries.

Watch out when your CPT is accessed via multiple query shapes — post_type can be a string ('event') or an array (['event', 'post']) on queries that mix types. For the array case: in_array('event', (array) $query->get('post_type'), true).

Modifying meta_query and tax_query

$query->set('meta_query', [...]) replaces the existing value. On archive pages WordPress may have already built part of the query (for example the tax_query on a category archive), and overwriting wipes that. Merge instead:

// Merge with existing, don't replace
$meta_query = $query->get( 'meta_query' ) ?: array();

$meta_query[] = array(
    'key'     => 'featured',
    'value'   => '1',
    'compare' => '=',
);

$query->set( 'meta_query', $meta_query );

Same pattern for tax_query. The ?: [] gives you a usable starting value when nothing was there yet, and the append leaves any existing clauses alone.

Also-useful scope checks

$query->is_home()           // the blog page
$query->is_category()       // any category archive
$query->is_category( 'news' ) // specifically the 'news' category
$query->is_tag( 'featured' ) // a specific tag archive
$query->is_tax( 'genre' )    // a custom-taxonomy archive
$query->is_search()          // search results
$query->is_author()          // author archive

Combine with the three mandatory guards (is_admin / is_main_query / scope) to target exactly the archive you want to modify.

Frequently asked questions

Related guides

• How to Order Posts by Meta Value in WordPress — the most common pre_get_posts customization.
• How to Get Posts by Date Range in WordPress — adding date_query via pre_get_posts.
• How to Get the Current Category ID in WordPress — context for taxonomy archive checks.
• How to Disable Revisions and Autosave in WordPress — another filter-driven customization.

References

WordPress developer reference for pre_get_posts and WP_Query conditional methods: developer.wordpress.org/reference/hooks/pre_get_posts.