Site-wide background images in WordPress 6.6

In WordPress 6.6 you can define site-wide background images in theme.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. and the Site Editor.

A “site-wide” background image is one whose value is set on the body element using the background-image CSSCSS Cascading Style Sheets. property, and, therefore, appears on every page of a site.

An example might be a photo that stretches with the window size, or a repeating pattern background.

To customize how background images appear, WordPress 6.6 supports the following background style properties:

• background position
• background size
• background repeat

Usage

In theme.json

In theme.json, site-wide background images and their properties are defined under "styles.background".

For example, as a single image URI in styles.background.backgroundImage.url:

{
	"styles": {
		"background": {
			"backgroundImage": {
				"url": "<a href="http://path.to/some/image.png">http://path.to/some/image.png</a>"
			},
			"backgroundSize": "cover"
		}
	}
}

For the above, WordPress will automatically wrap the image in the CSS url() function.

styles.background.backgroundImage also accepts string values, which can be any valid CSS value for background-image :

{
	"styles": {
		"background": {
			"backgroundImage": "url(<a href="http://path.to/some/image.png">http://path.to/some/image.png</a>)",
			"backgroundPosition": "center"
		}
	}
}

The above examples use absolute paths to image files. Such files would need to be hosted and maintained.

Most likely, theme developers will want to define background images using paths to a theme’s own assets. This ensures that the theme is self-contained and portable.

Relative paths to theme assets are defined using the file:./ prefix:

{
	"styles": {
		"background": {
			"backgroundImage": {
				"url": "file:./assets/my-theme-background.jpg"
			},
			"backgroundSize": "cover"
		}
	}
}

Paths are resolved on the backend using get_theme_file_uri.

Paths defined this way must be relative to the theme root, regardless of where the theme.json sits in your theme’s directory. This follows an existing pattern for web fonts.

Despite the dot in file:./, the special symbols dot (.) and double dot (..) for directory navigation are not supported in theme.json relative paths. This means, for example, that theme style variation files, which reside under the style/ directory, would use the same path as the theme’s main theme.json.

An issue exists to make the syntax more consistent.

In the Site Editor

Background images can be also be uploaded, and their properties tweaked through the Site Editor’s styles panel.

In WordPress 6.6, background image controls are located under Styles > Layout.

The styles panel navigation is undergoing review however, so in upcoming versions the location may change.

As well as setting new background images, it’s possible to “remove” a theme’s default background image in the Site Editor.

Relative paths to any images in theme.json are resolved on the backend, and are sent in the _links array of Global Styles REST responses. The Editor uses the resolved values to generate theme CSS in the client.

Limitations

In WordPress 6.6, the ability to define background images in theme.json exists only for top-level styles. Top-level styles apply to the body element. An open PR aims to also enable the feature at the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. level in the next WordPress release.

Work is also underway to:

• add support for fixed images, using the background-attachment CSS property.
• avoid conflicts between gradient backgrounds, whose values are currently set to the background property, and background-image. The proposal is that gradient backgrounds will also be set to background-image, and, where both an image and a gradient are defined, their values are merged .

Backwards compatibility

WordPress already has support for custom site-wide background images in the Customizer. The theme.json variant will not affect themes that have enabled this feature.

Background images added in the CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. take precedence over those set in theme.json or in the Site Editor.

An ongoing discussion seeks to harmonize the two features.

What’s next

Progress on upcoming work is tracked on Background Image block support follow-up tasks.

Props to @andrewserong and @juanmaguitar for review

#6-6, #core-editor, #dev-note, #dev-notes, #dev-notes-6-6, #gutenberg