Skip to content

Background image: should it integrate with background-image theme mod? #60939

@ramonjd

Description

@ramonjd

What's the issue?

Site background images in WordPress pre-block editor

in this issue a "site background image" refer to an image set via the background-image CSS property to the body tag.

WordPress themes have long been able to set site background images and other background properties such as size and repeat (on the HTML body element) either by the Customizer UI or, more directly, using custom-background theme support. For example:

add_theme_support(
    'custom-background',
    array(
        // As well as default image, there's default-position-x, default-position-y, default-size, default-repeat, default-attachment
        'default-image' => get_stylesheet_directory_uri() . '/img/bird.jpg',
    )
);

Or like this:

add_theme_support( 'custom-background' );
// As well as background_image, there's background_preset, background_size, background_position_x, background_position_y
set_theme_mod( 'background_image',  get_stylesheet_directory_uri() . '/img/bird.jpg' );

Enabling background support adds a link to the Customizer in the admin menu. Users can add/edit the background image using Customizer controls:

Link in sidebar Customizer controls
Screenshot 2024-04-22 at 1 44 09 pm Screenshot 2024-04-22 at 1 43 36 pm

Site background images in block themes/block editor

Since #59354 and #59454, users can add site background images via theme.json or global styles in the site editor.

However, if a site background image is set via theme support/mods, it will overwrite any theme.json or global styles image set in the site editor because of CSS specificity, that is body.custom-background will trump :where(body).

Screenshot 2024-04-22 at 11 50 44 am

What is the question? Or your proposed solution?

The main question is whether Gutenberg should take values set by theme support/mods into account by:

  • using any background- values from theme support/mods as defaults for top-level background property values.
  • overwriting theme support/mod values with theme.json/global styles values, perhaps via a higher CSS specificity or preventing WordPress from outputting the custom-background-css style tag
  • ??

Related discussion: #60578 (comment)

Metadata

Metadata

Assignees

No one assigned

    Labels

    Global StylesAnything related to the broader Global Styles efforts, including Styles Engine and theme.json[Feature] ThemesQuestions or issues with incorporating or styling blocks in a theme.[Type] QuestionQuestions about the design or development of the editor.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions