classic-theme-customizer

Classic Theme Customizer

Use this when adding or reviewing Customizer settings for a classic PHP theme. This is for theme presentation choices such as colors, layout toggles, logo-adjacent display settings, and small design options.

Do not use theme Customizer settings for plugin-like business data, payment credentials, complex content models, or cross-theme application state.

When to Use This Skill

• Adding customize_register code to a classic theme.
• Creating a color, select, checkbox, text, image, or layout option.
• Reviewing get_theme_mod() output in templates.
• Adding live preview with postMessage or selective refresh.
• Fixing unsanitized Customizer settings or controls registered outside the correct hook.

Registration Hook

Register settings, sections, and controls on customize_register.

add_action( 'customize_register', 'mytheme_customize_register' );

function mytheme_customize_register( WP_Customize_Manager $wp_customize ) {
	$wp_customize->add_section(
		'mytheme_layout',
		array(
			'title'    => __( 'Layout', 'textdomain' ),
			'priority' => 160,
		)
	);
}

Rules:

• Use the WP_Customize_Manager instance passed to the hook.
• Prefix setting IDs with the theme slug.
• Keep Customizer setup in inc/customizer.php or a similarly scoped include, loaded from functions.php.
• Do not register controls during normal template rendering.

Settings Must Sanitize

Every custom setting needs a sanitize_callback.

$wp_customize->add_setting(
	'mytheme_accent_color',
	array(
		'default'           => '#0a7a75',
		'type'              => 'theme_mod',
		'capability'        => 'edit_theme_options',
		'transport'         => 'refresh',
		'sanitize_callback' => 'sanitize_hex_color',
	)
);

Rules:

• Prefer type => 'theme_mod' for theme design settings.
• Use type => 'option' only when the value is intentionally shared beyond the active theme.
• When using type => 'option', set autoload => false for values that are not needed on most requests; core's multidimensional option save defaults to autoloading unless an autoload arg is supplied.
• The default capability is edit_theme_options; set it explicitly when clarity helps.
• Use transport => 'refresh' unless live preview is actually implemented.
• Add validate_callback when a value can be syntactically valid but semantically unacceptable.