after_switch_theme │ action-hook │ WP 3.3.0

Fires after the theme has been switched to a new one, when the theme is activated.

It fires on the first WordPress load after the theme was switched when the old theme exists. If the old theme does not exist, the hook is called as follows:

// One parameter, $stylesheet, rather than $old_name and $old_theme.
do_action( 'after_switch_theme', $stylesheet );

Only functions from the newly activated theme are available during this event. Use switch_theme if functions from the old theme are needed.

It differs from switch_theme because it fires later: not in the currently executing PHP script, but in the next one during the next page load. Theme activation involves two redirects followed by a return to the original page.

How it works

The complete theme switching sequence:

1. Open /wp-admin/themes.php.

2. Click the theme's Activate button (link).

3. Follow a URL such as /wp-admin/themes.php?action=activate&stylesheet=twentyfifteen.

4. The switch_theme hook fires.

5. WordPress automatically redirects to a URL such as /wp-admin/themes.php?activated=true.

6. The after_switch_theme hook fires.

7. WordPress automatically redirects back to /wp-admin/themes.php.

As a result, the final PHP execution does not show both theme switching hooks firing. Use die() to stop execution and inspect what happens.

Usage

add_action( 'after_switch_theme', 'wp_kama_after_switch_theme_action', 10, 2 );

/**
 * Function for `after_switch_theme` action-hook.
 * 
 * @param string   $old_name  Old theme name.
 * @param WP_Theme $old_theme WP_Theme instance of the old theme.
 *
 * @return void
 */
function wp_kama_after_switch_theme_action( $old_name, $old_theme ){
	// action...
}

Parameters

$old_name(string)

Old theme name.

$old_theme(WP_Theme)

WP_Theme object for the old theme. See wp_get_theme().

Examples

#1 Add default theme options on activation

add_action('after_switch_theme', 'mytheme_setup_options');

function mytheme_setup_options( $old_name ) {
	$opt = array('opt1'=>'val1', 'opt2'=>'val2');

	add_option('mytheme_options', $opt );
}

#2 Another way to add theme options on activation

This is equivalent to the first example but uses after_setup_theme, which fires continuously rather than once. In this example, the @ $_GET['activated'] check ensures that it runs only once.

The first approach is recommended because it is designed for one-time work when switching to a new theme and also provides the old theme parameters.

add_action( 'after_setup_theme', 'activate_my_theme' );
function activate_my_theme() {
	if ( @ $_GET['activated'] === 'true' && current_user_can('manage_options') ){
		$opt = array('opt1'=>'val1', 'opt2'=>'val2');

		add_option('mytheme_options', $opt );
	}
}

#3 Remove options on theme deactivation and add them on activation

// Remove theme settings on deactivation.
add_action('switch_theme', 'deactivate_my_theme');
function deactivate_my_theme( $old_name ){
	// Old theme functions are available, but new theme functions are not.
	delete_option('mytheme_options');
}

// Add theme settings on activation.
add_action('after_switch_theme', 'activate_my_theme' );
function activate_my_theme( $new_name ){
	// New theme functions are available, but old theme functions are not.

	$opt = array('opt1'=>'val1', 'opt2'=>'val2');

	add_option('mytheme_options', $opt );
}