Skip to content

Block Supports: Add translate property on X and Y axis to Transform supports - #86282

Draft
aaronrobertshaw wants to merge 5 commits into
add/transform-block-supportfrom
add/transform-translate
Draft

Block Supports: Add translate property on X and Y axis to Transform supports#86282
aaronrobertshaw wants to merge 5 commits into
add/transform-block-supportfrom
add/transform-translate

Conversation

@aaronrobertshaw

@aaronrobertshaw aaronrobertshaw commented Nov 4, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Important

This builds on #86240 and should merge after it. Its base is that PR's branch.

Related:

What?

Adds an X and Y offset to the Transform block support, through the CSS translate property. It combines with rotation. Group, Heading, Image and Video opt in.

Why?

Blocks cannot be nudged away from where the layout puts them. The grid canvas work in #85505, where blocks are placed freely, needs this too.

How?

  • Value: style.transform.translate is { x, y }. Each axis is one length or percentage.
  • Output: the translate property, never transform. A missing axis is 0.
  • Validation: style engine, theme.json and KSES drop calc(), var(), lists and other values.
  • Unknown keys: a z key fails the schema and PHP drops it.
  • UI: X offset and Y offset fields, negatives allowed. Each resets on its own.
  • Same as rotation: states, Global Styles, settings, skip serialization and the Image selector.

Z is left out. It needs perspective on a parent, so it can follow later as one more key.

"core/heading": {
	"transform": { "translate": { "x": "3rem" } }
}

Testing Instructions

  1. Add an Image with a caption and lightbox. Set Styles > Transform > X offset and Y offset.
  2. Only the image moves, in the editor and front end. Add a rotation; both apply. The lightbox image has neither.
  3. On a Heading, choose Mobile, turn on Responsive styles and set an offset. Desktop stays in place.
  4. Add the theme.json value above. Global Styles shows 3rem, and every Heading moves.

Screenshots or screencast

translate.mp4

Use of AI Tools

Written with Claude Code, then reviewed and tested.

@aaronrobertshaw
Transform: Add translate feature for X and Y offsets
9efb307 
Store style.transform.translate as an object with x and y axes and
output the individual translate property, validated in the style engine,
theme.json and KSES. Add X offset and Y offset controls to the Transform
panel and opt in Group, Heading, Image and Video.
@aaronrobertshaw
Transform: Test the translate feature
0ca2210 
Cover the style engine, theme.json, KSES, the block support, block
states, the Transform panel and global styles rendering. Extend the e2e
spec with an Image offset, its caption and lightbox, and a Mobile offset
on a Heading.
@aaronrobertshaw
Transform: Show the X and Y offsets side by side in the block inspector
8b7cee0
@aaronrobertshaw aaronrobertshaw added [Type] Enhancement A suggestion for improvement. [Feature] Design Tools Tools that impact the appearance of blocks both to expand the number of tools and improve the experi labels Nov 4, 2026
@aaronrobertshaw aaronrobertshaw self-assigned this Nov 4, 2026
@github-actions github-actions Bot added [Package] Blocks /packages/blocks [Package] Block library /packages/block-library [Package] Block editor /packages/block-editor [Package] Style Engine /packages/style-engine labels Nov 4, 2026
@github-actions

github-actions Bot commented Nov 4, 2026 •
edited
Loading

Copy link
Copy Markdown

🤖 PR meta 🤖

Preview in WordPress Playground Preview in Storybook

📦 Bundle size

Size Change: +459 B (+0.01%)

Total Size: 8.59 MB

📦 View Changed
Filename Size Change
build/modules/lazy-editor/index.min.js 14.4 kB +5 B (+0.03%)
build/scripts/block-editor/index.min.js 543 kB +216 B (+0.04%)
build/scripts/block-library/index.min.js 415 kB +14 B (0%)
build/scripts/blocks/index.min.js 44.9 kB +13 B (+0.03%)
build/scripts/edit-site/index.min.js 376 kB +5 B (0%)
build/scripts/editor/index.min.js 559 kB +3 B (0%)
build/scripts/style-engine/index.min.js 2.49 kB +148 B (+6.32%) 🔍
build/styles/block-editor/style-rtl.css 20 kB +3 B (+0.02%)
build/styles/block-editor/style-rtl.min.css 17 kB +6 B (+0.04%)
build/styles/block-editor/style.css 20 kB +5 B (+0.02%)
build/styles/block-editor/style.min.css 17 kB +6 B (+0.04%)
build/styles/block-library/image/style-rtl.css 3.02 kB +5 B (+0.17%)
build/styles/block-library/image/style-rtl.min.css 1.97 kB +4 B (+0.2%)
build/styles/block-library/image/style.css 3.03 kB +5 B (+0.17%)
build/styles/block-library/image/style.min.css 1.95 kB +4 B (+0.21%)
build/styles/block-library/style-rtl.css 22.9 kB +5 B (+0.02%)
build/styles/block-library/style-rtl.min.css 19.4 kB +4 B (+0.02%)
build/styles/block-library/style.css 23 kB +4 B (+0.02%)
build/styles/block-library/style.min.css 19.4 kB +4 B (+0.02%)

c95bcff Run

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric def06b5 add/transform-block-support % Change
timeToFirstByte 41.75 ms +15.69% -3.23% 42 ms +16.9% -6.9% -0.6%
largestContentfulPaint 76 ms +7.89% -2.63% 72 ms +5.56% -8.33% 5.56%
lcpMinusTtfb 34.6 ms +5.78% -14.6% 27.15 ms +6.26% -4.05% 27.44%
wpBeforeTemplate 21.76 ms +15.9% -4.87% 21.59 ms +17.09% -6.76% 0.79%
wpTemplate 16.92 ms +11.88% -5.79% 16.86 ms +7.18% -5.34% 0.36%
wpTotal 38.34 ms +16.69% -3.57% 38.66 ms +16.19% -7.24% -0.83%
wpMemoryUsage 7.71 MB +0% -0% 7.70 MB +0% -0% 0.12%
wpDbQueries 16 +0% -0% 16 +0% -0% 0%

front-end-classic-theme

Metric def06b5 add/transform-block-support % Change
timeToFirstByte 34.85 ms +4.88% -2.01% 33.55 ms +11.48% -5.07% 3.87%
largestContentfulPaint 78 ms +2.56% -2.56% 76 ms +5.26% -5.26% 2.63%
lcpMinusTtfb 42.65 ms +3.17% -3.4% 40.8 ms +3.92% -1.59% 4.53%
wpBeforeTemplate 18.65 ms +4.13% -2.14% 17.87 ms +7.27% -3.25% 4.36%
wpTemplate 12.86 ms +4.43% -2.49% 12.68 ms +6.15% -8.83% 1.42%
wpTotal 31.85 ms +5.46% -1.92% 30.43 ms +13.11% -4.93% 4.67%
wpMemoryUsage 6.40 MB +0% -0% 6.39 MB +0% -0% 0.15%
wpDbQueries 13 +0% -0% 13 +0% -0% 0%

media-processing

Metric def06b5 add/transform-block-support % Change
mediaProcessingJpeg 236.77 ms +2.02% -1.17% 238.17 ms +4.89% -0.63% -0.59%
mediaProcessingAvif 3815.71 ms +0.24% -0.28% 3789.04 ms +1.37% -0.32% 0.7%
mediaProcessingJpegToAvif 2647.81 ms +1.08% -0.37% 2609.77 ms +2.3% -0.18% 1.46%

media-upload

Metric def06b5 add/transform-block-support % Change
jpegUploadProcessing 1437.06 ms +0.93% -1.34% 1434.73 ms +0.42% -1.55% 0.16%
pngUploadProcessing 208.35 ms +2.92% -3.72% 200.47 ms +2.44% -2.69% 3.93%
largeJpegUploadProcessing 1414.97 ms +0.74% -0.54% 1422.94 ms +0.4% -0.48% -0.56%
multipleImageUploadProcessing 1494.44 ms +2.18% -0.68% 1491.2 ms +0.66% -0.82% 0.22%

post-editor

Metric def06b5 add/transform-block-support % Change
serverResponse 383.22 ms +9.06% -1.6% 377.64 ms +11.03% -1.9% 1.48%
firstPaint 399.95 ms +4.01% -19.86% 369.39 ms +25.98% -16.57% 8.27%
domContentLoaded 851.23 ms +1.93% -1.48% 823.32 ms +1.82% -2.25% 3.39%
loaded 852.4 ms +1.91% -1.51% 824.32 ms +1.83% -2.24% 3.41%
firstContentfulPaint 495.53 ms +2.9% -0.95% 482.56 ms +1.01% -2.65% 2.69%
firstBlock 2111.31 ms +1.08% -0.62% 2059.14 ms +1.02% -1.23% 2.53%
type 18.87 ms +2.33% -12.4% 17.95 ms +1% -13.48% 5.13%
typeWithoutInspector 17.79 ms +3.6% -2.92% 16.62 ms +11.13% -6.44% 7.04%
typeWithTopToolbar 23.5 ms +6.38% -5.45% 23.03 ms +1.74% -8.12% 2.04%
typeContainer 8.38 ms +10.26% -16.71% 7.94 ms +4.91% -7.81% 5.54%
focus 120.06 ms +1.28% -2.12% 119.62 ms +4.71% -4.01% 0.37%
firstFocus 259.77 ms +0% -0% 253.7 ms +0% -0% 2.39%
selectAll 340.63 ms +2.84% -0.77% 361.23 ms +0.02% -1.12% -5.7%
undo 30.43 ms +7.99% -3.38% 31.53 ms +4.92% -5.84% -3.49%
listViewOpen 79.42 ms +6.03% -11.72% 77.01 ms +6.34% -5.61% 3.13%
inserterOpen 44.32 ms +3.43% -13.27% 44.09 ms +17.01% -10.8% 0.52%
inserterHover 11.28 ms +14.72% -6.83% 11.89 ms +5.63% -8.83% -5.13%
inserterSearch 8.66 ms +10.28% -3.35% 9.01 ms +5.44% -12.54% -3.88%
loadPatterns 667.8 ms +0.45% -3.83% 663.52 ms +7.81% -5.3% 0.65%
wpTotal 373.77 ms +9.27% -1.65% 368.27 ms +11% -2% 1.49%
wpMemoryUsage 14.76 MB +0% -0% 14.73 MB +0% -0% 0.18%
wpDbQueries 55 +0% -0% 55 +0% -0% 0%

site-editor

Metric def06b5 add/transform-block-support % Change
serverResponse 289.5 ms +6.08% -6.37% 296.61 ms +3.38% -1.54% -2.4%
firstPaint 292.36 ms +6.03% -7.57% 268.7 ms +8.72% -2.23% 8.81%
domContentLoaded 660.2 ms +7.48% -2.29% 651.17 ms +2.47% -1.83% 1.39%
loaded 661.2 ms +7.44% -2.3% 651.93 ms +2.47% -1.81% 1.42%
firstContentfulPaint 386.79 ms +7.06% -3.01% 380.12 ms +2.05% -0.86% 1.75%
firstBlock 1924.63 ms +6.42% -3.79% 1861.38 ms +0.96% -0.52% 3.4%
type 16.53 ms +6.05% -6.41% 16.28 ms +2.64% -12.59% 1.54%
navigate 92.68 ms +9.6% -6.03% 100.01 ms +1.68% -4.83% -7.33%
loadPatterns 1059.78 ms +15.23% -8.89% 1133.3 ms +6.1% -16.35% -6.49%
loadPages 1008.41 ms +2.19% -1.09% 1044.38 ms +2.47% -3.19% -3.44%
wpTotal 279.78 ms +6.85% -5.76% 289.15 ms +3.33% -1.56% -3.24%
wpMemoryUsage 12.78 MB +0% -0% 12.77 MB +0% -0% 0.09%
wpDbQueries 45 +0% -0% 45 +0% -0% 0%

c95bcff Run

🏁 Flaky tests

Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

Undo restores the post selection when another synced entity is loaded (RTC WebSocket) in /test/e2e/specs/editor/collaboration/collaboration-undo-redo.spec.ts, passed after 1 failed attempt. 
Error: expect(received).toMatchObject(expected)

- Expected  - 2
+ Received  + 2

  Object {
    "attributeKey": "content",
    "blockIndex": 0,
    "content": "abcdef",
-   "endOffset": 3,
-   "offset": 3,
+   "endOffset": 6,
+   "offset": 6,
  }

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/collaboration-undo-redo.spec.ts:363:5
moves selected text into another paragraph in /test/e2e/specs/editor/various/draggable-blocks.spec.js, passed after 1 failed attempt. 
Error: expect(received).toMatchObject(expected)

- Expected  - 2
+ Received  + 2

  Array [
    Object {
      "attributes": Object {
-       "content": "First third",
+       "content": "First second third",
      },
      "name": "core/paragraph",
    },
    Object {
      "attributes": Object {
-       "content": "Fourth second fifth",
+       "content": "Fourth fifth",
      },
      "name": "core/paragraph",
    },
  ]

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/draggable-blocks.spec.js:1167:41
should insert mention in a table block in /test/e2e/specs/editor/various/autocomplete-and-mentions.spec.js, passed after 2 failed attempts. 
Error: apiRequestContext.fetch: socket hang up
Call log:
  - → DELETE http://localhost:8891/wp-json/wp/v2/users/32?force=true&reassign=1
    - user-agent: Playwright/1.63.0 (x64; ubuntu 24.04) node/24.20 CI/1
    - accept: */*
    - accept-encoding: gzip,deflate,br
    - X-WP-Nonce: fb0bbd2a7f
    - cookie: wordpress_test_cookie=WP%20Cookie%20check; wordpress_logged_in_da433b7faafd8180ebeb1624ceeeab7e=admin%7C1793938741%7CIDb9GHo8Av8QLUV6Q0jTEZwurc0xTKXo5QzUMoB5xxJ%7Ca01ca84644c027b0f6e22fba2e7325ee3dc63b67f9894dace6a600a7b25ee66f; wp-settings-time-1=1793766616

    at RequestUtils.rest (/home/runner/work/gutenberg/gutenberg/packages/e2e-test-utils-playwright/src/request-utils/rest.ts:111:39)
    at RequestUtils.deleteUser (/home/runner/work/gutenberg/gutenberg/packages/e2e-test-utils-playwright/src/request-utils/users.ts:91:30)
    at map (/home/runner/work/gutenberg/gutenberg/packages/e2e-test-utils-playwright/src/request-utils/users.ts:116:51)
    at RequestUtils.deleteAllUsers (/home/runner/work/gutenberg/gutenberg/packages/e2e-test-utils-playwright/src/request-utils/users.ts:116:5)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/autocomplete-and-mentions.spec.js:73:3
three users concurrently edit a large post with diverse blocks in /test/e2e/specs/editor/collaboration/collaboration-stress.spec.ts, passed after 1 failed attempt. 
TimeoutError: locator.waitFor: Timeout 17500ms exceeded.
Call log:
  - waiting for getByRole('button', { name: /Collaborators list/ }) to be visible

    at map (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/fixtures/collaboration-utils.ts:193:7)
    at CollaborationUtils.waitForMutualDiscovery (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/fixtures/collaboration-utils.ts:188:10)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/collaboration-stress.spec.ts:416:28

From 760e63b, not the current head. Run

@aaronrobertshaw aaronrobertshaw changed the title Transform: Add X and Y offsets with the translate property Block Supports: Add translate property on X and Y axis to Transform supports Nov 4, 2026
@aaronrobertshaw aaronrobertshaw mentioned this pull request Nov 4, 2026
Draft

This branch has not been deployed

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

Reviewers

@tellthemachines tellthemachines Awaiting requested review from tellthemachines tellthemachines will be requested when the pull request is marked ready for review tellthemachines is a code owner
@spacedmonkey spacedmonkey Awaiting requested review from spacedmonkey spacedmonkey will be requested when the pull request is marked ready for review spacedmonkey is a code owner
@ellatrix ellatrix Awaiting requested review from ellatrix ellatrix will be requested when the pull request is marked ready for review ellatrix is a code owner
@fabiankaegy fabiankaegy Awaiting requested review from fabiankaegy fabiankaegy will be requested when the pull request is marked ready for review fabiankaegy is a code owner
@juanmaguitar juanmaguitar Awaiting requested review from juanmaguitar juanmaguitar will be requested when the pull request is marked ready for review juanmaguitar is a code owner

Assignees

@aaronrobertshaw aaronrobertshaw

Labels

[Feature] Design Tools Tools that impact the appearance of blocks both to expand the number of tools and improve the experi [Package] Block editor /packages/block-editor [Package] Block library /packages/block-library [Package] Blocks /packages/blocks [Package] Style Engine /packages/style-engine [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