Skip to content

Enhancement: Add linkedByDefault spacing setting to theme.json - #84719

Open
sarthaknagoshe2002 wants to merge 3 commits into
WordPress:trunkfrom
sarthaknagoshe2002:fix/issue-70646
Open

sarthaknagoshe2002 wants to merge 3 commits into
WordPress:trunkfrom
sarthaknagoshe2002:fix/issue-70646

Conversation

@sarthaknagoshe2002

Copy link
Copy Markdown
Contributor

What?

Closes #70646

This PR introduces a new theme.json setting, settings.spacing.linkedByDefault, which allows theme developers to determine whether margin and padding controls should have their sides linked or unlinked by default in the block editor.

To ensure strict backward compatibility, this setting defaults to true. It accepts either a global boolean or a granular object ({ margin: boolean, padding: boolean }) for independent control.

Why?

Currently, when a user adds a block and attempts to adjust the margin, the top and bottom margin settings are linked by default, which often results in both margins being changed simultaneously. This contrasts with standard block spacing paradigms where typically only a top margin is applied.

While developers could previously use the register_block_type_args filter to restrict spacing support to only the top side, this aggressively removed the ability for users to edit the other sides. This PR provides a non-destructive UI solution that makes it easier to adjust a single side by default without taking any design tools away from the editor.

How?

  • Added linkedByDefault (boolean or object) to theme.json schema and allowlisted it in the PHP and JS style engines.
  • Updated DimensionsPanel to fetch the setting and pass strict marginLinked and paddingLinked booleans.
  • Updated BoxControl and SpacingSizesControl to default to unlinked when empty, while preserving the linked view for existing uniform attributes.

Testing Instructions

  1. In your testing environment, modify your active theme's theme.json to include the new setting. Test both the global boolean and the object override:
   "settings": {
       "spacing": {
           "linkedByDefault": false
       }
   }
  1. Alternatively, test the granular object:
"settings": {
    "spacing": {
        "linkedByDefault": {
            "margin": false,
            "padding": true
        }
    }
}
  1. Open a post or page in the block editor.
  2. Insert a Group block (ensure it has no previously saved spacing values).
  3. Open the Dimensions panel in the inspector controls.
  4. Verify that the Margin (and/or Padding, depending on your test config) controls render as unlinked by default (showing 4 individual side sliders/inputs).
  5. Verify that you can still manually click the "Link sides" button to bind them together.
  6. Insert a block that already has uniform spacing values saved to it. Verify that the controls correctly initialize as linked, overriding the linkedByDefault: false preference to match the block's existing data.

Screenshots or screencast

image

@github-actions github-actions Bot added [Package] Components /packages/components [Package] Block editor /packages/block-editor labels Oct 14, 2026
@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown

🤖 PR meta 🤖

Preview in WordPress Playground

🎉 Props

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: mirka <0mirka00@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>
Co-authored-by: andreawetzel <awetz583@git.wordpress.org>

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

Updated as activity occurs, without notifying anyone named here. Add the props-bot label to refresh.

🏷️ Labels

This pull request needs exactly one label indicating its type, and has 0.

  • Required: any label starting with [Type].
  • Found: none.

Read more about Type labels in Gutenberg. If you cannot add labels yourself, a reviewer can do it for you.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new effects make a default prop reset the user’s linked state whenever linkedByDefault changes after mount. This is not how we expect "default" props to work. Can we apply linkedByDefault only in the state initializer and remove usePrevious, inputValuesRef, and both effects?

const inputValues = values || DEFAULT_VALUES;
const inputValuesRef = useRef( inputValues );

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we use the same initialization-only approach here and remove the synchronization effect, previous-value tracking, and refs? Comparing sides by reference resets the user’s selected view when a parent passes a new array with identical contents, even without the new setting. Applying the default only in getInitialView would avoid that regression and leave subsequent link changes under the user’s control.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed this in 2ff753d.

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

Labels

[Package] Block editor /packages/block-editor [Package] Components /packages/components

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add option to unlink margin and padding sides by default

2 participants