set_theme_mod() │ WP 2.1.0

Creates or updates special settings (options) of the current theme.

By "special," it refers to options like "background-color," which can later be retrieved using get_theme_mod().

Functions of the type *_theme_mod are analogous to the Settings API and are needed for a unified standard and proper operation with child themes. For flexibility, filters are present in the functions.

All such special options of the theme are physically stored in one option of the wp_options table - theme_mods_(theme), in the form of an array.

The following code will place an array in the options: array( 'aaa'=>123, 'bbb'=>456 ).

set_theme_mod( 'aaa', 123 );
set_theme_mod( 'bbb', 456 );

All theme_mod functions are wrappers for get_option() and therefore they are slightly slower because before using get_option(), the function retrieves the theme name, creates the option name "theme_mods_$theme" from it, and then applies a filter to the specified option.

However, all these operations do not significantly reduce speed.

To remove an existing theme option, use remove_theme_mod().

Uses: get_theme_mods(), update_option()
1 time — 0.000983 sec (slow) | 50000 times — 4.90 sec (fast)
Hooks from the function

Returns

true|false. Depending on whether the option value was updated or not. See update_option().

Usage

set_theme_mod( $name, $value );
$name(string) (required)
The name of the special theme option.
$value(mixed) (required)
The value of the option.

Examples

1

#1 Set the themes option

Install and get a special setup of the theme:

add_action( 'switch_theme', 'wp_kama_theme_mods' );

function wp_kama_theme_mods() {
	set_theme_mod( 'my_mod_one', 'new_mode_one_value' );
}

Then get this option where needed:

get_theme_mod( 'my_mod_one' ); // > 123

Changelog

Since 2.1.0 Introduced.
Since 5.6.0 A return value was added.

set_theme_mod() code WP 6.8.1

wp-includes/theme.php 
function set_theme_mod( $name, $value ) {
	$mods      = get_theme_mods();
	$old_value = isset( $mods[ $name ] ) ? $mods[ $name ] : false;

	/**
	 * Filters the theme modification, or 'theme_mod', value on save.
	 *
	 * The dynamic portion of the hook name, `$name`, refers to the key name
	 * of the modification array. For example, 'header_textcolor', 'header_image',
	 * and so on depending on the theme options.
	 *
	 * @since 3.9.0
	 *
	 * @param mixed $value     The new value of the theme modification.
	 * @param mixed $old_value The current value of the theme modification.
	 */
	$mods[ $name ] = apply_filters( "pre_set_theme_mod_{$name}", $value, $old_value );

	$theme = get_option( 'stylesheet' );

	return update_option( "theme_mods_$theme", $mods );
}

Theme Modification API (theme mods options settings)

Other Theme Functions