Document the supports style properties that were deemed stable during 5.6 cycle #26771
Conversation
oandregal
requested review from
ajitbohra,
chrisvanpatten and
mkaz
as code owners
oandregal
added
[Feature] Block API
|
Cross-posting #24422 for visibility: it'd be great to use the existing block.json data to show which blocks support each property here. This data lives now in this document which is sourced manually, so it's prone to be outdated (it already is as it doesn't have info about spacing, for example) https://developer.wordpress.org/block-editor/developers/themes/theme-json/#styles |
|
Size Change: +1.32 kB (0%) Total Size: 1.21 MB
ℹ️ View Unchanged
|
|
A prospective text for the block supports dev note: Blocks can declare support for style propertiesWordPress 5.6 introduces a new API for blocks to declare support for some style properties via the supports: {
color: {
background: true, // Enable background color UI control.
gradient: true, // Enable gradient color UI control.
text: true // Enable text color UI control.
},
fontSize: true, // Enable font size UI control.
lineHeight: true // Enable line height UI control.
}For some of these properties, the active theme may need to opt-in for them to be enabled. That's the case of lineHeight, for example. How it worksWhen the user interacts with the controls, they will automatically attach the style value to the wrapper element of the block. This works as it did before:
Note that these are attached to the wrapper element of the block, so it works best with blocks that follow the newest apiVersion (see related dev note). The UI controls that present users with a set of preset values, take them from the corresponding theme supports:
In depthWhen blocks declare support for a style property, they also gain additional block attributes. These can also be used to set default values: attributes: {
backgroundColor: {
type: 'string',
default: 'value',
},
gradient: {
type: 'string',
default: 'value',
},
textColor: {
type: 'string',
default: 'value',
},
fontSize: {
type: 'string',
default: 'value'
},
style: {
type: 'Object',
default: {
color: {
background: 'value',
gradient: 'value',
link: 'value',
text: 'value'
},
typography: {
fontSize: 'value',
lineHeight: 'value',
}
}
}
}The attributes |
|
@youknowriad feel free to edit directly the comment with text for the dev note. |
| @@ -163,3 +309,40 @@ supports: { | |||
| reusable: false | |||
| } | |||
| ``` | |||
|
|
|||
| ## spacing | |||
There was a problem hiding this comment.
Is this stable? I mean the block support is stable but I'm not sure we have a stable way to enable the UI for themes.
There was a problem hiding this comment.
It looks like it is, as per #25788
There was a problem hiding this comment.
Oh, however, that requires global styles to pass the setting down to the block editor. I guess that was what you were thinking of? Should we add back at least the comments in the theme support docs about this only working for the plugin?
There was a problem hiding this comment.
Added a comment about the things that require theme support to work 67dd1c5
There was a problem hiding this comment.
Prepared #26859 to tweak the docs and signal that custom-spacing theme support still requires the plugin to work.
|
@nosolosw the dev note is great, I think we need to clarify the "requirements". Meaning these only apply to the block wrapper and that it's better used in conjunction with I'm not sure we need to detail the block attributes in the dev note but maybe a link to the block supports documentation at the end could be helpful. |
|
@youknowriad tweaked a bit the dev note adding a longer intro and explaining how it works. How does it look? |
|
Awesome. Now that I think about it, it's probably a good idea to expand on the dynamic blocks support for this |
This documents how blocks declare support for some style properties -color, font size, spacing, line height- that were deemed stabled during the WordPress 5.6 release cycle.
Note that:
__experimentalare not documented, as they are still in the experimental phase.color.linkproperty is no longer marked as experimental but still requires experimental theme support, so this hasn't been documented either.