Category: Blogging

If you’ve spent any time bending WordPress to your will, you’ve likely met both pre_get_posts and template_redirect. They sit in different corners of the request lifecycle, yet they’re often dragged into the same conversation—usually when a developer is trying to alter what appears on a page. The trouble is, they don’t do the same job. Not even close. And using one where the other belongs leads to silent failures, wasted queries, and layouts that feel like they’re fighting back.

I’m Jonas Venn, and I build WordPress systems that have to hold up under real content loads, not just demo data. I’ve watched both of these hooks betray developers who trusted them too much. Let’s walk through what each hook actually does, where they live in the request cycle, and the specific moments you’ll regret picking the wrong one.

Where These Hooks Sit in the WordPress Request Lifecycle

Before you can use either hook safely, you need to know when they fire. The WordPress request lifecycle is a sequence of events that starts with the index.php entry point and ends with a fully rendered template. pre_get_posts fires early, right after the main query object is set up but before any posts are fetched from the database. template_redirect fires much later, after the main query has run, after WordPress has determined which template file to load, but just before that template is actually rendered.

This timing difference is everything. pre_get_posts lets you modify the SQL query that fetches posts. template_redirect lets you hijack the entire page output. If you try to change what posts appear using template_redirect, you’re already too late—the query ran, the database round-trip happened, and you’re now patching a wound with a bandage that doesn’t stick.

pre_get_posts: The Query Modifier That Demands Precision

pre_get_posts is an action hook that gives you access to the WP_Query object before it hits the database. You use it to alter query variables—posts_per_page, post_type, category__in, meta_query, and so on. The hook passes the query object by reference, so your changes directly shape what WordPress retrieves.

Here’s a typical, clean example. Say you want to show only future events on the main blog archive, but you don’t want to touch the admin side or secondary queries:

add_action( 'pre_get_posts', 'jooom_modify_main_query' );
function jooom_modify_main_query( $query ) {
    if ( ! is_admin() && $query->is_main_query() && $query->is_home() ) {
        $query->set( 'meta_key', 'event_date' );
        $query->set( 'orderby', 'meta_value' );
        $query->set( 'order', 'ASC' );
        $query->set( 'meta_query', array(
            array(
                'key'     => 'event_date',
                'value'   => date( 'Y-m-d' ),
                'compare' => '>=',
                'type'    => 'DATE'
            )
        ) );
    }
}

This is pre_get_posts at its best: surgical, conditional, and aware of its context. The is_main_query() check is not optional. Without it, you’ll corrupt every query on the page—menus, widgets, related posts—and then wonder why your site’s navigation suddenly lists only future events.

When pre_get_posts Betrays You

The betrayal comes when you assume pre_get_posts can solve a problem it was never designed to touch. I’ve seen developers try to use it to redirect users, load alternative templates, or inject content into the loop. None of that works. By the time pre_get_posts fires, WordPress hasn’t decided which template to use. You can’t force a 404, you can’t switch to a custom page template, and you can’t output a different header. The hook is purely about shaping the main query’s SQL.

Another common pitfall: forgetting that pre_get_posts runs on every query unless you guard it. A missing is_main_query() check is the fastest way to break a site. I’ve also seen developers try to use pre_get_posts to alter queries on pages that don’t have a main query in the traditional sense—like a static front page. If your front page is set to a static page, the main query fetches that page, not a list of posts. Tweaking posts_per_page there does nothing visible, and you’ll waste an hour debugging why your custom loop isn’t showing up.

Another subtle betrayal: pre_get_posts runs on every request, including REST API and AJAX calls if they trigger a main query. If you’re not checking ! is_admin() and the request context, you might accidentally alter admin list tables or API responses. The fix is always more conditionals—$query->is_main_query(), ! is_admin(), and specific is_* checks.

template_redirect: The Page Hijacker That Thinks It’s Helpful

template_redirect fires after WordPress has determined which template to load, but before any output is sent to the browser. At this point, the main query is done. The global $wp_query object is fully populated. WordPress knows whether it’s a single post, a page, an archive, a 404, or a search result. This hook is your last chance to say, “No, I don’t want that template. I want something else entirely.”

Common uses include forcing a 404 when a post doesn’t meet certain criteria, redirecting users based on custom conditions, or loading a completely different template file for a specific URL pattern. For example, if you have a custom post type “portfolio” and you want to serve a special template only when a query string is present, template_redirect is your hook:

add_action( 'template_redirect', 'jooom_custom_portfolio_redirect' );
function jooom_custom_portfolio_redirect() {
    if ( is_singular( 'portfolio' ) && isset( $_GET['view'] ) && 'detailed' === $_GET['view'] ) {
        include get_stylesheet_directory() . '/portfolio-detailed.php';
        exit;
    }
}

This works because the main query already fetched the portfolio post. We’re just swapping the presentation layer. If you tried this with pre_get_posts, you’d be modifying a query that hasn’t even run yet, with no guarantee the template would match your intent.

When template_redirect Betrays You

The biggest betrayal is performance blindness. Because template_redirect fires after the main query, any database work that query did is already done. If you realize at this stage that you need different posts—say, you want to show related items instead of the main content—you’re stuck. You can run a secondary query with new WP_Query(), but now you’ve doubled your database load. The main query still ran, fetched posts you’re not using, and consumed server resources. On a high-traffic site, that’s a slow, painful death.

Another trap: using template_redirect to modify the main loop’s content. You can’t. The loop will iterate over whatever the main query returned. If you want to change that, you need to either override the global $wp_query (messy and risky) or use a different approach entirely—like a custom page template with a secondary query, or better yet, pre_get_posts to alter the main query before it runs.

I’ve also seen template_redirect used for conditional redirects that should have been handled earlier. For instance, if you need to redirect a user based on whether a post exists in a certain category, you can check that in template_redirect, but the main query already ran. A more efficient path is to hook into parse_request or parse_query and short-circuit the process before the database gets hit. template_redirect is convenient, but it’s not free.

Direct Comparison: When to Use Which

Let’s make this concrete. Here’s a side-by-side of common tasks and which hook you should reach for:

• Change the number of posts on an archive page: pre_get_posts. Alter posts_per_page before the query runs. template_redirect can’t do this without a second query.
• Exclude a category from the blog index: pre_get_posts. Use category__not_in on the main query. If you wait until template_redirect, the excluded posts are already fetched and counted toward pagination—your page counts will be wrong.
• Redirect a user based on post meta: template_redirect. You need the post data to decide, and that data is available only after the query. But consider if you can redirect earlier using parse_request to save the query cost.
• Load a custom template for a specific URL pattern: template_redirect. Use template_include filter if you just want to swap the file; use template_redirect if you need to run logic before deciding.
• Alter the sort order of search results: pre_get_posts. Modify the orderby and order parameters on the search query. template_redirect can’t reorder already-fetched results without a new query.
• Display a custom 404 page based on the requested URL: template_redirect. Check the global $wp_query->is_404() and load your template. But if you want to prevent the 404 by finding matching content, hook earlier—like parse_request—to avoid the 404 status header being sent.

Notice a pattern? pre_get_posts is for shaping what data the main query fetches. template_redirect is for deciding how to present the page after the data is fetched. Cross those lines, and you’ll create bugs that are hard to trace because they involve state that’s already been set.

Real-World Scenario: Fixing a “Nothing Found” Archive

Let’s look at a practical case that ties into a common WordPress headache. Suppose you have a custom post type “Projects” with an archive at /projects/. You’ve set has_archive => true when registering the post type, but visiting the URL shows “Nothing Found.” You might be tempted to jump into template_redirect and force a custom query. Don’t.

The “Nothing Found” message usually means the main query returned zero posts, often because of a conflict with the default query parameters or a plugin modifying queries incorrectly. The right fix is to use pre_get_posts to ensure the main query includes your custom post type on that archive page:

add_action( 'pre_get_posts', 'jooom_fix_project_archive' );
function jooom_fix_project_archive( $query ) {
    if ( ! is_admin() && $query->is_main_query() && $query->is_post_type_archive( 'project' ) ) {
        $query->set( 'posts_per_page', 12 );
        $query->set( 'orderby', 'date' );
        $query->set( 'order', 'DESC' );
    }
}

If you’re still seeing “Nothing Found” after that, the problem is likely deeper—maybe the post type isn’t registered correctly, or a plugin is unsetting your query vars. I’ve written about diagnosing that exact situation in What to Fix First When a New WordPress Site Says Nothing Found. The point here is that pre_get_posts is your first line of defense for query-related issues. template_redirect won’t help you if the main query is empty; you’d just be loading a template that has no posts to display.

Performance Considerations That Most Guides Skip

Every time you use template_redirect to run a secondary query, you’re adding database load. On a page that already has a main query, plus maybe a few widget queries, adding another full WP_Query can push your server over the edge during traffic spikes. I’ve seen sites where a well-meaning developer used template_redirect to create a “custom loop” for a specific category, resulting in two full queries where one would have sufficed. The fix was to move the logic to pre_get_posts and let the main query handle everything.

But pre_get_posts isn’t always the performance hero. If you add complex meta queries or tax queries to the main query, you can slow down every page load on your site—even pages that don’t display the results. That’s because pre_get_posts modifies the query before it runs, and if your conditionals aren’t tight enough, you’ll burden unrelated pages with expensive database operations. Always use the most specific conditional tags possible: $query->is_post_type_archive() instead of just is_archive(), for example.

When Both Hooks Betray You: The Case of the Missing Conditional

There’s a scenario where neither hook works as expected, and it’s maddening until you understand why. Imagine you want to modify the query for a page that uses a custom page template. You hook into pre_get_posts and check is_page_template( 'custom-template.php' ). It doesn’t fire. Why? Because pre_get_posts runs before the template is selected. The conditional tag is_page_template() relies on the template being chosen, which happens later. So your check fails, and your modifications never apply.

You might then try template_redirect, but by then the query is done. You can run a new query, but you’ve lost the efficiency of modifying the main query. The solution is to use a different conditional in pre_get_posts—like checking the page slug or ID—or to override the main query entirely with query_posts() (which is generally discouraged but sometimes necessary). This is the kind of edge case that separates a builder from a copier: understanding the exact sequence of WordPress core actions and knowing which hook gives you the control you need.

FAQ

Can I use pre_get_posts to redirect a user?

No. pre_get_posts fires before headers are sent, but it’s not designed for redirects. The hook’s purpose is to modify query variables. If you try to call wp_redirect() inside a pre_get_posts callback, you’ll likely cause errors because output may have already started, or you’ll interfere with the query setup. Use template_redirect or an earlier hook like parse_request for redirects.

Why does my pre_get_posts modification affect admin pages?

Because you forgot to include ! is_admin() in your conditional check. pre_get_posts runs on every query, including those in the WordPress admin area. Without that check, your changes will alter post lists, media library queries, and other admin screens. Always start your pre_get_posts callback with if ( is_admin() ) return; unless you specifically intend to modify admin queries.

Is it safe to run a new WP_Query inside template_redirect?

It’s safe in the sense that it won’t break the page, but it’s inefficient. The main query has already run and fetched posts. If you run a new WP_Query, you’re adding a second database request. For small sites, this might not matter. For sites with heavy traffic or large databases, it can cause noticeable slowdowns. Whenever possible, restructure your logic to modify the main query via pre_get_posts instead.

What’s the difference between template_redirect and template_include?

template_redirect is an action hook that fires before the template is loaded; it’s meant for performing logic like redirects or custom conditions. template_include is a filter hook that lets you change which template file is loaded. If you just need to swap the template file, use template_include. If you need to run additional logic (like checking user permissions) before deciding on the template, use template_redirect.

Understanding these two hooks isn’t about memorizing their definitions. It’s about knowing the exact moment in WordPress’s execution where your code will run, and what state the system is in at that moment. Get that right, and you’ll stop fighting your own site.

Most WordPress search results pages are blunt instruments. They match query strings against post content and titles, then dump everything into a single chronological list. For a site with a carefully built editorial taxonomy—categories, tags, custom taxonomies, and curated relationships—that default behavior is a quiet disaster. It ignores the structural decisions editors made and treats every piece of content as an undifferentiated blob. The result is a search experience that feels disconnected from the rest of the site, and worse, it trains users to stop trusting the navigation you built.

I’m Jonas Venn, and I spend my days inside WordPress systems engineering. I see this pattern repeat across news sites, documentation portals, and content-heavy membership platforms. The fix isn’t a plugin that promises AI-powered everything. It’s a deliberate rebuild of the search query, the template, and the way results are presented. This article walks through that rebuild step by step, with code you can drop into a child theme or a custom plugin.

Why Default WordPress Search Undermines Editorial Structure

WordPress ships with a search mechanism that runs a simple WP_Query looking at post_title and post_content. It doesn’t consider taxonomy terms, custom fields, or the weight of different content types. If you run a site where a “Guide” custom post type should always rank above a “News” post for certain queries, the default search won’t know that. If you have a hierarchical category structure where “Tutorials > Intermediate” is more relevant than a loosely tagged post, the default search ignores that hierarchy entirely.

This creates a mismatch. Editors spend hours building taxonomies that group, relate, and prioritize content. The search page then bypasses all of that work. Users who click a category link get a beautifully filtered view; users who type the same concept into the search bar get a noisy, flat list. That inconsistency erodes confidence in the site’s information architecture.

Mapping the Search Query to Your Taxonomy Model

Before writing any code, you need to define what a “good” result looks like for your specific content model. This isn’t a one-size-fits-all problem. On a documentation site, a result from the “Reference” custom post type might be more valuable than a blog post. On a recipe site, a result tagged with the exact ingredient the user typed should surface above a post that merely mentions it in passing.

Start by listing your content types and taxonomies. For each, decide:

• Which post types should be searched by default?
• Which taxonomies should be matched against the search query?
• Should taxonomy term archives themselves appear as results?
• What weighting or sorting logic makes sense for your editorial priorities?

Once you have that map, you can modify the main search query using the pre_get_posts action. This hook lets you alter the query before it runs, so you can add post types, set meta queries, and adjust ordering without touching the template.

add_action( 'pre_get_posts', function( $query ) {
    if ( ! is_admin() && $query->is_main_query() && $query->is_search() ) {
        $query->set( 'post_type', array( 'post', 'guide', 'reference' ) );
        $query->set( 'posts_per_page', 20 );
        // We'll add taxonomy-aware ordering later
    }
});

This snippet expands the search to include custom post types. But it’s still just a content match. To make the search taxonomy-aware, you need to go deeper.

Injecting Taxonomy Term Matching into the Search Logic

WordPress doesn’t natively search taxonomy terms. If a user types “intermediate,” the default search looks for that word in post titles and content. It won’t find posts assigned to the “Intermediate” category unless the word appears in the post body. To fix this, you need to intercept the search query and add a taxonomy condition.

One approach is to use the posts_search filter to modify the SQL WHERE clause, but that’s fragile and hard to maintain. A cleaner method is to run a two-pass search: first, find taxonomy terms that match the query; second, include posts assigned to those terms in the results, weighted appropriately.

Here’s a practical implementation. We’ll hook into pre_get_posts and build a tax query if the search string matches any existing term names:

add_action( 'pre_get_posts', function( $query ) {
    if ( ! is_admin() && $query->is_main_query() && $query->is_search() ) {
        $search_term = $query->get( 's' );
        if ( empty( $search_term ) ) {
            return;
        }

        // Find matching terms across specified taxonomies
        $matching_terms = get_terms( array(
            'taxonomy'   => array( 'category', 'post_tag', 'guide_topic' ),
            'name__like' => $search_term,
            'fields'     => 'ids',
            'hide_empty' => false,
        ) );

        if ( ! empty( $matching_terms ) && ! is_wp_error( $matching_terms ) ) {
            $tax_query = array(
                'relation' => 'OR',
                array(
                    'taxonomy' => 'category',
                    'field'    => 'term_id',
                    'terms'    => $matching_terms,
                ),
                array(
                    'taxonomy' => 'post_tag',
                    'field'    => 'term_id',
                    'terms'    => $matching_terms,
                ),
                array(
                    'taxonomy' => 'guide_topic',
                    'field'    => 'term_id',
                    'terms'    => $matching_terms,
                ),
            );
            $query->set( 'tax_query', $tax_query );
        }
    }
});

This code checks if the search string matches any term name in your chosen taxonomies. If it does, it adds a tax_query that pulls in posts assigned to those terms. The OR relation means a post can match via content or via taxonomy assignment. That’s a start, but it still doesn’t prioritize taxonomy-matched posts over content-matched ones. For that, we need to adjust the ordering.

Weighting Results by Editorial Relevance

Default WordPress search orders by date, or by relevance if you’re using MySQL’s fulltext search. Neither respects your editorial taxonomy. To change that, you can use the posts_orderby filter to inject custom sorting logic, or you can run a secondary query that merges and reorders results based on your own scoring system.

I prefer a scoring approach because it gives you full control. Here’s the idea: run the main query to get content-matched posts, then separately query for taxonomy-matched posts. Assign a relevance score to each post based on where the match occurred—title match scores highest, then taxonomy term match, then content match. Merge the results, deduplicate, and sort by score.

This requires overriding the default search template. Create a search.php file in your theme (or better, a child theme) and build the custom query there:

$search_term = get_search_query();
$scored_posts = array();

// Query 1: Title matches (highest score)
$title_query = new WP_Query( array(
    'post_type'      => array( 'post', 'guide', 'reference' ),
    'posts_per_page' => -1,
    's'              => $search_term,
    'search_columns' => array( 'post_title' ),
) );
foreach ( $title_query->posts as $post ) {
    $scored_posts[ $post->ID ] = array( 'post' => $post, 'score' => 3 );
}

// Query 2: Taxonomy term matches (medium score)
$matching_terms = get_terms( array(
    'taxonomy'   => array( 'category', 'post_tag', 'guide_topic' ),
    'name__like' => $search_term,
    'fields'     => 'ids',
    'hide_empty' => false,
) );
if ( ! empty( $matching_terms ) && ! is_wp_error( $matching_terms ) ) {
    $tax_query = new WP_Query( array(
        'post_type'      => array( 'post', 'guide', 'reference' ),
        'posts_per_page' => -1,
        'tax_query'      => array(
            array(
                'taxonomy' => 'category',
                'field'    => 'term_id',
                'terms'    => $matching_terms,
            ),
        ),
    ) );
    foreach ( $tax_query->posts as $post ) {
        if ( ! isset( $scored_posts[ $post->ID ] ) ) {
            $scored_posts[ $post->ID ] = array( 'post' => $post, 'score' => 2 );
        } else {
            $scored_posts[ $post->ID ]['score'] += 2;
        }
    }
}

// Query 3: Content matches (lowest score)
$content_query = new WP_Query( array(
    'post_type'      => array( 'post', 'guide', 'reference' ),
    'posts_per_page' => -1,
    's'              => $search_term,
) );
foreach ( $content_query->posts as $post ) {
    if ( ! isset( $scored_posts[ $post->ID ] ) ) {
        $scored_posts[ $post->ID ] = array( 'post' => $post, 'score' => 1 );
    }
}

// Sort by score descending
usort( $scored_posts, function( $a, $b ) {
    return $b['score'] - $a['score'];
});

This gives you a $scored_posts array sorted by editorial relevance. A post whose title contains the search term gets a score of 3. A post assigned to a matching taxonomy term gets 2. A post that only matches in content gets 1. If a post matches in multiple ways, the scores add up, naturally boosting the most relevant content to the top.

You can extend this scoring model to include custom fields, post type priority, or even recency. The key is that you define the weights based on your editorial structure, not an opaque algorithm.

Designing the Results Template to Reflect Taxonomy Context

Even with smart ordering, a search results page can still look like a disconnected list. The template needs to show why a result is relevant. That means displaying the taxonomy terms that triggered the match, the post type label, and breadcrumb-style context.

For each result, output the post type as a small label (“Guide,” “Reference,” “Article”) and list the matching taxonomy terms. If a post matched because it’s in the “Intermediate” category, show that category with a link. This reinforces the site’s information architecture and gives users a path to browse related content.

Here’s a loop snippet for the scored results:

if ( ! empty( $scored_posts ) ) :
    foreach ( $scored_posts as $item ) :
        $post = $item['post'];
        setup_postdata( $post ); ?>
        

            

            

                post_type )->labels->singular_name; ?>
                ID );
                if ( $categories ) {
                    echo ' in ';
                    $cat_links = array();
                    foreach ( $categories as $cat ) {
                        $cat_links[] = '' . $cat->name . '';
                    }
                    echo implode( ', ', $cat_links );
                    echo '';
                }
                ?>
            
            

        
    
    
No results found for your search. Try a different term or browse our categories.

Notice the fallback message. When a search truly returns nothing, don’t just show a dead end. Link to the category archive or a sitemap-style page. If you have a post that explains common search pitfalls, link to that too. For example, if your site has a known issue with empty archives after a migration, you might point users to a resource like What to Fix First When a New WordPress Site Says Nothing Found. That turns a failed search into a helpful navigation moment.

Handling Faceted Search Without Breaking the Query

If your site uses faceted search—allowing users to filter by post type, category, or tag—you need to integrate those facets with your custom scoring. The danger is that a faceted filter (e.g., “Show only Guides”) will override your carefully weighted query and revert to default date ordering.

The solution is to apply facets as additional query arguments on top of your scored results, not as a replacement query. If you’re using WP_Query directly in the template, you can merge facet parameters into each of your three scoring queries. If you’re using a plugin like FacetWP, you’ll need to hook into its indexing process to preserve your custom relevance scores.

For a custom faceted setup, extend the earlier code to accept query variables from the URL:

$post_type_filter = isset( $_GET['post_type'] ) ? sanitize_text_field( $_GET['post_type'] ) : '';
$category_filter = isset( $_GET['category'] ) ? intval( $_GET['category'] ) : 0;

$base_args = array(
    'posts_per_page' => -1,
);
if ( $post_type_filter ) {
    $base_args['post_type'] = $post_type_filter;
} else {
    $base_args['post_type'] = array( 'post', 'guide', 'reference' );
}
if ( $category_filter ) {
    $base_args['cat'] = $category_filter;
}

// Use $base_args in each of the three scoring queries

This keeps the scoring logic intact while respecting the user’s chosen filters. The facets become a lens on top of your editorial relevance model, not a replacement for it.

Caching Considerations for High-Traffic Search Pages

Running three separate WP_Query instances on every search request can get expensive. On a site with thousands of posts, you’ll want to cache the results. WordPress transients are a good fit here. Generate a cache key based on the search term and any active filters, store the scored results array, and serve from cache when possible.

$cache_key = 'search_results_' . md5( $search_term . $post_type_filter . $category_filter );
$scored_posts = get_transient( $cache_key );

if ( false === $scored_posts ) {
    // Run the three queries and build $scored_posts
    set_transient( $cache_key, $scored_posts, HOUR_IN_SECONDS );
}

Invalidate the cache when new content is published or when taxonomy terms are updated. Hook into save_post and edited_term to delete relevant transients. This keeps the search fresh without hammering the database on every request.

Testing Your Taxonomy-Aware Search

You can’t trust that your scoring logic works until you test it against real editorial content. Create a set of test posts with known titles, taxonomy assignments, and body content. Then run searches that should match in specific ways:

• A search for a term that appears only in a post title should return that post first.
• A search for a category name should return posts in that category, even if the word isn’t in the post content.
• A search that matches both a title and a taxonomy term should rank higher than a content-only match.
• Applying a post type filter should narrow results without breaking the scoring order.

Use WP_DEBUG and query logging during development to see exactly what SQL is being generated. If you’re on a local environment, the Query Monitor plugin is invaluable for spotting slow queries or unexpected tax query joins.

Extending the Model to Custom Taxonomies and Post Types

The code examples above use standard categories and tags, but the same pattern works for any registered taxonomy. If you run a documentation site with a “Software Version” taxonomy, you can include it in the term-matching step. If you have a “Priority” custom field that editors use to mark important content, you can factor that into the scoring.

The important principle is that your search should reflect the same organizational logic that editors use when they structure the site. If a human editor would say “this guide is more relevant than that news post for this query,” your search algorithm should agree. That means sitting down with your editorial team, understanding their taxonomy decisions, and encoding those decisions into the scoring weights.

FAQ

Will this custom search work with the block editor’s site editor?

Yes, but you’ll need to use a child theme or a custom plugin to house the PHP code. The block editor’s full-site editing mode doesn’t support arbitrary PHP in templates, so a classic search.php template in a child theme is the most reliable approach. If you’re committed to FSE, you can build a custom block that runs the scored query and renders results, but that adds complexity.

How do I handle misspellings or partial matches in taxonomy terms?

The name__like parameter in get_terms() does a basic SQL LIKE match, which won’t catch misspellings. For fuzzy matching, you could use the get_terms filter to modify the SQL, or pre-process the search term with similar_text() against your term list. A simpler approach is to use WordPress’s built-in soundex or metaphone functions, but those are limited. For most sites, exact and partial matching covers the majority of user queries.

Does this approach affect the WordPress admin search?

No, the code examples use ! is_admin() checks to ensure they only run on the front end. The admin search will continue to use the default WordPress behavior. If you want to apply similar logic to the admin, you can remove that condition, but be cautious—admin search screens often have their own filtering needs.

Can I use this with a third-party search plugin like Relevanssi?

Yes, but you’ll need to adapt the approach. Plugins like Relevanssi already index taxonomy terms and allow custom weighting. Instead of building your own scoring queries, you’d configure the plugin’s settings to match your editorial priorities. The template design principles still apply: show taxonomy context and post type labels in the results.

Building a search results page that respects your editorial taxonomy isn’t about adding more features. It’s about removing the disconnect between how you organize content and how users find it. The code in this article gives you a foundation. The real work is in defining what relevance means for your specific content model, and then sticking to that definition across every search interaction on your site.

You’re building a custom archive page. You need to tweak the main query—maybe change the posts per page, add a meta query, or exclude a category. You reach for pre_get_posts. It’s the standard, the safe bet. But then you add a redirect for a specific template, or you need to fire a 404, and suddenly your query modifications vanish, or worse, they fire on the wrong page entirely. You’ve stumbled into the gap between pre_get_posts and template_redirect.

I’ve debugged this exact scenario on client sites more times than I can count. A developer hooks into pre_get_posts to customize the main query on a custom post type archive. Then they add a template_redirect to enforce some access logic. The redirect fires, but the query is already set—or worse, the query modification runs on the redirected page, mangling the wrong loop. Understanding the execution order isn’t just academic; it’s what keeps your site from serving broken layouts or exposing content you meant to hide.

The WordPress Request Lifecycle in Plain Terms

Before we pit these two hooks against each other, we need to map the terrain. WordPress processes every request through a predictable sequence. The key players are pre_get_posts, which fires inside the WP_Query constructor, and template_redirect, which fires much later, just before the template is chosen.

Here’s the simplified order:

1. Query parsing: WordPress translates the URL into query variables.
2. pre_get_posts: Fires after the query variable object is created but before the actual database query runs. This is where you modify the main query.
3. Database query: WordPress fetches the posts based on the (possibly modified) query variables.
4. template_redirect: Fires after the query is run and posts are loaded, but before the template is selected. This is where you decide which template file to use or whether to redirect the user entirely.

The trap is set when you use pre_get_posts to alter a query that template_redirect later invalidates. Or when you use template_redirect to force a 404, but pre_get_posts has already run a heavy, unnecessary database query. The order is fixed, and misunderstanding it leads to wasted resources and logic errors.

When pre_get_posts Is the Right Tool

pre_get_posts is the scalpel for the main query. It fires on every single page load—front end, back end, feeds, you name it. Its sole purpose is to alter the query variables before the SQL is built. Use it when you need to change what posts appear on an archive, search, or blog page without creating a secondary query.

For example, let’s say you want to exclude a category from the main blog page but only on the front end. You’d hook into pre_get_posts, check that you’re on the main query and not in the admin, and then modify the category parameters.

add_action( 'pre_get_posts', 'joo_exclude_category_from_blog' );
function joo_exclude_category_from_blog( $query ) {
    if ( ! $query->is_main_query() || is_admin() ) {
        return;
    }
    if ( $query->is_home() ) {
        $query->set( 'category__not_in', array( 12 ) ); // Exclude category ID 12
    }
}

This is clean, efficient, and doesn’t trigger a second query. The database does the heavy lifting in one pass. But the moment you need to make a decision based on the results of that query, pre_get_posts becomes useless. It fires before the query runs, so you can’t know if the query returned zero posts, or if a specific post has a certain meta value. That’s when you’re tempted to jump to template_redirect—and that’s where the trouble often starts.

The template_redirect Overreach

template_redirect is the hook you use when you need to change the template file or perform a hard redirect. It fires after the query is complete and WordPress has determined what type of page it is (404, single, archive, etc.). It’s the perfect place to say, “Actually, this isn’t the page I want; send the user over there instead.”

Here’s a classic misuse: a developer wants to hide a custom post type archive unless the user is logged in. They write a pre_get_posts callback that sets post__not_in to an empty array, but that still runs the query. Then they add a template_redirect to check is_post_type_archive('hidden_cpt') and redirect non-logged-in users. The problem? The query already ran. On a site with thousands of posts, that’s a wasted, potentially expensive database call. The correct approach is to kill the query early, but template_redirect is too late for that.

Another common pitfall: using template_redirect to set a 404 status. You might think, “I’ll check if a certain condition is met, and if not, I’ll set a 404.” But by the time template_redirect fires, WordPress has already decided it’s not a 404. You can force the 404 template to load, but the headers might already be sent, and the main query has already consumed resources. You’re patching a symptom, not the cause.

Where pre_get_posts Fails You

pre_get_posts is not a decision engine. It’s a modifier. You can’t use it to check if a user has permission to see a specific post, because the post hasn’t been fetched yet. You can’t use it to redirect based on the number of results, because the results don’t exist. You can’t even reliably use it to set a 404, because the 404 status is determined later in the process.

Consider a membership site where certain posts are only visible to logged-in users. A naive approach hooks into pre_get_posts and adds a meta query to filter out restricted posts. That works for the loop, but it doesn’t prevent direct access to a single restricted post via its permalink. For that, you need a later hook—but if you use template_redirect to check permissions and then redirect, you’ve already run the main query for that single post. It’s a small waste, but on a high-traffic site, it adds up.

The real betrayal happens when you combine both hooks without understanding their sequence. You modify the query in pre_get_posts, then in template_redirect you check a condition that depends on the query results. If the condition fails, you redirect. But the query already ran with your modifications, and those modifications might have been expensive—like a meta query on a large post type. You’ve just burned server resources for a page that will never be seen.

Building a Smarter Redirect: The posts_request Filter

If you need to redirect based on query results, but you want to avoid the cost of running the full query, there’s a lesser-known hook: posts_request. This filter fires after the SQL is built but before it’s sent to the database. You can intercept the SQL, run a lightweight check, and if the conditions aren’t met, short-circuit the query and redirect.

Here’s an example. Suppose you have a custom post type “event” and you want to redirect to a calendar page if there are no upcoming events. Instead of letting the query run and then checking in template_redirect, you can do this:

add_filter( 'posts_request', 'joo_redirect_if_no_events', 10, 2 );
function joo_redirect_if_no_events( $request, $query ) {
    if ( ! $query->is_main_query() || ! $query->is_post_type_archive( 'event' ) ) {
        return $request;
    }
    // Run a lightweight count query
    $count = wp_count_posts( 'event' )->publish;
    if ( 0 === $count ) {
        wp_redirect( home_url( '/calendar/' ) );
        exit;
    }
    return $request;
}

This hook fires right before the database query, so you can still abort with a redirect and avoid the full query cost. But be careful: posts_request gives you the raw SQL string, not a query object. You can’t use $query->set() here; you’d need to manipulate the SQL directly or, as shown, run a separate lightweight query to make your decision.

When to Use Each Hook: A Practical Guide

Let’s break down common scenarios and the right hook for each.

Modifying the Main Query on Archives

Hook: pre_get_posts
Why: You want to change the posts per page, order, or add a meta query for a specific archive. This is the canonical use case. The query hasn’t run yet, so you’re not wasting resources.

add_action( 'pre_get_posts', 'joo_modify_archive_query' );
function joo_modify_archive_query( $query ) {
    if ( is_admin() || ! $query->is_main_query() ) {
        return;
    }
    if ( $query->is_post_type_archive( 'product' ) ) {
        $query->set( 'posts_per_page', 12 );
        $query->set( 'orderby', 'title' );
        $query->set( 'order', 'ASC' );
    }
}

Redirecting Based on Post Count

Hook: posts_request or template_redirect
Why: If you need to redirect when a query returns no results, template_redirect is the standard place. But if the query is expensive, consider posts_request to abort early. For a simple blog archive, the cost difference is negligible; for a complex meta query on thousands of posts, it’s significant.

Here’s a template_redirect example that redirects a search with no results to a custom “no results” page:

add_action( 'template_redirect', 'joo_redirect_empty_search' );
function joo_redirect_empty_search() {
    if ( is_search() && ! have_posts() ) {
        wp_redirect( home_url( '/search-tips/' ) );
        exit;
    }
}

This is acceptable because the search query already ran. But if you’re dealing with a custom query that you know will be empty under certain conditions, intercept earlier.

Forcing a 404 on Invalid Single Posts

Hook: wp or parse_query
Why: If you need to force a 404 on a single post based on its content (e.g., a custom field), you can’t do it in pre_get_posts because the post hasn’t been fetched. template_redirect works but is late. The wp hook fires after the query object is set up but before the template is loaded, giving you access to the queried post. You can then set a 404 status and load the 404 template without running the full template hierarchy.

add_action( 'wp', 'joo_force_404_on_hidden_posts' );
function joo_force_404_on_hidden_posts( $wp ) {
    if ( ! is_singular( 'hidden_post_type' ) ) {
        return;
    }
    $post = get_queried_object();
    $is_visible = get_post_meta( $post->ID, '_joo_visibility', true );
    if ( 'hidden' === $is_visible && ! current_user_can( 'edit_posts' ) ) {
        $wp->set_404();
        status_header( 404 );
        nocache_headers();
        include( get_query_template( '404' ) );
        exit;
    }
}

This approach sets the 404 status properly and loads the 404 template without running the full single post template. It’s more efficient than a template_redirect redirect because it doesn’t trigger an additional HTTP request.

When Both Hooks Collide: A Debugging Story

I once inherited a site where the blog page was mysteriously blank. The theme had a pre_get_posts callback that set posts_per_page to 6 for the blog archive. A plugin, however, used template_redirect to check if the current page was the blog archive and, if so, redirect to a custom page template. The problem? The plugin’s redirect fired after the query was modified, but the custom template didn’t account for the altered posts_per_page. It used a hardcoded value of 10, so when the query returned only 6 posts, the template’s loop logic broke, showing empty spaces and a missing “next page” link.

The fix was to move the posts_per_page modification to the custom template’s own query, or to use a filter that runs later, like found_posts, to adjust pagination. But the real lesson was about ownership: pre_get_posts and template_redirect were fighting over the same query, and neither was clearly in charge. We ended up consolidating all query logic into a single class that used pre_get_posts for modifications and template_include for template overrides, with a shared state object to avoid conflicts.

Building a Shared State Between Hooks

Sometimes you need to pass information from an early hook to a later one. For example, you might detect a condition in pre_get_posts that should later affect the template choice. WordPress doesn’t provide a built-in way to do this, but you can use a static class property or a transient.

Here’s a pattern I’ve used on membership sites:

class JOO_Query_State {
    public static $is_restricted = false;
}

add_action( 'pre_get_posts', 'joo_check_restricted_archive' );
function joo_check_restricted_archive( $query ) {
    if ( $query->is_post_type_archive( 'premium_content' ) && ! current_user_can( 'read_premium' ) ) {
        JOO_Query_State::$is_restricted = true;
        // Prevent the query from fetching posts
        $query->set( 'post__in', array(0) );
    }
}

add_action( 'template_redirect', 'joo_redirect_restricted_archive' );
function joo_redirect_restricted_archive() {
    if ( JOO_Query_State::$is_restricted ) {
        wp_redirect( home_url( '/upgrade/' ) );
        exit;
    }
}

This way, the query is neutered early, and the redirect happens at the right time. The static property acts as a bridge between the two hooks without relying on global variables or re-running logic.

Performance Implications You Can’t Ignore

Every hook you use adds execution time. pre_get_posts fires on every page load, so keep your callbacks lean. Avoid complex logic or additional database calls inside it. If you need to check user permissions, use WordPress’s cached functions like current_user_can()—they’re fast.

template_redirect fires later, but it’s still before the template renders. If you’re doing a redirect, use wp_redirect() with an exit to stop further execution. Don’t let the rest of the page load continue after a redirect; it’s a waste of server resources and can cause header-already-sent errors.

When you’re working with large datasets, the difference between aborting at posts_request versus template_redirect can be measured in milliseconds per request. On a site with 100,000 posts and a complex meta query, that’s the difference between a 200ms response and a 2-second timeout.

FAQ

Can I use pre_get_posts to redirect a user?

No. pre_get_posts fires before headers are sent, but it’s not designed for redirects. You can technically call wp_redirect() inside it, but it’s unreliable and can cause errors because the query hasn’t finished setting up. Use template_redirect or an earlier hook like parse_request for redirects.

Why does my pre_get_posts modification not work on a custom page template?

If your custom page template uses a secondary query (like new WP_Query), pre_get_posts won’t affect it unless you pass the query object and set is_main_query incorrectly. pre_get_posts only alters the main query by default. For secondary queries, modify the arguments directly when you instantiate WP_Query.

What’s the earliest hook I can use to force a 404?

The parse_query hook fires after the query variables are parsed but before the database query. You can use it to set is_404 and is_singular to false, effectively forcing a 404 without running the main query. However, this requires deep understanding of the query object and can break things if not done carefully. The wp hook is a safer, slightly later alternative.

Choosing the Right Hook for the Job

The gap between pre_get_posts and template_redirect is where many WordPress projects accumulate technical debt. The fix isn’t to avoid one or the other; it’s to understand the request lifecycle and place your logic at the earliest possible point that has the information you need.

If you’re modifying what posts appear, use pre_get_posts. If you’re deciding which template to load, use template_redirect. If you’re doing both, consider whether you can split the logic or use an intermediate hook like wp or posts_request. And if you find yourself fighting the system, step back and ask whether your architecture is trying to do too much in the query layer. Sometimes the best fix is a custom REST endpoint or a page template that handles its own data fetching.

For more on fixing common WordPress query issues, read What to Fix First When a New WordPress Site Says Nothing Found. It covers the early debugging steps that often reveal hook conflicts like the ones described here.

Remember: every hook is a tool with a specific shape. Use the one that fits the task, not the one that’s closest to hand.

You drop a crisp, hand-optimized SVG into the WordPress media library. Instead of a sharp icon or a responsive illustration, you get a broken image thumbnail, a security error, or a blank space where your graphic should be. The frustration is real, especially when you know the file is clean. The problem isn’t your SVG—it’s how WordPress handles it by default. I’m Jonas Venn, and I build systems that treat the front end as a precision instrument. This article walks through the exact reasons SVG uploads fail and gives you direct, code-level fixes that don’t rely on plugins.

The Core Problem: WordPress Treats SVGs as a Security Risk

WordPress doesn’t block SVGs out of spite. Scalable Vector Graphics are XML-based, which means they can contain inline scripts, event handlers, and external references. A malicious SVG can execute JavaScript, load remote resources, or embed hidden tracking pixels. The WordPress core team decided that the safest default is to reject the file type entirely. When you try to upload an SVG, the wp_check_filetype_and_ext function runs a MIME type check. If the file doesn’t pass the allowed list, you get the classic “Sorry, this file type is not permitted for security reasons” message.

This isn’t a bug. It’s a deliberate design choice. But for developers and site builders who need crisp, resolution-independent graphics, it’s a roadblock. The typical workaround is a plugin like Safe SVG or SVG Support. Those work, but they add another dependency, another update surface, and often more code than you actually need. If you’re comfortable editing your theme’s functions.php or building a small custom plugin, you can solve this with a few precise lines of code.

Step 1: Allow the SVG MIME Type

The first barrier is WordPress’s MIME type whitelist. You need to tell WordPress that image/svg+xml is an acceptable file type. This is done by hooking into the upload_mimes filter. Add this to your theme’s functions.php or, better, a site-specific plugin:

add_filter( 'upload_mimes', 'jooom_add_svg_mime' );
function jooom_add_svg_mime( $mimes ) {
    $mimes['svg'] = 'image/svg+xml';
    return $mimes;
}

This snippet registers the .svg extension with the correct MIME type. After adding this, you can upload an SVG, and WordPress will accept the file. But you’ll immediately hit the next wall: the media library shows a generic placeholder instead of a preview, and the file might still not display correctly in the block editor. That’s because WordPress also needs to handle the file’s display and sanitization.

Step 2: Fix the Media Library Preview

WordPress generates thumbnail previews for raster images using the GD or Imagick library. SVGs are vector files, so these libraries can’t process them. The result is a broken image icon in the grid view. To fix this, you need to tell WordPress to use the SVG itself as the thumbnail. Hook into wp_prepare_attachment_for_js and wp_get_attachment_image_src to override the default behavior.

add_filter( 'wp_prepare_attachment_for_js', 'jooom_fix_svg_media_library', 10, 3 );
function jooom_fix_svg_media_library( $response, $attachment, $meta ) {
    if ( $response['mime'] === 'image/svg+xml' ) {
        $response['sizes'] = array(
            'full' => array(
                'url' => $response['url'],
                'width' => $response['width'],
                'height' => $response['height'],
                'orientation' => $response['orientation'],
            ),
        );
        $response['icon'] = $response['url'];
    }
    return $response;
}

add_filter( 'wp_get_attachment_image_src', 'jooom_fix_svg_thumbnail', 10, 4 );
function jooom_fix_svg_thumbnail( $image, $attachment_id, $size, $icon ) {
    if ( get_post_mime_type( $attachment_id ) === 'image/svg+xml' ) {
        $image[0] = wp_get_attachment_url( $attachment_id );
        $image[1] = $image[2] = null;
    }
    return $image;
}

These two functions ensure that the media library shows the actual SVG as the preview and that any calls to wp_get_attachment_image_src return the original file. The width and height are set to null because SVGs are inherently responsive; forcing dimensions can distort them. This approach keeps your SVGs fluid in the admin and on the front end.

Step 3: Sanitize SVGs on Upload to Strip Malicious Code

Allowing SVGs without sanitization is like leaving your front door unlocked. Even if you trust the source, a designer might unknowingly upload an SVG exported from a compromised tool. The fix is to strip out scripts, event handlers, and other risky elements at the point of upload. PHP’s DOMDocument class makes this straightforward. We’ll hook into wp_handle_upload_prefilter to clean the file before WordPress saves it.

add_filter( 'wp_handle_upload_prefilter', 'jooom_sanitize_svg' );
function jooom_sanitize_svg( $file ) {
    if ( $file['type'] !== 'image/svg+xml' ) {
        return $file;
    }

    $dom = new DOMDocument();
    $dom->loadXML( file_get_contents( $file['tmp_name'] ), LIBXML_NOENT | LIBXML_DTDLOAD );

    $allowed_tags = array( 'svg', 'g', 'path', 'circle', 'rect', 'line', 'polyline', 'polygon', 'ellipse', 'text', 'tspan', 'defs', 'use', 'clipPath', 'mask', 'linearGradient', 'radialGradient', 'stop', 'pattern', 'image', 'title', 'desc' );
    $allowed_attributes = array( 'id', 'class', 'xmlns', 'viewBox', 'width', 'height', 'x', 'y', 'x1', 'y1', 'x2', 'y2', 'cx', 'cy', 'r', 'rx', 'ry', 'd', 'points', 'fill', 'stroke', 'stroke-width', 'stroke-linecap', 'stroke-linejoin', 'stroke-dasharray', 'opacity', 'transform', 'href', 'xlink:href', 'clip-path', 'mask', 'style' );

    $elements = $dom->getElementsByTagName( '*' );
    for ( $i = $elements->length - 1; $i >= 0; $i-- ) {
        $element = $elements->item( $i );
        if ( ! in_array( $element->tagName, $allowed_tags ) ) {
            $element->parentNode->removeChild( $element );
            continue;
        }
        for ( $j = $element->attributes->length - 1; $j >= 0; $j-- ) {
            $attribute = $element->attributes->item( $j );
            if ( ! in_array( $attribute->name, $allowed_attributes ) ) {
                $element->removeAttribute( $attribute->name );
            }
        }
    }

    file_put_contents( $file['tmp_name'], $dom->saveXML() );
    return $file;
}

This code defines a strict whitelist of allowed SVG elements and attributes. Anything not on the list gets stripped. The LIBXML_NOENT | LIBXML_DTDLOAD flags prevent XML External Entity (XXE) attacks during parsing. After cleaning, the sanitized XML is written back to the temporary file. This step is non-negotiable if you’re allowing SVGs on a site where multiple users have upload access.

Step 4: Ensure SVGs Display Correctly in the Block Editor

Even with the MIME type allowed and the media library fixed, the block editor can still choke on SVGs. The Image block expects a raster image with defined dimensions. When you insert an SVG, the block might set width and height to zero or fail to render the preview. The solution is to add a small CSS snippet that forces the editor to respect the SVG’s intrinsic aspect ratio and to output the raw SVG markup when appropriate.

Add this to your theme’s admin styles via admin_enqueue_scripts:

add_action( 'admin_enqueue_scripts', 'jooom_svg_admin_styles' );
function jooom_svg_admin_styles() {
    echo '<style>
        .components-responsive-wrapper__content[src$=".svg"] {
            width: 100% !important;
            height: auto !important;
        }
        .wp-block-image img[src$=".svg"] {
            width: 100%;
            height: auto;
        }
    </style>';
}

This targets SVG images inside the editor’s responsive wrapper and the image block, forcing them to scale properly. For more control, you can also filter the image block’s output on the front end to inline the SVG code, which allows CSS styling of individual SVG elements. That’s a more advanced technique, but the CSS fix above solves the immediate display issue.

Step 5: Handle SVG Dimensions and Responsiveness

SVGs don’t have a fixed pixel size like PNGs. They can scale infinitely, but WordPress and many themes try to assign explicit width and height attributes. This can lead to SVGs being displayed at 0x0 or stretched disproportionately. The earlier thumbnail fix sets dimensions to null, which helps, but you should also ensure that the img tag itself doesn’t get hardcoded dimensions from the theme or editor.

Add this filter to remove width and height attributes from SVG img tags on the front end:

add_filter( 'wp_get_attachment_image_attributes', 'jooom_remove_svg_dimensions', 10, 3 );
function jooom_remove_svg_dimensions( $attr, $attachment, $size ) {
    if ( get_post_mime_type( $attachment->ID ) === 'image/svg+xml' ) {
        unset( $attr['width'] );
        unset( $attr['height'] );
        $attr['class'] = isset( $attr['class'] ) ? $attr['class'] . ' svg-image' : 'svg-image';
    }
    return $attr;
}

This strips the width and height attributes and adds a svg-image class for targeted CSS. In your theme’s stylesheet, you can then set .svg-image { width: 100%; height: auto; } to make SVGs fill their container while maintaining aspect ratio. This is especially useful for logos and icons that need to adapt to different screen sizes.

Why a Code Solution Beats a Plugin for System Builders

Plugins are convenient, but they introduce variables you can’t always control. A plugin might be abandoned, conflict with a custom theme, or load assets on every page when you only need SVGs in a specific post type. By writing your own SVG support, you keep the logic transparent and minimal. You know exactly what’s allowed and what’s stripped. This matters when you’re building a site that will be handed off to a client or maintained by a team—you can document the exact behavior instead of pointing to a third-party plugin’s changelog.

There’s also a performance angle. Many SVG plugins add a settings page, enqueue scripts, or run sanitization on every page load. The code above only fires during upload and when preparing attachment data. It’s lean and event-driven. If you’re already maintaining a custom theme or a mu-plugin for client sites, this fits right in. You can even wrap the entire solution in a single class and conditionally load it only for users with the upload_files capability.

When SVGs Still Break: Debugging Common Edge Cases

Sometimes the file uploads but renders as a blank square. Here are the most common culprits and how to diagnose them:

1. The SVG Uses Inline Styles That Conflict with Theme CSS

If your SVG contains <style> blocks with generic class names like .st0, they can be overridden by your theme’s stylesheet. Open the SVG in a text editor and look for <style> tags. Either remove them and use presentation attributes instead, or namespace the classes. The sanitization function above doesn’t strip <style> tags because they’re valid SVG, but you can add 'style' to the disallowed tags list if you prefer to handle styling externally.

2. The SVG Contains External References

Elements like <image href="..."> or <use href="..."> can point to external resources. If those resources are blocked by a Content Security Policy or are unavailable, the SVG will break. Inspect the SVG code for any xlink:href or href attributes pointing to external URLs. Replace them with embedded data URIs or remove them if they’re not essential.

3. Server MIME Type Configuration

Even if WordPress accepts the file, your web server might not serve it with the correct Content-Type: image/svg+xml header. This is rare on modern hosts but can happen. Check the network tab in your browser’s developer tools when loading the SVG directly. If the MIME type is wrong, add AddType image/svg+xml .svg to your .htaccess file or contact your host.

FAQ

Is it safe to allow SVG uploads on a client site?

Yes, if you implement sanitization. The code in Step 3 strips scripts and event handlers, which are the primary attack vectors. For high-security sites, you can also restrict SVG uploads to administrators only by wrapping the MIME type filter in a capability check: if ( current_user_can( 'manage_options' ) ). This limits the risk to trusted users.

Why does my SVG look blurry in the media library even after the fix?

The media library grid view uses a fixed thumbnail size. If your SVG has a complex design with thin lines, it might appear aliased when scaled down. This is a rendering issue, not a code problem. The SVG itself is still sharp at its native size. You can improve the preview by ensuring your SVG has a clear viewBox and uses stroke widths that hold up at small sizes.

Can I use this approach on a multisite network?

Yes, but with caution. On a multisite, the upload_mimes filter applies network-wide unless you conditionally load it per site. You can place the code in a mu-plugin and use get_current_blog_id() to enable SVG support only for specific sites. The sanitization function should always run regardless, to protect the entire network.

What if I need to allow more SVG elements for complex illustrations?

The allowed tags and attributes arrays in the sanitization function are a starting point. You can add elements like <filter>, <feGaussianBlur>, or <animate> if your use case requires them. Be aware that <animate> and <script> are high-risk. Only whitelist what you absolutely need, and test thoroughly.

Building a Reliable SVG Workflow

Once SVGs are working, treat them like any other asset in your build pipeline. Optimize them with tools like SVGO before uploading. Keep a master folder of source SVGs outside WordPress so you can re-upload if needed. If you’re using a version control system for your theme, consider storing critical SVGs directly in the theme and referencing them via get_template_directory_uri() instead of the media library. This bypasses the upload process entirely and gives you full control over the files.

For sites that rely heavily on SVGs—icon systems, data visualizations, interactive maps—this code-based approach scales better than a plugin. You can extend the sanitization to log rejected elements, add a custom capability for SVG uploads, or integrate with a CDN that serves SVGs with immutable caching headers. The foundation is solid, and the code is yours to adapt.

If you’re dealing with other WordPress quirks, like a fresh install that returns nothing but a blank page, the same systematic mindset applies. Check your permalinks, your .htaccess, and your reading settings before reaching for a plugin. I’ve written about that exact scenario in What to Fix First When a New WordPress Site Says Nothing Found. The principle is the same: understand the system, then write the smallest possible fix.

SVGs are a core part of modern web design. WordPress’s default stance is conservative, but with a few well-placed hooks, you can unlock their full potential without compromising security or performance. The code above has been running on client sites for years without issues. Copy it, adapt it, and get back to building.

You shipped a custom WordPress theme. The client logs in, tweaks the header color, adds a widget, and maybe even edits a template file straight from the Appearance Editor. Meanwhile, you’re pushing structural changes from your local Git branch. What you get: merge conflicts, overwritten work, and a production site that drifts further from your canonical codebase every single week.

This isn’t a discipline problem. It’s a systems problem. Clients will always need to make small, immediate changes. Your job is to build a version-control workflow that absorbs that reality without breaking the theme’s integrity. Here’s the exact stack and strategy I use to keep client-edited themes under Git control—without locking them out of the tools they expect.

Why Standard Git + WordPress Theme Workflows Break

In a typical software project, the production environment is a read-only mirror of the repository. WordPress flips that assumption. The theme directory is live, writable, and exposed to both the WordPress admin UI and FTP-based editing if the client has hosting access. A standard git push to production will either overwrite client changes or fail because of uncommitted modifications on the server.

The core tension sits between two types of change:

• Structural changes — PHP logic, template architecture, custom post type registrations, and CSS framework updates. These come from you, the developer, and belong in version control.
• Cosmetic and content-adjacent changes — Color tweaks, font choices, widget placements, and minor template text edits. These come from the client and often happen through the Customizer, block editor settings, or direct file edits.

If you treat every production file as sacred, you’ll spend hours manually reconciling diffs. If you lock the client out of the theme editor entirely, you’ll get support tickets asking why they can’t change their own site. The solution is a deliberate separation of concerns baked into the theme architecture and deployment pipeline.

Architect the Theme for Safe Client Edits

Before touching Git, you need a theme structure that limits where client edits can land. This isn’t about restricting freedom—it’s about defining clear boundaries so both sides know which files are “developer territory” and which are “client territory.”

Use a Child Theme for Client-Exposed Files

Ship your core theme as a parent. Give the client a child theme that inherits everything but overrides only specific files: style.css, functions.php, and perhaps a handful of template parts. The parent theme stays under strict Git control. The child theme becomes the client’s sandbox.

This works because WordPress’s template hierarchy checks the child theme first. If the client edits header.php in the child theme, that version loads. Your parent header.php remains untouched. When you push an update to the parent, the child’s override still takes precedence—but only for the files the client actually modified. Everything else pulls from your updated parent.

For CSS, encourage the client to use the Customizer’s Additional CSS panel or a child theme style.css that enqueues after the parent. Never let them edit the parent’s main stylesheet directly. A single misplaced edit there can cascade into layout breaks that are a pain to trace.

Lock Down Template Editing in Production

WordPress 5.9+ allows template editing through the Site Editor for block themes. For classic or hybrid themes, the Theme File Editor under Appearance remains a tempting trap. Disable it. Add this to your parent theme’s functions.php or a must-use plugin:

define( 'DISALLOW_FILE_EDIT', true );

This removes the editor from the admin menu entirely. Clients can still use the Customizer, widgets, and block settings—just not raw PHP files. If they need template-level changes, they go through the child theme or a controlled process you define.

Set Up a Git Repository That Respects Production Reality

Your local Git repo is the source of truth for the parent theme. The production server is a hybrid: it contains your deployed parent theme plus the client’s child theme and any database-stored settings. The goal is to version-control what you own while tracking what the client changes.

Repository Structure

I recommend a monorepo for the project, not just the theme. This lets you version-control custom plugins, mu-plugins, and even deployment scripts alongside the theme. A typical layout:

project-root/
├── themes/
│   ├── parent-theme/        ← Your Git-managed code
│   └── child-theme/         ← Client sandbox (tracked but not deployed from Git)
├── plugins/
├── mu-plugins/
└── deploy/

The child theme lives in the repo for reference and local development, but you never push it to production from your machine. Instead, production’s child theme is treated as a client-owned artifact. You pull it down periodically to audit and commit changes back to the repo for history.

Gitignore Strategy

Your .gitignore should exclude anything the client or WordPress core can modify on the server. For the parent theme, that’s minimal—maybe just node_modules and build artifacts. For the child theme, you might ignore everything except a baseline you initially provisioned. The key is to never let a git pull on production overwrite client work.

On the production server, the parent theme directory is a Git working copy, but it’s set to a detached HEAD or a specific tag. You deploy via git fetch and git checkout <tag>, not git pull. This avoids merge conflicts with any stray files. The child theme directory is not a Git working copy at all—it’s just a folder you sync manually or via a controlled script.

Deployment Pipeline That Preserves Client Edits

Pushing code to a live site where files can change independently requires a one-way sync, not a bidirectional merge. Here’s the deployment sequence I use:

1. Tag a release in your local repo: git tag v1.2.0 and push the tag.
2. On production, fetch tags: git fetch --tags.
3. Checkout the tag for the parent theme directory: git checkout v1.2.0. This updates only tracked files and leaves untracked or ignored files alone.
4. Run a post-deploy script that compares the production child theme against your repo’s child-theme baseline. If the client added custom templates or CSS, the script logs the differences and optionally commits them to a separate branch in your repo for auditing.

This approach means your parent theme updates are atomic and conflict-free. The client’s child theme modifications survive because they live outside the Git working copy’s tracked scope. You get a clean audit trail of what the client changed, and you can merge those changes back into the development branch if they’re worth keeping permanently.

Handling Database-Stored Theme Modifications

Not all client edits land in files. The Customizer saves settings—colors, typography, layout options—to the wp_options table under theme_mods_<theme-slug>. These are part of the theme’s runtime configuration but exist entirely outside the file system. Version-controlling them requires a different tactic.

Export Theme Mods as JSON

Write a small WP-CLI script or a custom plugin that exports theme mods to a JSON file on demand. Run it before each deployment and commit the JSON to your repo as a snapshot of the client’s Customizer state. If a deployment accidentally resets these settings, you can re-import them with a companion WP-CLI command.

This also gives you a diffable artifact. When the client says “the site looks different after your update,” you can compare the pre- and post-deployment JSON to see if a Customizer setting was overwritten or if a CSS specificity change in your update caused a visual shift.

Use Theme Mods Sparingly in the Parent Theme

If your parent theme stores layout-critical values in theme mods, a client can break the design by changing a number field from 4 to 40. Reserve theme mods for truly user-facing options—logo, accent color, typography scale—and validate them aggressively in the theme’s output. For structural settings like grid breakpoints or container widths, hardcode them in the parent theme or pull from a controlled options page that clients can’t access.

Child Theme Versioning and Client Collaboration

The child theme is the client’s playground, but it still needs version control for your sanity. I treat the production child theme as a separate Git repository—or at least a separate branch—that the client never touches directly. Instead, I pull a copy of their live child theme into my local environment periodically, review the changes, and commit them with clear messages like “Client added custom header template 2024-03-15.”

This gives you a full history of client edits without exposing them to Git. If they break something, you can diff against the last known-good state and revert selectively. It also means you can test your parent theme updates against their actual child theme overrides before deploying, catching conflicts in a staging environment rather than on the live site.

Automate the Pull with a Cron Job

Set up a weekly cron on the production server that zips the child theme and pushes it to a private cloud storage bucket or a dedicated Git branch via a deploy key. You pull that snapshot into your local environment, review the diff, and decide what to keep. This keeps the audit trail current without requiring manual FTP downloads every time you need to check on client changes.

When the Client Edits Parent Theme Files Anyway

Despite your best architecture, a client with admin access might still edit a parent theme file directly—especially if they have hosting-level access and use FTP. You need a detection mechanism, not a prevention mechanism, because prevention at the file-system level on shared hosting is fragile.

Integrity Checking with Checksums

After each deployment, generate a checksum manifest of all parent theme files. Store it outside the theme directory. On a regular cron job, compare the current files against the manifest. If a mismatch is found, log it and optionally email you. This turns a silent overwrite into a detectable event.

You can also use Git’s own integrity checking on the production parent theme directory. Since the directory is a Git working copy, git status will show modified tracked files. A simple script that runs git status --porcelain and alerts on unexpected changes gives you near-real-time visibility into client tampering.

Recovering from a Client Edit That Broke the Site

Even with checksums and alerts, you’ll eventually get the panicked email: “I changed something and now the site is down.” Your recovery process should be fast and not rely on sifting through Git history while the client watches.

First, if the parent theme is the problem, git checkout <last-good-tag> in the parent theme directory restores it instantly. The child theme is trickier because it’s not under Git control on the server. Keep a known-good backup of the child theme in a separate directory on the server—just a dated copy of the entire child theme folder from the last audit. A simple shell script can swap the broken child theme with the backup in seconds.

For Customizer-related breakage, the WP-CLI command wp option get theme_mods_<child-slug> retrieves the current settings. You can compare that to your pre-deployment JSON snapshot and selectively reset individual mods without wiping everything.

FAQ

Should I completely disable the WordPress file editor?

Yes, for the parent theme. Add define( 'DISALLOW_FILE_EDIT', true ); to your wp-config.php or a must-use plugin. This removes the Appearance → Theme File Editor and Plugins → Plugin File Editor menus. It doesn’t affect the Customizer, block editor, or media uploads, so clients can still manage visual settings and content. If they need to edit template files, they should do it through a child theme you’ve set up for them.

How do I handle version control when the client uses a page builder?

Page builders like Elementor or Beaver Builder store most design data in the database, not theme files. Your theme’s job is to provide a clean canvas and well-structured hooks. Version-control the parent theme as usual. For the builder data, use a migration plugin or WP-CLI to export builder settings and layouts to JSON files, then commit those to your repo as design snapshots. This gives you a history of page-level changes without touching the live database.

Can I use a staging site to let clients preview theme updates before they go live?

Absolutely, and it’s a practice I recommend. Push your parent theme update to a staging environment first, then sync the client’s child theme and Customizer settings from production to staging. Let the client review the staging site. Once approved, you deploy the parent theme tag to production and re-import the Customizer settings if needed. This catches conflicts between your new code and their customizations before they affect the live site. For more on staging workflows, see What to Fix First When a New WordPress Site Says Nothing Found for related debugging patterns.

Building a Client-Ready Theme Update Dashboard

For clients who want more control without direct file access, build a simple theme update interface into the WordPress admin. This isn’t about letting them edit code—it’s about giving them a safe way to trigger updates and see what changed.

Create a custom admin page that displays the current parent theme version, the latest available version from your Git tags, and a changelog pulled from your repository’s release notes. Add a one-click update button that runs your deployment script behind the scenes. This gives the client agency without exposing them to Git or the file system.

Under the hood, the button triggers a server-side script that fetches the latest tag, checks it out in the parent theme directory, and logs the update. If the child theme has conflicts, the script can pause and notify you rather than breaking the site. This turns theme updates into a managed service rather than a surprise.

Long-Term Maintenance: When the Client’s Child Theme Becomes the De Facto Theme

Over years, a client’s child theme can accumulate so many overrides that it essentially becomes the primary theme. At that point, the parent-child relationship is more about update safety than code inheritance. Your version-control strategy needs to adapt.

Consider promoting the child theme to a standalone theme in your repo, with the original parent becoming a library or framework that you version separately. This flips the dependency: the client’s theme imports your framework as a Composer package or Git submodule, and updates are explicit version bumps they approve. It’s more work to set up, but for long-lived sites with heavy customization, it eliminates the tension entirely.

Summary Workflow Checklist

Here’s the end-to-end process I use on every client project where the client has production access:

1. Ship a parent theme with a pre-built child theme skeleton.
2. Disable the file editor in wp-config.
3. Deploy parent theme tags via git checkout, never git pull.
4. Export theme mods as JSON before each deployment.
5. Run integrity checks on parent theme files weekly.
6. Pull the production child theme into a local audit branch regularly.
7. Provide a one-click update dashboard for non-technical clients.

This stack keeps your Git history clean, your client empowered, and your production theme stable—even when someone edits a file at 11 p.m. on a Friday.

FAQ

What if the client insists on editing the parent theme directly?

Explain the risks in terms they care about: future updates will overwrite their changes, and security patches will be delayed because you can’t safely deploy. Then offer a compromise: move their desired edits into the child theme for them. Most clients agree once they understand the cost of maintaining a forked parent theme. If they still refuse, set up the integrity monitoring and treat the parent theme as a fork in your repo, merging their changes into a client-specific branch.

How do I version-control block theme templates when clients use the Site Editor?

Block theme templates are stored as HTML files in the theme’s templates and parts directories. When a client edits them in the Site Editor, WordPress saves the modified templates to the database, not the file system. Your file-based templates remain untouched. To version-control these edits, export the database-saved templates using WP-CLI or a custom script, convert them to HTML files, and commit them to a client-templates directory in your repo. This gives you a history of their Site Editor changes without touching your canonical template files.

Is it safe to use Git on a production server with shared hosting?

Yes, if you limit Git to the parent theme directory and use a detached HEAD or tag checkouts. Most shared hosts allow shell access or Git via SSH. If not, you can deploy via a script that downloads a tarball of the tagged release from your Git host (GitHub, GitLab, Bitbucket) and extracts it to the theme directory. The key is to never run git pull on a directory where uncommitted changes might exist. Always use a clean checkout of a specific tag.

You drag a crisp SVG into the media library. The preview spins. Then WordPress throws the error: “Sorry, this file type is not permitted for security reasons.” Or worse—it uploads, but your icon renders as a broken thumbnail, or the file silently strips your carefully tuned viewBox. If you’ve been handed a design system that depends on scalable vector icons, this moment is a quiet rage trigger. I’ve hit it on three client builds this year alone. The good news: you don’t need a plugin to fix it. You need to understand what WordPress is actually rejecting and why—then patch the behavior at the right layer.

The Real Reason WordPress Blocks Your SVG

WordPress isn’t being stubborn. SVGs are XML documents, not flat images. An SVG file can carry inline scripts, event handlers, and external entity references—vectors for cross-site scripting (XSS) and XML entity expansion attacks. The core team’s default posture is to treat every SVG as potentially hostile. That’s why the allowed file type list in wp-includes/functions.php omits svg and svgz entirely. The MIME check fails, and the uploader rejects the file before it ever touches the media library.

But the security concern is only half the story. Even if you force the upload through, WordPress’s image subsystem doesn’t understand vector data. There’s no width/height extraction from the XML tree, no thumbnail generation, and no metadata parsing. The media modal shows a blank document icon because the attachment metadata array is empty. That’s a design gap, not a security feature—and it’s one you can bridge with a few lines of PHP that respect the security boundary.

What Actually Breaks: MIME Validation, Metadata, and Rendering

Three distinct failures stack up when you try to upload an SVG without preparation. First, the wp_check_filetype_and_ext filter runs a MIME-type lookup against a hardcoded map. SVGs often arrive with image/svg+xml, which isn’t in the map. Second, even if the file passes the type gate, the attachment metadata generator—wp_generate_attachment_metadata—returns nothing useful for XML-based files. No width, no height, no thumbnail crop data. Third, the media library preview relies on that metadata to display a thumbnail. Without it, you get the broken document icon. The file is there, but WordPress doesn’t know how to show it.

Step 1: Allow the MIME Type Without Opening the Floodgates

The cleanest entry point is the upload_mimes filter. It lets you add svg to the allowed list before the type checker runs. But don’t stop there. Pair it with a server-side sanitization step that strips scripts, event handlers, and foreign objects from the XML before the file lands in the uploads directory. This keeps the security boundary intact while granting designers the format they need.

add_filter( 'upload_mimes', function( $mimes ) {
    $mimes['svg'] = 'image/svg+xml';
    return $mimes;
});

That snippet alone gets you past the upload gate. But it doesn’t sanitize the file, and it doesn’t fix the preview. For a production site, you need a second filter that intercepts the file during the upload prefilter phase. Hook into wp_handle_upload_prefilter and run the SVG through DOMDocument, stripping <script> tags, onload attributes, and any namespace you don’t explicitly trust. This is the same approach used by well-audited SVG sanitizer libraries, but you can implement a minimal version that covers 95% of real-world icon files without pulling in a dependency.

add_filter( 'wp_handle_upload_prefilter', function( $file ) {
    if ( 'image/svg+xml' !== $file['type'] ) {
        return $file;
    }
    $svg = file_get_contents( $file['tmp_name'] );
    $dom = new DOMDocument();
    $dom->loadXML( $svg, LIBXML_NOENT | LIBXML_NSCLEAN );
    $allowed_elements = [ 'svg', 'g', 'path', 'circle', 'rect', 'line', 'polyline', 'polygon', 'ellipse', 'defs', 'use', 'title', 'desc' ];
    $allowed_attrs    = [ 'viewBox', 'xmlns', 'd', 'fill', 'stroke', 'stroke-width', 'cx', 'cy', 'r', 'x', 'y', 'width', 'height', 'transform', 'id', 'class' ];
    $xpath = new DOMXPath( $dom );
    foreach ( $xpath->query( '//*' ) as $node ) {
        if ( ! in_array( $node->nodeName, $allowed_elements, true ) ) {
            $node->parentNode->removeChild( $node );
            continue;
        }
        for ( $i = $node->attributes->length - 1; $i >= 0; $i-- ) {
            $attr = $node->attributes->item( $i );
            if ( ! in_array( $attr->name, $allowed_attrs, true ) ) {
                $node->removeAttribute( $attr->name );
            }
        }
    }
    file_put_contents( $file['tmp_name'], $dom->saveXML() );
    return $file;
});

This filter runs before the file is moved to the uploads directory. It strips anything that isn’t a structural or presentational SVG element. If your icons come from a trusted design pipeline—Figma exports, Illustrator artboards with “presentation attributes” enabled—this sanitizer won’t touch the visual output. It only removes the dangerous cruft that some editors inject by default.

Step 2: Generate Attachment Metadata So Thumbnails Work

Once the SVG is stored, WordPress tries to build metadata by calling wp_generate_attachment_metadata. For raster images, this extracts dimensions and creates sub-sizes. For SVGs, it returns an empty array because the function relies on PHP’s getimagesize(), which doesn’t parse XML. The fix is to hook into wp_generate_attachment_metadata and supply the missing width and height directly from the SVG’s viewBox or width/height attributes.

add_filter( 'wp_generate_attachment_metadata', function( $metadata, $attachment_id ) {
    $mime = get_post_mime_type( $attachment_id );
    if ( 'image/svg+xml' !== $mime ) {
        return $metadata;
    }
    $file = get_attached_file( $attachment_id );
    $svg  = simplexml_load_file( $file );
    $attr = $svg->attributes();
    $viewBox = explode( ' ', (string) $attr->viewBox );
    if ( count( $viewBox ) === 4 ) {
        $width  = intval( $viewBox[2] );
        $height = intval( $viewBox[3] );
    } elseif ( isset( $attr->width, $attr->height ) ) {
        $width  = intval( $attr->width );
        $height = intval( $attr->height );
    } else {
        return $metadata;
    }
    $metadata['width']  = $width;
    $metadata['height'] = $height;
    $metadata['file']   = basename( $file );
    return $metadata;
}, 10, 2 );

With this in place, the media library reads the dimensions and renders a proper preview. The SVG still won’t generate cropped thumbnails—WordPress’s image editor can’t resize vectors—but the full-size preview becomes usable. For most icon and illustration workflows, that’s enough.

Step 3: Fix the Media Library Preview Display

Even with correct metadata, the media library grid uses wp_get_attachment_image, which wraps the file in an <img> tag. Browsers render SVGs fine in <img> elements, but WordPress’s responsive image logic adds srcset and sizes attributes that reference non-existent thumbnail files. The result is a broken image or a fallback to the generic document icon. You can intercept this with the wp_get_attachment_image_src filter, returning only the full-size URL for SVGs.

add_filter( 'wp_get_attachment_image_src', function( $image, $attachment_id, $size, $icon ) {
    if ( 'image/svg+xml' === get_post_mime_type( $attachment_id ) ) {
        $file = get_attached_file( $attachment_id );
        if ( $file ) {
            $image[0] = wp_get_attachment_url( $attachment_id );
            $image[1] = null;
            $image[2] = null;
        }
    }
    return $image;
}, 10, 4 );

This filter strips the width and height from the image downsize logic, forcing the browser to render the SVG at its natural aspect ratio. If you need the SVG to scale within a specific container, handle that with CSS max-width: 100%; height: auto; on the front end—don’t rely on WordPress to generate raster fallbacks that don’t exist.

When You Should Still Avoid SVGs in the Library

This approach works for design-forward sites where the SVG is the final asset: logos, icons, spot illustrations. It’s not a good fit if you expect non-technical content editors to upload arbitrary SVGs from the web. The sanitizer above is minimal; it won’t catch every edge case in a user-submitted file. If your workflow involves untrusted SVG sources, you need a full XML security library—and at that point, a vetted plugin that wraps such a library is the safer architectural choice. But for a controlled build pipeline where you or your designers own the source files, the code above keeps your functions.php lean and your dependency tree short.

Putting It All Together: A Single mu-plugin File

I prefer to bundle SVG support as a must-use plugin rather than scattering filters across a theme’s functions.php. This keeps the logic portable and independent of theme switches. Create a file at wp-content/mu-plugins/svg-upload.php with all three filters. The mu-plugin directory loads automatically, so you don’t need to activate anything. Here’s the complete file structure:

<?php
/**
 * Plugin Name: SVG Upload Support (No Plugin)
 * Description: Enables sanitized SVG uploads and fixes media preview without a third-party plugin.
 * Author: Jonas Venn
 */

// 1. Allow SVG MIME type
add_filter( 'upload_mimes', function( $mimes ) {
    $mimes['svg'] = 'image/svg+xml';
    return $mimes;
});

// 2. Sanitize SVG on upload
add_filter( 'wp_handle_upload_prefilter', function( $file ) {
    if ( 'image/svg+xml' !== $file['type'] ) {
        return $file;
    }
    $svg = file_get_contents( $file['tmp_name'] );
    $dom = new DOMDocument();
    $dom->loadXML( $svg, LIBXML_NOENT | LIBXML_NSCLEAN );
    $allowed_elements = [ 'svg', 'g', 'path', 'circle', 'rect', 'line', 'polyline', 'polygon', 'ellipse', 'defs', 'use', 'title', 'desc' ];
    $allowed_attrs   = [ 'viewBox', 'xmlns', 'd', 'fill', 'stroke', 'stroke-width', 'cx', 'cy', 'r', 'x', 'y', 'width', 'height', 'transform', 'id', 'class' ];
    $xpath = new DOMXPath( $dom );
    foreach ( $xpath->query( '//*' ) as $node ) {
        if ( ! in_array( $node->nodeName, $allowed_elements, true ) ) {
            $node->parentNode->removeChild( $node );
            continue;
        }
        for ( $i = $node->attributes->length - 1; $i >= 0; $i-- ) {
            $attr = $node->attributes->item( $i );
            if ( ! in_array( $attr->name, $allowed_attrs, true ) ) {
                $node->removeAttribute( $attr->name );
            }
        }
    }
    file_put_contents( $file['tmp_name'], $dom->saveXML() );
    return $file;
});

// 3. Generate attachment metadata for preview dimensions
add_filter( 'wp_generate_attachment_metadata', function( $metadata, $attachment_id ) {
    if ( 'image/svg+xml' !== get_post_mime_type( $attachment_id ) ) {
        return $metadata;
    }
    $file = get_attached_file( $attachment_id );
    $svg  = simplexml_load_file( $file );
    $attr = $svg->attributes();
    $viewBox = explode( ' ', (string) $attr->viewBox );
    if ( count( $viewBox ) === 4 ) {
        $width  = intval( $viewBox[2] );
        $height = intval( $viewBox[3] );
    } elseif ( isset( $attr->width, $attr->height ) ) {
        $width  = intval( $attr->width );
        $height = intval( $attr->height );
    } else {
        return $metadata;
    }
    $metadata['width']  = $width;
    $metadata['height'] = $height;
    $metadata['file']   = basename( $file );
    return $metadata;
}, 10, 2 );

// 4. Prevent srcset generation for SVGs in media views
add_filter( 'wp_get_attachment_image_src', function( $image, $attachment_id, $size, $icon ) {
    if ( 'image/svg+xml' === get_post_mime_type( $attachment_id ) ) {
        $file = get_attached_file( $attachment_id );
        if ( $file ) {
            $image[0] = wp_get_attachment_url( $attachment_id );
            $image[1] = null;
            $image[2] = null;
        }
    }
    return $image;
}, 10, 4 );

Drop this file into wp-content/mu-plugins/ and your SVG uploads will work. No plugin updates to track, no license keys, no compatibility breaks when Gutenberg shifts its media handling again. You own the logic.

Testing the Pipeline with Real SVGs

After adding the mu-plugin, test with a few SVG variants. Start with a minimal icon exported from Figma using the “SVG” preset with “presentation attributes” styling. The file should upload, display a thumbnail in the media library, and render correctly in a post or page. Next, test an SVG that contains inline styles and a <script> tag—something you might accidentally get from a stock icon site. The sanitizer should strip the script and any style attributes not in the allowed list, while preserving the visual output. Finally, test an SVG with explicit width and height attributes but no viewBox. The metadata filter should fall back to those values and still produce a working preview.

If the thumbnail still shows a document icon, check that your SVG has either a valid viewBox or explicit width/height attributes. The metadata filter depends on at least one of these being present. SVGs without dimensional data will fall through and return an empty metadata array, which triggers the fallback icon.

Handling the Frontend Display

Once the file is in the library, you’ll likely use it in blocks, shortcodes, or template code. The native Image block works, but it wraps the SVG in an <img> tag. That’s fine for most cases, but you lose the ability to style the SVG’s internal elements with CSS. If you need dynamic fill colors or hover states on individual paths, inline the SVG directly into your template using file_get_contents and echo it inside a container div. This gives you full CSS control over the vector DOM. Just make sure you’re pulling from a trusted source—your own media library, after sanitization.

For block-based themes, you can register a custom block that pulls the attachment URL and inlines the SVG markup server-side. That’s a larger build, but the foundation you’ve laid with the mu-plugin makes it possible. The attachment is clean, the metadata is present, and the file is accessible via wp_get_attachment_url.

Why This Beats Installing a Plugin

There are several well-known SVG support plugins. They work. But they also add admin menus, settings pages, and sometimes their own sanitizer libraries that duplicate what PHP’s DOMDocument already does. On a site where you’re already managing a custom theme and a handful of mu-plugins, adding another plugin for a single file type is overhead. The code above is 60 lines, fully auditable, and does exactly what you need—nothing more. When WordPress core eventually adds native SVG handling (it’s been discussed for years), you can remove the mu-plugin without untangling a plugin’s database options.

This approach also aligns with how I handle other WordPress quirks. When a new site returns “Nothing Found” for every permalink, I don’t install a plugin—I check the rewrite rules and flush them. The same builderly mindset applies here: understand the mechanism, then write the smallest possible fix. If you’re dealing with that permalink issue, I’ve written a separate guide on what to fix first when a new WordPress site says nothing found that follows the same philosophy.

Security Notes for Production

The sanitizer above uses a whitelist approach: it removes anything not explicitly allowed. This is safer than blacklisting known-bad elements because it protects against future SVG attack vectors that haven’t been cataloged yet. The LIBXML_NOENT flag prevents entity expansion attacks. The LIBXML_NSCLEAN flag removes redundant namespace declarations. Together, they harden the XML parsing step.

If your site allows user registrations with upload capabilities, consider adding a capability check before the MIME filter runs. You can restrict SVG uploads to administrators and editors by wrapping the upload_mimes filter in a current_user_can( 'edit_posts' ) conditional. For most brochure sites and portfolios, this isn’t necessary—the uploader is already gated behind authentication.

When the Fix Doesn’t Stick: Debugging Checklist

If you’ve added the mu-plugin and SVGs still fail, work through this list:

• File encoding: The SVG must be valid XML. Open it in a text editor and check for BOM characters or HTML entities that break the parser.
• PHP DOM extension: The sanitizer requires DOMDocument and DOMXPath. These are enabled by default in most PHP builds, but some minimal hosting setups disable them. Verify with phpinfo().
• mu-plugin loading order: Must-use plugins load before regular plugins and themes. If another plugin is filtering upload_mimes with a higher priority and removing your addition, you’ll need to adjust the priority or find the conflict.
• File permissions: The uploads directory must be writable. If the file moves but the metadata filter can’t read it back, check ownership and permissions.
• Caching layer: If you use a CDN or object cache, flush it after adding the mu-plugin. Stale MIME-type lists can survive in opcode caches.

Extending the Approach for SVGZ and Inline Use

Compressed SVG files (.svgz) are gzipped SVGs. To support them, add svgz to the MIME map with image/svg+xml and decompress the file before sanitization. The wp_handle_upload_prefilter can check the extension and run gzdecode before passing the XML to DOMDocument. For inline SVG use in templates, you can skip the upload flow entirely and store SVG strings as theme options or custom post meta—but then you lose the media library’s organizational benefits. The mu-plugin approach keeps the asset in the library where it belongs.

FAQ

Is it safe to allow SVG uploads on a client site?

Yes, if you sanitize the file on upload and restrict upload capabilities to trusted roles. The sanitizer in this guide strips scripts, event handlers, and foreign objects. Combined with WordPress’s existing authentication layer, this is safe for sites where only administrators and editors can upload files.

Why does my SVG thumbnail still show a broken icon after adding the code?

The most common cause is a missing viewBox or width/height attribute in the SVG file. The metadata filter needs at least one of these to extract dimensions. Open the SVG in a text editor and confirm the root <svg> element has a viewBox (e.g., viewBox="0 0 24 24") or explicit width and height.

Can I use this method with the block editor’s Image block?

Yes. The Image block will display the SVG using an <img> tag. The wp_get_attachment_image_src filter prevents broken srcset references. If you need to style the SVG’s internal paths with CSS, you’ll need to inline the SVG markup instead of using the Image block.

What happens when WordPress core eventually supports SVGs?

You can remove the mu-plugin. The filters are additive; they won’t conflict with native support because they only act on the SVG MIME type. If core adds its own sanitization and metadata handling, your filters may become redundant, but they won’t break anything.

SVG uploads don’t have to be a fragile workaround. With a single mu-plugin file, you get sanitized uploads, working previews, and a media library that treats vectors as first-class assets. The code is yours to audit, extend, and remove when it’s no longer needed. That’s the builder’s way.