Action Reference for The SEO Framework

Published on

Actions allow you to hook into TSF conditionally — to add content, checks, or other functionality at specific points in the plugin’s lifecycle.

We recommend against using actions if you aren’t an avid PHP developer. You must revalidate your implementation on every major release. As of v5.1.0, The SEO Framework registers over 60 actions.

Below you’ll find the most essential action hooks. Internal actions (used only by TSF itself) and metabox before/after pairs (used by Extension Manager) are not listed individually — for those, review the code. If you don’t know how actions work or where to place them, read our filter guide first; actions use the same registration pattern.

Plugin loaded

These action hooks fire on WordPress’s plugins_loaded at priority 5. They let you hook into TSF without checking function_exists( 'tsf' ). Because they run before the theme loads, you must register these in plugins (including mu-plugins).

/**
 * Runs after TSF is loaded in the admin.
 *
 * @since 3.1.0
 */
do_action( 'the_seo_framework_admin_loaded' );

/**
 * Runs after TSF is loaded.
 *
 * @since 3.1.0
 */
do_action( 'the_seo_framework_loaded' );

Use the_seo_framework_loaded when you need early access to the tsf() object — for example, to register a filter before TSF initializes. Use the admin variant when your code only applies to dashboard pages.

Example: register a filter early

add_action(
	'the_seo_framework_loaded',
	function () {

		add_filter(
			'the_seo_framework_title_from_generation',
			function ( $title, $args ) {
				// Modify generated titles before TSF initializes.
				return $title;
			},
			10,
			2,
		);
	},
);

Plugin init

These actions fire on WordPress’s init at priority 0. Beyond removing the need for function_exists checks, they let you register and deregister TSF actions.

Because they run after the theme loads, you can register these in themes too.

/**
 * Runs before the plugin is initialized.
 *
 * @since 2.8.0
 */
do_action( 'the_seo_framework_init' );

/**
 * Runs after the plugin is initialized.
 * Use this to remove filters and actions.
 *
 * @since 3.1.0
 */
do_action( 'the_seo_framework_after_init' );

Context-specific init hooks

TSF fires separate init hooks for admin and front-end contexts. These are useful when your code should only run in one context.

/**
 * Runs before the plugin is initialized in the admin screens.
 *
 * @since 2.8.0
 */
do_action( 'the_seo_framework_admin_init' );

/**
 * Runs after the plugin is initialized in the admin screens.
 * Use this to remove actions.
 *
 * @since 2.9.4
 */
do_action( 'the_seo_framework_after_admin_init' );

/**
 * Runs before the plugin is initialized on the front-end.
 *
 * @since 2.8.0
 */
do_action( 'the_seo_framework_front_init' );

/**
 * Runs after the plugin is initialized on the front-end.
 * Use this to remove actions.
 *
 * @since 2.9.4
 */
do_action( 'the_seo_framework_after_front_init' );

Example: disable front-end redirects

add_action(
	'the_seo_framework_after_front_init',
	function () {
		// Remove TSF's custom redirect handler on the front-end.
		remove_action(
			'template_redirect',
			[ 'The_SEO_Framework\Front\Redirect', 'init_meta_setting_redirect' ],
		);
	},
);

Hook lifecycle order

Understanding when each hook fires helps you pick the right one. TSF’s hooks fire in this order:

On plugins_loaded priority 5:

  1. the_seo_framework_admin_loaded (admin only)
  2. the_seo_framework_loaded

On init priority 0:

  1. the_seo_framework_init
  2. the_seo_framework_admin_init or the_seo_framework_front_init (context-dependent)
  3. the_seo_framework_after_admin_init or the_seo_framework_after_front_init (context-dependent)
  4. the_seo_framework_after_init

Choosing between them:

  • Need the tsf() object early? Use the_seo_framework_loaded.
  • Need to add or remove hooks? Use the _after_ variants.
  • Need theme functions available? Use the init hooks — the loaded hooks fire before themes load.
  • Only relevant in admin or front-end? Use the context-specific variant.

Front-end meta output

These hooks let you inject content before or after TSF’s <head> meta tags. They fire on every front-end page load where TSF outputs metadata.

/**
 * Fires before TSF's HTML comment and meta tag output begins.
 *
 * @since 2.6.0
 */
do_action( 'the_seo_framework_do_before_output' );

/**
 * Fires after TSF's HTML comment and meta tag output completes.
 *
 * @since 2.6.0
 */
do_action( 'the_seo_framework_do_after_output' );

/**
 * Fires before individual meta tags are rendered.
 *
 * @since 4.2.0
 */
do_action( 'the_seo_framework_before_meta_output' );

Redirect

This hook fires just before TSF sends a redirect header. You can use it to log redirects or add custom logic.

/**
 * @since 4.1.2
 * @param string $url The URL TSF is redirecting to.
 */
do_action( 'the_seo_framework_before_redirect', $url );

Settings page

TSF provides before/after action hooks for each settings metabox tab on the SEO Settings page. Extension Manager uses these to inject its own fields. The pattern is:

do_action( 'the_seo_framework_{$tab}_metabox_before' );
// ... metabox content ...
do_action( 'the_seo_framework_{$tab}_metabox_after' );

Where {$tab} is one of: general, title, description, robots, homepage, post_type_archive, social, webmaster, sitemaps, feed, or schema.

Two additional hooks wrap the entire settings page:

/**
 * Fires before all SEO settings metaboxes.
 *
 * @since 3.0.0
 */
do_action( 'the_seo_framework_pre_seo_settings' );

/**
 * Fires after all SEO settings metaboxes.
 *
 * @since 3.0.0
 */
do_action( 'the_seo_framework_pro_seo_settings' );

Post and term edit screens

TSF provides hooks around its SEO meta boxes on post, term, and user edit screens. Extension Manager uses these to add fields like Focus and Local SEO.

/**
 * Post edit screen - wraps the entire SEO box.
 *
 * @since 2.9.0
 */
do_action( 'the_seo_framework_pre_page_inpost_box' );
do_action( 'the_seo_framework_pro_page_inpost_box' );

/**
 * Post edit screen - per tab.
 * Tabs: general, visibility, social.
 *
 * @since 2.9.0
 */
do_action( "the_seo_framework_pre_page_inpost_{$tab}_tab" );
do_action( "the_seo_framework_pro_page_inpost_{$tab}_tab" );

/**
 * Term edit screen - wraps the entire SEO box.
 *
 * @since 2.9.0
 */
do_action( 'the_seo_framework_pre_tt_inpost_box' );
do_action( 'the_seo_framework_pro_tt_inpost_box' );

/**
 * User profile edit screen.
 *
 * @since 4.1.4
 */
do_action( 'the_seo_framework_before_author_fields' );
do_action( 'the_seo_framework_after_author_fields' );

Sitemap

/**
 * Fires before TSF outputs the sitemap XML.
 *
 * @since 4.0.0
 * @param string $sitemap_id The sitemap ID (e.g., 'base').
 */
do_action( 'the_seo_framework_sitemap_header', $sitemap_id );

/**
 * Fires after all sitemap transient caches are cleared.
 *
 * @since 5.0.0
 */
do_action( 'the_seo_framework_cleared_sitemap_transients' );

Upgrade and downgrade

These hooks fire when TSF detects a version change — useful for running migration logic in companion plugins.

/**
 * @since 2.7.0
 * @param string $previous_version The version the site upgraded from.
 * @param string $current_version  The current version of the plugin.
 */
do_action( 'the_seo_framework_upgraded', $previous_version, $current_version );

/**
 * @since 4.1.0
 * @param string $previous_version The version the site downgraded from.
 * @param string $current_version  The current version of the plugin.
 */
do_action( 'the_seo_framework_downgraded', $previous_version, $current_version );
Filed Under: Developers, Customization