Form Block: Global styles affect nested blocks

It’s reported, the current implementation of the Form Block can affect the global styleStyle When you select a CF7 Skins Style the aesthetic design (CSS code) is automatically created and applied to your form. of all blocks nested within a Form Block.

Table of Contents #

• Problem
• Current situation
• Exploration
• Solution
• Testing
• Pull Request

Problem #

Form Block: Global styles affect all form elements #56784

In the form block, the form element is specified as __experimentalSelector, so the global style affects all form elements.

gutenberg/packages/block-library/src/form/block.json

Line 57 in 19f944d

“__experimentalSelector”: “form”

I think that this is not the intended behavior and that this selector should be removed.

It’s reported, the current implementation of the Form Block can affect the global style of blocks nested within a Form Block. Global Styles applied to the Form block currently unintentionally affect other blocks nested within the Form block.

The "__experimentalSelector": "form" setting in block.json targets the <form> element rendered by the Form block. Styles applied to the Form block (via style variations or custom CSS) will correctly target that form.

However, if you place other blocks, like paragraphs, headings, or even other form-related blocks, inside the Form block in the editor, those nested blocks might inherit or be unintentionally affected by the styles intended for the outer <form> element. This happens because the styles are scoped to the <form> element but are still within the DOM hierarchy that encompasses the nested blocks.

Global Styles applied to the Form block should not unintentionally affect other blocks nested within the Form block.

back to top

Current situation #

Code

https://github.com/WordPress/gutenberg/blob/19f944db51b5c2f4ef06ba60377e1cb9e3201abd/packages/block-library/src/form/block.json#L57

Questions #

• Explain – what does this line of code do?
  • Does this line of code currently serve any purpose?
  • Can this line of code be removed without any consequences?
• Do nested Blocks within other Blocks have similar issues?
  • If not, how are these issues prevented?
• What the best solution to preventing this issue on the Form Block?

Explain – what does this line of code do? #

The line “__experimentalSelector”: “form” in the block.json file for the Form block in the Gutenberg editor, is a special property that defines the CSS selector used for the block’s wrapper element. It defines an experimental feature that allows targeting the HTML form element rendered by the block in the editor’s styles.

This property tells the block editor which HTML element to target when applying styles to the block. In this case, it specifies that styles should be applied to the <form> element directly, rather than to a wrapper div that might otherwise contain the form.

This means that any custom CSS applied using the block’s style variations or additional CSS classes can directly affect the form element itself, providing more granular control over its appearance.

The __experimental prefix indicates that this functionality is subject to change or removal in future versions.

The reported issue is for any other Blocks added within the Form Block.

The issue reported in the Gutenberg GitHub issue #56784 is about styles applied to the Form block unintentionally affecting other blocks nested within the Form block.

The "__experimentalSelector": "form" setting in block.json targets the <form> element rendered by the Form block. Styles applied to the Form block (via style variations or custom CSS) will correctly target that form.

However, if you place other blocks, like paragraphs, headings, or even other form-related blocks, inside the Form block in the editor, those nested blocks might inherit or be unintentionally affected by the styles intended for the outer <form> element. This happens because the styles are scoped to the <form> element but are still within the DOM hierarchy that encompasses the nested blocks.

This can be a problem for the layout and styling of content inside the Form block that isn’t meant to be part of the form’s visual styling.

Can this code affect the styling of other form elements on a post or page that are not created by the Form Block?

The __experimentalSelector property within the supports object of a block’s block.json file allows you to target the main element rendered by the block with CSS selectors. In this case, with "__experimentalSelector": "form", any custom styles applied to the Form block through block style variations or additional CSS classes will specifically target the <form> element generated by the block.

However, the crucial point is that these styles are scoped to the specific instance of the Form block to which they are applied. They will not affect other <form> elements on the page or post unless those elements also happen to be instances of the Form block and have the same styles applied to them.

This feature provides targeted styling for the Form block’s output and shouldn’t interfere with the styling of other form elements on the page.

Do nested Blocks within other Blocks have similar issues? #

No – this issue is solved by using the selectors API.

back to top

Exploration #

What the best solution to preventing this issue on the Form Block? #

The selectors API is the recommended approach moving forward.

Selectors API Documentation

1. Block Selectors Reference Guide:

// docs/reference-guides/block-api/block-selectors.md

# Selectors

Block Selectors is the API that allows blocks to customize the CSS selector used
when their styles are generated.

A block may customize its CSS selectors at three levels: root, feature, and
subfeature.

## Root selector

The root selector is the block's primary CSS selector.

All blocks require a primary CSS selector for their style declarations to be
included under. If one is not provided through the Block Selectors API, a
default is generated in the form of `.wp-block-<name>`.

2. Block Metadata Documentation:

// docs/reference-guides/block-api/block-metadata.md


### Selectors

-   Type: `object`
-   Optional
-   Localized: No
-   Property: `selectors`
-   Default: `{}`
-   Since: `WordPress 6.3.0`

Any custom CSS selectors, keyed by `root`, feature, or sub-feature, to be used
when generating block styles for theme.json (global styles) stylesheets.
Providing custom selectors allows more fine grained control over which styles
apply to what block elements, e.g. applying typography styles only to an inner
heading while colors are still applied on the outer block wrapper etc.

Key Points

1. Official Since WordPress 6.3: The selectors API has been officially part of WordPress since version 6.3
2. Deprecation Path: The code shows that __experimentalSelector is used as a fallback when the newer API isn’t available
3. More Granular Control: The newer API allows for feature and subfeature level selector customization
4. Hierarchical Structure: The API supports a more organized approach to styling different parts of blocks
5. Future Direction: The implementation clearly shows the direction WordPress is moving with block styling

Moving from __experimentalSelector to the newer selectors API aligns with WordPress’s direction for block styling and provides better control over how styles are applied to different elements within the block.

Maintains Block Editor Conventions: Aligns with how most other blocks handle styling.

Examples of Blocks Using Class-Based Selectors

1. Group Block:

// packages/block-library/src/group/block.json

{
  "selectors": {
    "root": ".wp-block-group"
  }
}

2. Columns Block:

// packages/block-library/src/columns/block.json

{
  "selectors": {
    "root": ".wp-block-columns"
  }
}

3. Button Block:

// packages/block-library/src/button/block.json

{
  "selectors": {
    "root": ".wp-block-button"
  }
}

Documentation References

1. Block Styles Documentation:

// docs/reference-guides/block-api/block-styles.md

Block Styles allow alternative styles to be applied to existing blocks. 
They work by adding a className to the block's wrapper. 
This className can be used to provide an alternative styling for the block if the block style is selected.

2. Style Engine Documentation:

// packages/style-engine/docs/using-the-style-engine-with-block-supports.md

When [registering a block support](https://developer.wordpress.org/reference/classes/wp_block_supports/register/), 
it is possible to pass an 'apply' callback in the block support config array to add 
or extend block support attributes with "class" or "style" properties.

3. Styles Architecture Documentation:

// docs/explanations/architecture/styles.md

The user may change the state of this block by applying different styles: a text alignment, 
a color, a font size, a line height, etc. These states are reflected in the HTML markup 
of the block in the form of HTML attributes, mainly through the `class` or `style` 
attributes, though it can be any other the block author sees fit.

Key Points

1. Consistency with Core Blocks: Most core blocks use class-based selectors rather than element selectors
2. Isolation of Styles: The documentation emphasizes component isolation through class names
3. Block Wrapper Conventions: The block wrapper documentation recommends using class-based approaches for styling
4. Style Engine Design: The style engine is designed to work with class-based selectors for better specificity control
5. Future Compatibility: The newer selectors API is the recommended approach moving forward

This change brings the Form block in line with WordPress core block styling conventions, which use class-based selectors to maintain style isolation between blocks and their children.

Explain how “Modify the CSS selector approach to be more specific and prevent style inheritance” works – include benefits & disadvantages.

The current approach uses "__experimentalSelector": "form", which targets the HTML <form> element directly. This causes styles to cascade down to all child elements within the form.

The proposed modification changes this to use a class-based selector:

// packages/block-library/src/form/block.json
{
  "__experimentalSelector": ".wp-block-form",
  "selectors": {
    "root": ".wp-block-form"
  }
}

This works by:

1. Using a class-based selector (.wp-block-form) instead of an element selector (form)
2. Leveraging the newer selectors API which provides more control over style application
3. Ensuring styles target only the form container itself, not its children

Benefits:

1. Prevents Unintended Style Inheritance: Styles applied to the form block won’t automatically cascade to child elements
2. Better Isolation: Each block maintains its own styling independence
3. More Predictable Behavior: Users can style the form container without affecting inputs
4. Maintains Block Editor Conventions: Aligns with how most other blocks handle styling
5. Future-Proof: Uses the newer selectors API which is the recommended approach

Disadvantages:

1. Additional Wrapper: May require an additional wrapper div with the class, potentially adding to DOM complexity
2. Migration Needed: Existing sites using the form block might see styling changes
3. Some Styles Need Re-application: Users would need to explicitly style form elements separately
4. Potential Specificity Issues: May require careful CSS specificity management if other selectors target form elements
5. Implementation Complexity: Requires changes to both the block definition and possibly the edit/save components

Technical Implementation Details:

When the block editor applies global styles, it uses the getBlockCSSSelector function to determine which selector to use. By changing from an element selector to a class selector, we’re telling the system to generate CSS rules that only target elements with that specific class, rather than all elements of a certain type.

The WordPress global styles system would then generate CSS like:

:root :where(.wp-block-form) { /* styles */ }

Instead of:

:root :where(form) { /* styles */ }

It’s reported Global Styles applied to the Form block unintentionally affect other blocks nested within the Form block.

See https://github.com/WordPress/gutenberg/issues/56784

How can this be prevented.

The issue is that global styles applied to the Form block are cascading down to all nested blocks because of the __experimentalSelector: "form" setting. This causes styles to be applied to the <form> element, which then affects all child elements.

To fix this in the form block code, you could:

1. Modify the CSS selector approach to be more specific and prevent style inheritance:

// packages/block-library/src/form/block.json
{
  "__experimentalSelector": ".wp-block-form",
  "selectors": {
    "root": ".wp-block-form"
  }
}

2. Add a style isolation mechanism in the form block’s edit.js and save.js:

// packages/block-editor/src/components/global-styles/utils.js
export function scopeSelector( selector, scope ) {
  // ...existing code...
}

The most effective approach would be to change the __experimentalSelector to use a class-based selector instead of the element selector, as this would prevent the styles from automatically cascading to all form elements.

back to top

Testing #

What blocks are available to be nested inside the Form block?

// packages/block-library/src/form/block.json

{
    "allowedBlocks": [
        "core/paragraph",
        "core/heading",
        "core/form-input",
        "core/form-submit-button",
        "core/form-submission-notification",
        "core/group",
        "core/columns"
    ]
}

Allowed Blocks:

1. core/paragraph – Text paragraphs for form descriptions or instructions
2. core/heading – Section headings to organize form content
3. core/form-input – Various input fields (text, email, checkbox, etc.)
4. core/form-submit-button – The submit button for the form
5. core/form-submission-notification – Success/error messages after submission
6. core/group – Container to group related form elements
7. core/columns – Multi-column layout for form elements

back to top

Confirm Issue #

back to top

Solution #

		"__experimentalSelector": ".wp-block-form",
		"selectors": {
			"root": ".wp-block-form"
		}

The selected code includes both:

• "__experimentalSelector": ".wp-block-form" and
• "selectors": { "root": ".wp-block-form" }

rather than just the selectors property for several important reasons:

Why Both Properties Are Included

1. Backward Compatibility:
   • The __experimentalSelector property is the older API that some parts of the codebase might still rely on
   • From the code in get-block-css-selector.js, we can see it checks for both properties:
2. Transition Period:
   • WordPress is in a transition period between the older experimental API and the newer stable API
   • Including both ensures the block works correctly across different WordPress versions
3. Different Processing Paths:
   • Some parts of the codebase might process the experimental property directly
   • Other newer parts use the structured selectors object
4. Compatibility with Plugins:
   • Third-party plugins or themes might rely on the experimental property
   • Removing it could break compatibility with these extensions

Including both properties ensures the block works correctly in all contexts while following the recommended path toward the newer, more structured API.

back to top

Pull Request #

back to top

Heading #

back to top

Heading #

The overall goal is to make adding simple forms as easy as adding any other content block.

back to top

Further reading

• Item

back to top

NOTES:

It’s important the Form Block Experiment does not have any unintended consequences on a WordPress site when a user tries using the Form Block. It’s reported, the current implementation of the Form Block can affect the global style of all form elements on a page or post, regardless of how other forms on the page are created.

As an experiment, the Form Block should have no side affects on any elements on a post or page other than those elements that are actually created by the Form Block.

This can only happen at this stage if:

• the Gutenberg plugin is activate &
• the Form and Input blocks option is is set under Experimental settings.

It’s important the Form Block Experiment does not have any unintended consequences on a WordPress site when a user tries using the Form Block.

• Does the Form Block affect the styling of forms created by other form plugins on the same page – No
• How do existing form plugins prevent their styling from affecting the styling of other forms on the same page? – Not relevant