Skip to content

Page List: Add background image, size, and gradient support - #83234

Open
aaronrobertshaw wants to merge 1 commit into
trunkfrom
add/page-list-background-support
Open

Page List: Add background image, size, and gradient support#83234
aaronrobertshaw wants to merge 1 commit into
trunkfrom
add/page-list-background-support

Conversation

@aaronrobertshaw

@aaronrobertshaw aaronrobertshaw commented Sep 21, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Related: #43241

What?

Adds background image, size, and gradient support to the Page List block.

Why?

The Page List block supports color (including the legacy color gradients), border, shadow, spacing and typography, but not the Background panel's background image, size, and gradient controls. This brings it in line with other blocks as part of the design tools consistency work.

How?

Adds background.backgroundImage, background.backgroundSize and background.gradient to the block's block.json supports. Page List is server rendered through get_block_wrapper_attributes(), so the supports serialize onto the list wrapper and no PHP change is needed. The legacy color.gradients support stays alongside background.gradient.

It returns early when there are no pages. One existing edge case, where every published page has an unpublished parent, still renders an empty list; its existing border, spacing and shadow already paint that box, so the background behaves the same.

The gradient layers over the image (#75859), so both show together.

The core blocks reference and the block's README.md are regenerated to list the new supports.

Testing Instructions

  1. Add a Page List block to a post on a site with a few pages and publish. It renders as before, with no background.
  2. In Global Styles, go to Blocks > Page List > Background, set an image with size Contain, add a light translucent gradient and save. The block shows the image under the gradient in the editor and on the front end.
  3. With step 2 still applied, select the block, set a different image with size Cover and a blue translucent gradient in the block inspector, and update the post. The block level image, size and gradient win in the editor and on the front end.
  4. In Global Styles, choose Mobile in the States menu and set a smaller image size with a green translucent gradient. In the post editor, open View, turn on Responsive styles and choose Mobile. The block shows the mobile values in the editor and on the front end at a mobile width, while the desktop width still shows the desktop ones.
  5. With step 4 still applied and Mobile selected, set the second image with size Contain and a red translucent gradient on the block. The block level mobile values win in the editor and on the front end at a mobile width.

Screenshots or screencast

Global Style - Editor Global Style - Frontend
2-global-editor 2-global-front
Block Instance Override - Editor Block Instance Override - Frontend
3-instance-editor 3-instance-front
Responsive Global Style (Mobile) - Editor Responsive Global Style (Mobile) - Frontend
4-responsive-global-editor 4-responsive-global-front
Responsive Block Instance Override (Mobile) - Editor Responsive Block Instance Override (Mobile) - Frontend
5-responsive-instance-editor 5-responsive-instance-front

Use of AI Tools

Implemented, built and screenshotted by a Claude Code agent from a predefined task.

@aaronrobertshaw aaronrobertshaw added [Feature] Design Tools Tools that impact the appearance of blocks both to expand the number of tools and improve the experi [Type] Enhancement A suggestion for improvement. [Package] Block library /packages/block-library Global Styles Anything related to the broader Global Styles efforts, including Styles Engine and theme.json [Block] Page List Affects the Page List Block labels Sep 21, 2026
@aaronrobertshaw aaronrobertshaw self-assigned this Sep 21, 2026
@github-actions

github-actions Bot commented Sep 21, 2026

Copy link
Copy Markdown

🤖 PR meta 🤖

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric 538b082 trunk % Change
timeToFirstByte 60.4 ms +9.02% -5.55% 57.45 ms +15.75% -2.79% 5.13%
largestContentfulPaint 102 ms +9.8% -5.88% 100 ms +8% -4% 2%
lcpMinusTtfb 40.15 ms +16.56% -12.45% 43.95 ms +2.5% -22.41% -8.65%
wpBeforeTemplate 30.08 ms +13.03% -5.88% 28.3 ms +19.93% -1.94% 6.29%
wpTemplate 25.27 ms +4.31% -3.56% 24.76 ms +8.97% -2.5% 2.06%
wpTotal 56.66 ms +8.49% -6.28% 53.8 ms +14.39% -2.96% 5.32%
wpMemoryUsage 7.53 MB +0% -0% 7.50 MB +0% -0% 0.47%
wpDbQueries 17 +0% -0% 17 +0% -0% 0%

front-end-classic-theme

Metric 538b082 trunk % Change
timeToFirstByte 50 ms +4.2% -3.2% 48.1 ms +5.41% -1.66% 3.95%
largestContentfulPaint 108 ms +3.7% -3.7% 104 ms +1.92% -3.85% 3.85%
lcpMinusTtfb 56.85 ms +4.31% -3.34% 54 ms +3.52% -2.41% 5.28%
wpBeforeTemplate 26.88 ms +3.91% -1.38% 26.73 ms +5.16% -2.69% 0.56%
wpTemplate 18.67 ms +5.46% -1.87% 18.27 ms +4.16% -1.64% 2.19%
wpTotal 46.89 ms +3.9% -3.52% 45.17 ms +5.47% -2.3% 3.81%
wpMemoryUsage 6.15 MB +0% -0% 6.12 MB +0% -0% 0.6%
wpDbQueries 14 +0% -0% 14 +0% -0% 0%

media-processing

Metric 538b082 trunk % Change
mediaProcessingJpeg 397.89 ms +0.85% -0.2% 401.71 ms +0.31% -0.64% -0.95%
mediaProcessingAvif 6063.27 ms +0.26% -0.43% 6054.52 ms +0.65% -0.08% 0.14%
mediaProcessingJpegToAvif 4174.71 ms +0.18% -0.09% 4191.96 ms +0.32% -0.07% -0.41%

media-upload

Metric 538b082 trunk % Change
jpegUploadProcessing 1434.61 ms +34.68% -0.76% 1427.26 ms +0.33% -0.7% 0.51%
pngUploadProcessing 214.74 ms +15.05% -1.53% 228.09 ms +4.87% -6.66% -5.85%
largeJpegUploadProcessing 1414.78 ms +0.88% -0.44% 1414.41 ms +0.59% -0.22% 0.03%
multipleImageUploadProcessing 1612.26 ms +0.61% -3.49% 1570.97 ms +8.4% -1.41% 2.63%

post-editor

Metric 538b082 trunk % Change
serverResponse 351.36 ms +1.1% -9.33% 309.67 ms +8.38% -8.01% 13.46%
firstPaint 180.48 ms +20.53% -14.07% 145.64 ms +16.94% -14.27% 23.92%
domContentLoaded 856.75 ms +2.5% -1.54% 843.49 ms +1.81% -0.81% 1.57%
loaded 857.83 ms +2.51% -1.54% 844.6 ms +1.82% -0.8% 1.57%
firstContentfulPaint 355.49 ms +1.16% -2.19% 357.82 ms +1.5% -5.84% -0.65%
firstBlock 2516.12 ms +1.29% -1.24% 2457.92 ms +1.89% -0.99% 2.37%
type 18.31 ms +3.44% -2.95% 18.36 ms +6.92% -5.77% -0.27%
typeWithoutInspector 18.38 ms +5.77% -4.95% 17.96 ms +2.23% -3.23% 2.34%
typeWithTopToolbar 23.86 ms +3.1% -10.14% 23.46 ms +4.43% -2.47% 1.71%
typeContainer 7.81 ms +6.02% -8.07% 7.93 ms +1.39% -10.09% -1.51%
focus 59.96 ms +4.9% -3.94% 62.43 ms +17.49% -7.94% -3.96%
firstFocus 168.74 ms +0% -0% 164.87 ms +0% -0% 2.35%
selectAll 412.04 ms +5.52% -4.23% 388.01 ms +5.37% -3.04% 6.19%
listViewOpen 54.16 ms +9.42% -6.24% 53.74 ms +11.61% -8.97% 0.78%
inserterOpen 19.02 ms +13.04% -6.2% 20.44 ms +3.96% -9.25% -6.95%
inserterHover 2.43 ms +7% -6.17% 3 ms +16.67% -7.67% -19%
inserterSearch 7.36 ms +8.42% -9.24% 6.74 ms +9.05% -3.41% 9.2%
loadPatterns 532.41 ms +0.5% -5.22% 493.16 ms +6.34% -2.29% 7.96%
wpTotal 342.4 ms +1.12% -9.57% 300.31 ms +8.82% -8.01% 14.02%
wpMemoryUsage 13.05 MB +0% -0% 13.01 MB +0% -0% 0.29%
wpDbQueries 54 +0% -0% 54 +0% -0% 0%

site-editor

Metric 538b082 trunk % Change
serverResponse 496.26 ms +3.83% -2.11% 503.87 ms +1.42% -4.49% -1.51%
firstPaint 249.3 ms +11.53% -21.52% 243.13 ms +21.78% -15.6% 2.54%
domContentLoaded 1138.71 ms +2.36% -0.74% 1150.99 ms +1.61% -3.93% -1.07%
loaded 1139.92 ms +2.37% -0.74% 1152.2 ms +1.6% -3.93% -1.07%
firstContentfulPaint 446.1 ms +2.24% -0.85% 453.65 ms +2.13% -2.65% -1.66%
firstBlock 4172.21 ms +0.31% -0.11% 4128.83 ms +0.57% -1.34% 1.05%
type 21.95 ms +3.46% -4.33% 19.35 ms +3.26% -1.45% 13.44%
navigate 116.04 ms +4.44% -4.15% 119.69 ms +8.05% -2.39% -3.05%
loadPatterns 1426.3 ms +9.12% -6.83% 1358.23 ms +14.25% -1.33% 5.01%
loadPages 1071.24 ms +2.09% -0.68% 1094.22 ms +0.97% -1.68% -2.1%
wpTotal 485.97 ms +2.8% -1.98% 493.85 ms +1.56% -4.53% -1.6%
wpMemoryUsage 12.01 MB +0% -0% 11.99 MB +0% -0% 0.15%
wpDbQueries 43.5 +1.15% -1.15% 43 +2.33% -0% 1.16%

efca65c Run

@aaronrobertshaw
aaronrobertshaw marked this pull request as ready for review September 21, 2026 06:05
@github-actions

github-actions Bot commented Sep 21, 2026

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: aaronrobertshaw <aaronrobertshaw@git.wordpress.org>

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

@aaronrobertshaw aaronrobertshaw mentioned this pull request Sep 21, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ramonjd ramonjd Awaiting requested review from ramonjd
@andrewserong andrewserong Awaiting requested review from andrewserong
@talldan talldan Awaiting requested review from talldan
@tellthemachines tellthemachines Awaiting requested review from tellthemachines
@fabiankaegy fabiankaegy Awaiting requested review from fabiankaegy fabiankaegy is a code owner
@juanmaguitar juanmaguitar Awaiting requested review from juanmaguitar juanmaguitar is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

@aaronrobertshaw aaronrobertshaw

Labels

[Block] Page List Affects the Page List Block [Feature] Design Tools Tools that impact the appearance of blocks both to expand the number of tools and improve the experi Global Styles Anything related to the broader Global Styles efforts, including Styles Engine and theme.json [Package] Block library /packages/block-library [Type] Enhancement A suggestion for improvement.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@aaronrobertshaw