Full Site Editing

Chapter 2: Theme.json

Theme.json image options

In this lesson

There are four image options in the theme.json settings section, and one in styles:

Settings:

  • backgroundImage, which enables or disables the option to add a background image.
  • backgroundSize, which enables or disables the option to adjust the background image options: Size, position and repeat.
  • lightbox, which enables or disables viewing an image in a full screen lightbox modal.
  • aspectRatio, which enables or disables the image aspect ratio settings.

Styles: The styles section is where you add default background images to the site or the blocks.

I have covered the aspect ratio settings and presets in the theme.json layout and spacing lesson, because right now, the block editor only use it for images, but it does not have to be limited to images.

How to enable background image and background size controls

Once enabled, you can add background images to the group, post content, pull quote, quote, and verse blocks.

In the styles panel in the Site Editor you can also add a background image to the site:

Note: To remove an image, you need to click on the image itself inside the modal, the “Reset all” option does not reset the image URL.

Both the backgroundImage and backgroundSize controls are disabled by default.
If you have already set appearanceTools to true, you do not need to enable these settings separately.

"settings": {
	"background": {
		"backgroundImage": true,
		"backgroundSize": true
	}
}

And to disable them, just change this value from true to false:

"settings": {
	"background": {
		"backgroundImage": false,
		"backgroundSize": false
	}
}

How to add a default background image using theme.json

Any block can have a default background image set in the styles section of theme.json, even blocks that don’t support the controls in the block settings sidebar.

💡Unfortunately, at the time of writing this in April 2025, there is a bug in the editor that breaks the URL to the image in theme.json elements. So right now you can only add it to the site and the blocks.

All the background image style options are inside a background object. The first property, backgroundImage, has a single key and value pair; the url.

In this code example, the image is inside the theme’s assets/images/ folder.
You may recognize that I am using file, which is the same format as when including font files. The path is relative to the theme’s root directory.

"styles": {
	"background": {
		"backgroundImage": {
			"url": "file:./assets/images/background.png"
		}
	}
}

This adds the background image to the body element in the editor or editor iframe, and on the front:

body {
    background-image: url(https://example.com/wp-content/themes/themeslug/assets/images/background.png);

If you also have a solid body background color set, both will be applied. A solid background color will be visible below a semi transparent background image.

💡There are known bugs with combining a background image with a background gradient. On the body, the background image will override the gradient. While if you add a gradient to a block that has a background image, only the gradient will be visible.

Here is a short example of how to add the background image to a single block:

"styles": {
	"blocks": {
		"core/pullquote": {
			"background": {
				"backgroundImage": {
					"url": "file:./assets/images/background.png"
				}
			}
		}
	}
}

The resulting CSS output for the pull quote is:

:root :where(.wp-block-pullquote) {
    background-image: url(https://example.com/wp-content/themes/themeslug/assets/images/background.png);
}

The rest of the style options also represent standard CSS features, and you can use any valid CSS value. These are pretty straightforward:

"styles": {
	"blocks": {
		"core/pullquote": {
			"background": {
				"backgroundImage": {
					"url": "file:./assets/images/background.png"
				},
				"backgroundAttachment": "fixed"
			}
		}
	}
}

Lightbox settings

The lightbox is a feature that opens an image in a full screen modal. WordPress enables the lightbox on the image block and gallery block by default.

💡There are no styling options for the lightbox. To change the look of the lightbox, you would need to use custom CSS.

There are two lightbox settings in theme.json:

  • Enabled: Enables or disables the lightbox.
  • allowEditing: Enables or disables the lightbox control in the link option in the block toolbar.

The default theme.json loaded by WordPress has the following setting:

"settings": {
	"blocks": {
		"core/image": {
			"lightbox": {
				"allowEditing": true
			}
		}
	}
}

So you must add your customization on the settings.blocks.core/image level, not directly under settings. This is subject to change once more blocks have support for the lightbox.

  • When enabled is set to true, all image blocks open in the lightbox when you click on the image on the front of the site, unless you select a different link setting for the individual block.
  • If allowEditing is true, then the lightbox control is available in the link setting in the block toolbar.
  • If allowedEditing is false, then the lightbox control is available on any block that already had the lightbox option enabled. But the control is not available on newly inserted blocks.
  • And even if they are both disabled, the lightbox feature can still be enabled on the image block by:
    • Copying or duplicating an existing block that already has the lightbox enabled.
    • Editing the attributes in the code editor mode.

All you would need to do is set enabled to true on the image block in the code editor:

<!-- wp:image {"lightbox":{"enabled":true},"id":12,"sizeSlug":"full","linkDestination":"none"} -->

So there is no way to completely disable the lightbox using theme.json.
And because the image is an inner block inside the gallery, it is also not possible to use theme.json to only disable the lightbox on the gallery.