From 7f5b3b0e6b1107bc3eb0a179631a3b39206b5188 Mon Sep 17 00:00:00 2001
From: Sukhendu Sekhar Guria <sukhendu.guria@rtcamp.com>
Date: Wed, 15 Apr 2026 16:58:53 +0530
Subject: [PATCH] Customize: Allow themes to configure the custom-background
 CSS selector

---
 src/js/_enqueues/wp/customize/preview.js       |  8 ++++++--
 src/wp-includes/class-wp-customize-manager.php | 14 ++++++++++++++
 src/wp-includes/post-template.php              |  3 ++-
 src/wp-includes/theme.php                      |  9 ++++++++-
 4 files changed, 30 insertions(+), 4 deletions(-)

diff --git a/src/js/_enqueues/wp/customize/preview.js b/src/js/_enqueues/wp/customize/preview.js
index 375cd2104ba0f..9f12a3ec93275 100644
--- a/src/js/_enqueues/wp/customize/preview.js
+++ b/src/js/_enqueues/wp/customize/preview.js
@@ -671,12 +671,16 @@
 				settings[ prop ] = api( 'background_' + prop );
 			} );
 
+			var bgElement  = ( api.settings.theme && api.settings.theme.bgElement ) ? api.settings.theme.bgElement : document.body;
+			var bgClass    = ( api.settings.theme && api.settings.theme.bgClass ) ? api.settings.theme.bgClass : 'custom-background';
+			var bgSelector = ( api.settings.theme && api.settings.theme.bgSelector ) ? api.settings.theme.bgSelector : 'body.custom-background';
+
 			/*
 			 * The body will support custom backgrounds if either the color or image are set.
 			 *
 			 * See get_body_class() in /wp-includes/post-template.php
 			 */
-			$( document.body ).toggleClass( 'custom-background', !! ( settings.color() || settings.image() ) );
+			$( bgElement ).toggleClass( bgClass, !! ( settings.color() || settings.image() ) );
 
 			if ( settings.color() ) {
 				css += 'background-color: ' + settings.color() + ';';
@@ -690,7 +694,7 @@
 				css += 'background-attachment: ' + settings.attachment() + ';';
 			}
 
-			$( '#custom-background-css' ).text( 'body.custom-background { ' + css + ' }' );
+			$( '#custom-background-css' ).text( bgSelector + ' { ' + css + ' }' );
 		}
 	};
 
diff --git a/src/wp-includes/class-wp-customize-manager.php b/src/wp-includes/class-wp-customize-manager.php
index 961910e011d12..e302f02927314 100644
--- a/src/wp-includes/class-wp-customize-manager.php
+++ b/src/wp-includes/class-wp-customize-manager.php
@@ -2151,6 +2151,17 @@ public function customize_preview_settings() {
 			restore_previous_locale();
 		}
 
+		/*
+		 * Export custom-background element, class, and selector into the preview frame.
+		 * bgElement and bgClass are exported separately so the JS can toggle the class
+		 * on the correct DOM element; bgSelector is the final CSS selector used in the
+		 * injected <style> tag.
+		 */
+		$has_custom_bg   = current_theme_supports( 'custom-background' );
+		$bg_element      = $has_custom_bg ? tag_escape( get_theme_support( 'custom-background', 'background-element' ) ) : 'body';
+		$bg_class        = $has_custom_bg ? sanitize_html_class( get_theme_support( 'custom-background', 'background-class' ) ) : 'custom-background';
+		$bg_selector     = $has_custom_bg ? sprintf( get_theme_support( 'custom-background', 'background-selector' ), $bg_element, $bg_class ) : 'body.custom-background';
+
 		$settings = array(
 			'changeset'         => array(
 				'uuid'      => $this->changeset_uuid(),
@@ -2164,6 +2175,9 @@ public function customize_preview_settings() {
 				'stylesheet'   => $this->get_stylesheet(),
 				'active'       => $this->is_theme_active(),
 				'isBlockTheme' => wp_is_block_theme(),
+				'bgElement'    => $bg_element,
+				'bgClass'      => $bg_class,
+				'bgSelector'   => $bg_selector,
 			),
 			'url'               => array(
 				'self'          => $self_url,
diff --git a/src/wp-includes/post-template.php b/src/wp-includes/post-template.php
index 2429ab3adb776..0f378b695430d 100644
--- a/src/wp-includes/post-template.php
+++ b/src/wp-includes/post-template.php
@@ -802,7 +802,8 @@ function get_body_class( $css_class = '' ) {
 
 	if ( current_theme_supports( 'custom-background' )
 		&& ( get_background_color() !== get_theme_support( 'custom-background', 'default-color' ) || get_background_image() ) ) {
-		$classes[] = 'custom-background';
+
+		$classes[] = sanitize_html_class( get_theme_support( 'custom-background', 'background-class' ) );
 	}
 
 	if ( has_custom_logo() ) {
diff --git a/src/wp-includes/theme.php b/src/wp-includes/theme.php
index 07869ae61d0ff..79e6419d928c0 100644
--- a/src/wp-includes/theme.php
+++ b/src/wp-includes/theme.php
@@ -1948,7 +1948,11 @@ function _custom_background_cb() {
 	$processor = new WP_HTML_Tag_Processor( '<style id="custom-background-css"></style>' );
 	$processor->next_tag();
 
-	$style_tag_content = 'body.custom-background { ' . trim( $style ) . ' }';
+	$element  = tag_escape( get_theme_support( 'custom-background', 'background-element' ) );
+	$class    = sanitize_html_class( get_theme_support( 'custom-background', 'background-class' ) );
+	$selector = sprintf( get_theme_support( 'custom-background', 'background-selector' ), $element, $class );
+
+	$style_tag_content = $selector . ' { ' . trim( $style ) . ' }';
 	$processor->set_modifiable_text( "\n{$style_tag_content}\n" );
 	echo "{$processor->get_updated_html()}\n";
 }
@@ -2893,6 +2897,9 @@ function add_theme_support( $feature, ...$args ) {
 				'wp-head-callback'       => '_custom_background_cb',
 				'admin-head-callback'    => '',
 				'admin-preview-callback' => '',
+				'background-element'     => 'body',
+				'background-class'       => 'custom-background',
+				'background-selector'    => '%1$s.%2$s', // sprintf template: %1$s = background-element, %2$s = background-class.
 			);
 
 			$jit = isset( $args[0]['__jit'] );