Skip to content

[Lightbox] Add theme.json support for lightbox overlay background color#78588

Open
sarthaknagoshe2002 wants to merge 2 commits into
WordPress:trunkfrom
sarthaknagoshe2002:fix/issue-78506
Open

[Lightbox] Add theme.json support for lightbox overlay background color#78588
sarthaknagoshe2002 wants to merge 2 commits into
WordPress:trunkfrom
sarthaknagoshe2002:fix/issue-78506

Conversation

@sarthaknagoshe2002
Copy link
Copy Markdown
Contributor

@sarthaknagoshe2002 sarthaknagoshe2002 commented May 22, 2026

What?

Closes #78506

This PR adds support for a new overlayBackgroundColor property within the lightbox settings in theme.json. It updates the Image block's lightbox rendering to use a CSS custom property for the overlay background instead of a hardcoded inline style.

Why?

Currently, the Image and Gallery block lightbox feature hardcodes the scrim background color as an inline style (style="background-color: #fff"). This is a major pain point for dark themes or portfolio sites, as it forces theme developers to use !important in their custom CSS to override the white background. By moving this to theme.json and utilizing CSS custom properties, we align the lightbox feature with the standard Gutenberg design tools system and make it much easier for theme authors to customize.

How?

  • Added overlayBackgroundColor to the lightbox configuration.
  • The image block now checks for an overlayBackgroundColor value in the block level settings (settings.blocks.core/image.lightbox) and falls back to the global settings (settings.lightbox).
  • Replaced the hardcoded inline background-color on the .scrim div with a CSS custom property: --wp--lightbox--overlay-background-color.
  • Updated packages/block-library/src/image/style.scss to consume the new var(--wp--lightbox--overlay-background-color) with a default fallback of rgb(255, 255, 255).

Testing Instructions

  1. Activate a block theme.
  2. Open the theme's theme.json file and add a global lightbox background color:
    "settings": {
        "lightbox": {
            "overlayBackgroundColor": "rgba(0, 0, 0, 0.9)"
        }
    }
  3. Open a post or page in the editor.
  4. Insert an Image block, upload an image.
  5. Save the post and view it on the front end.
  6. Click the image to trigger the lightbox. Verify that the background color is now the dark, semi-transparent color defined in theme.json.
  7. Update your theme.json to define a specific color just for the image block (settings.blocks.core/image.lightbox.overlayBackgroundColor = "red"). Verify that the block-level setting successfully overrides the global setting on the front end.

Screenshots or screencast

Before After
image image

@github-actions github-actions Bot added the [Package] Block library /packages/block-library label May 22, 2026
@github-actions
Copy link
Copy Markdown

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

  • Required label: Any label starting with [Type].
  • Labels found: [Package] Block library.

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

@github-actions
Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: sarthaknagoshe2002 <sarthaknagoshe2002@git.wordpress.org>
Co-authored-by: BlackStar1991 <blackstar1991@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Package] Block library /packages/block-library

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Allow users and themes to customize the Image/Gallery Lightbox background color

1 participant