Yoast SEO Filters: Customizing SEO Data in WordPress

Yoast SEO is one of the most popular WordPress plugins for optimizing website content for search engines. However, developers often need to customize the data Yoast generates – such as titles, meta descriptions, or breadcrumbs – to fit specific use cases.

In this guide, you’ll learn how to use Yoast SEO filters to manipulate SEO data dynamically in WordPress themes and plugins.

What Are Yoast Filters?

Filters in WordPress allow you to modify or add to the output of WordPress functions. Yoast SEO provides several filters that developers can hook into, making it possible to customize the SEO data it generates.

Common filters include wpseo_title for modifying titles, wpseo_metadesc for customizing meta descriptions, and wpseo_canonical for changing canonical URLs.

Tip: Filters are an essential part of WordPress development. Understanding them can significantly expand your customization capabilities beyond what the Yoast SEO admin panel offers.

Best Practices for Using Yoast Filters

When using Yoast filters, adhering to best practices ensures that your customizations are effective, maintainable, and error-free.

Filters provide significant flexibility, but they also require careful implementation to avoid unintended consequences. Incorrect SEO data or performance issues can result from poorly written filter callbacks.

The following tips will help you optimize your use of Yoast filters:

• Use Conditionals: Leverage WordPress conditionals like is_singular() or is_category() to target specific pages or content types.
• Test Changes: Use browser developer tools to inspect titles and meta tags after adding filters.
• Use Debugging Tools: Validate Open Graph or schema changes using tools like Google’s Rich Results Test.
• Set Filter Priority: Use the third parameter of add_filter() to control when your filter runs relative to others. A higher number means it runs later.
• Check Yoast Version Compatibility: Some filters changed behavior in Yoast SEO 14.0+. Always test your filters after updating the plugin.

Practical Examples for using Yoast Filters

Yoast SEO provides filters to customize titles, meta descriptions, canonical URLs, and more. Below are practical examples to help you tailor its output to your SEO strategy.

1. Modifying SEO Titles

Customizing the titles generated by Yoast can help improve clarity or align them with specific SEO strategies. The wpseo_title filter lets you modify the <title> tag output.

Example 1: Append the Site Name to Titles

function custom_yoast_title( $title ) {
    return $title . ' | My Custom Site';
}
add_filter( 'wpseo_title', 'custom_yoast_title' );

Explanation: This appends the site name to all titles generated by Yoast, ensuring consistent branding.

Example 2: Add Pagination Information

function custom_pagination_title( $title ) {
    if ( is_paged() ) {
        $paged = get_query_var( 'paged' ) ? get_query_var( 'paged' ) : 1;
        return $title . ' - Page ' . $paged;
    }
    return $title;
}
add_filter( 'wpseo_title', 'custom_pagination_title' );

Explanation: This function appends the current page number to the title on paginated content. It helps search engines and users distinguish between different pages of the same archive.

2. Customizing Meta Descriptions

Meta descriptions play a vital role in search engine click-through rates. The wpseo_metadesc filter lets you override or modify the description Yoast generates.

Example: Add Category Descriptions

function custom_meta_description( $description ) {
    if ( is_category() ) {
        $category = get_queried_object();
        return $category->description ? $category->description : $description;
    }
    return $description;
}
add_filter( 'wpseo_metadesc', 'custom_meta_description' );

Explanation: This dynamically replaces the meta description with the category description on category archive pages. If the category has no description set, it falls back to the default Yoast output.

3. Customizing Open Graph Data for Social Sharing

Open Graph data ensures that your content appears correctly when shared on social platforms like Facebook or LinkedIn.

In earlier versions of Yoast SEO, you could use filters like wpseo_opengraph_title and wpseo_opengraph_desc to modify OG tags directly. However, these filters were deprecated in Yoast SEO 14.0.

The recommended approach is now to use Yoast’s wpseo_title filter (which also affects the OG title by default) or the Metadata API for more granular control. For OG images, the wpseo_opengraph_image filter is still available:

function custom_og_image( $image ) {
    if ( is_front_page() ) {
        return 'https://example.com/images/homepage-og.jpg';
    }
    return $image;
}
add_filter( 'wpseo_opengraph_image', 'custom_og_image' );

Explanation: This sets a custom Open Graph image for the homepage. The wpseo_opengraph_image filter remains supported in current versions of Yoast SEO.

Pro Tip: Always test your Open Graph data using Facebook’s Sharing Debugger or LinkedIn’s Post Inspector to verify that your customizations render correctly.

4. Excluding Yoast Data on Specific Pages

Sometimes you need to remove Yoast’s meta output from certain pages, such as landing pages with their own SEO setup.

function exclude_yoast_meta( $meta ) {
    if ( is_page_template( 'landing-page.php' ) ) {
        return '';
    }
    return $meta;
}
add_filter( 'wpseo_metadesc', 'exclude_yoast_meta' );

Explanation: This removes Yoast meta descriptions from pages using a specific template, such as landing pages where you manage SEO independently.

5. Adding Custom Canonical URLs

The wpseo_canonical filter lets you override the canonical URL Yoast generates. You can also return false to remove the canonical tag entirely.

function custom_canonical_url( $canonical ) {
    if ( is_singular( 'custom_post_type' ) ) {
        return 'https://example.com/custom-url/';
    }
    return $canonical;
}
add_filter( 'wpseo_canonical', 'custom_canonical_url' );

Explanation: This sets a custom canonical URL for posts of a specific post type. This is useful when content is syndicated or when you need to point search engines to a preferred version of a page.

Yoast filters can be invaluable for addressing real-life scenarios where default SEO settings need customization. Here are additional use cases where you might need these filters:

6. Modifying Breadcrumbs for Specific Pages

Breadcrumbs improve navigation and provide context to users and search engines. The wpseo_breadcrumb_links filter gives you access to the full breadcrumb array.

function custom_breadcrumbs( $breadcrumbs ) {
    if ( is_page( 'about-us' ) ) {
        $breadcrumbs[1]['text'] = 'Who We Are';
    }
    return $breadcrumbs;
}
add_filter( 'wpseo_breadcrumb_links', 'custom_breadcrumbs' );

Explanation: This code modifies the breadcrumb text for the “About Us” page. The $breadcrumbs parameter is a multi-dimensional array where each element contains url, text, and optionally term_id or id keys.

7. Dynamically Adjusting Robots Meta Tags

For SEO purposes, you might need to prevent specific pages from being indexed or followed.

Since Yoast SEO 14.0, the wpseo_robots filter receives an associative array instead of a string. The keys are directive names and the values are typically boolean true:

function custom_robots_meta( $robots ) {
    if ( is_post_type_archive( 'events' ) ) {
        $robots['noindex'] = true;
        $robots['nofollow'] = true;
    }
    return $robots;
}
add_filter( 'wpseo_robots', 'custom_robots_meta' );

Explanation: This adds noindex and nofollow directives for the archive of a custom post type called “events,” preventing it from appearing in search engine results.

8. Customizing Open Graph Descriptions

If you need to customize the Open Graph description for specific content types, you can use the wpseo_metadesc filter combined with OG-specific logic, or use the Metadata API for full control.

Here is an example using the meta description filter to affect OG output:

function custom_event_description( $description ) {
    if ( is_singular( 'events' ) ) {
        $event_date = get_post_meta( get_the_ID(), 'event_date', true );
        return 'Join us for this event on ' . $event_date . '. ' . $description;
    }
    return $description;
}
add_filter( 'wpseo_metadesc', 'custom_event_description' );

Explanation: This prepends event date information to the meta description for event posts. Since Yoast uses the meta description as a fallback for the OG description, this affects social sharing as well.

Modifying Schema Output with Yoast Filters

Yoast SEO generates structured data (Schema.org markup) automatically for your pages. You can customize this output using schema-specific filters.

The wpseo_schema_graph_pieces filter lets you add or remove graph pieces from the schema output:

function add_custom_schema_piece( $pieces, $context ) {
    $pieces[] = new My_Custom_Schema_Piece( $context );
    return $pieces;
}
add_filter( 'wpseo_schema_graph_pieces', 'add_custom_schema_piece', 10, 2 );

You can also disable all Yoast schema output by returning false from the wpseo_json_ld_output filter:

add_filter( 'wpseo_json_ld_output', '__return_false' );

This is useful when you manage schema markup through a different plugin or custom implementation.

Controlling XML Sitemap Output

Yoast SEO also provides filters for customizing its XML sitemap. You can exclude specific post types, taxonomies, or individual posts from the sitemap.

To exclude a custom post type from the sitemap:

function exclude_cpt_from_sitemap( $excluded, $post_type ) {
    if ( $post_type === 'internal_docs' ) {
        return true;
    }
    return $excluded;
}
add_filter( 'wpseo_sitemap_exclude_post_type', 'exclude_cpt_from_sitemap', 10, 2 );

To exclude specific posts by ID:

function exclude_posts_from_sitemap( $excluded_ids ) {
    $excluded_ids[] = 123;
    $excluded_ids[] = 456;
    return $excluded_ids;
}
add_filter( 'wpseo_exclude_from_sitemap_by_post_ids', 'exclude_posts_from_sitemap' );

These filters give you fine-grained control over what appears in your XML sitemap without modifying Yoast’s settings through the admin panel.

FAQs

Common questions about Yoast SEO filters:

Conclusion

Yoast SEO filters provide a powerful way to customize the SEO data generated by your WordPress site. Whether you’re modifying titles, meta descriptions, canonical URLs, robots directives, or schema markup, these filters give you full control over how Yoast handles your site’s SEO output.

Keep in mind that Yoast SEO continues to evolve. Major changes in version 14.0 deprecated several filters and introduced the Metadata API as the recommended approach for advanced customizations. Always test your filter code after plugin updates and consult the Yoast developer portal for the latest documentation.