Block Supports
The Block Supports API allows a block to opt in or out of certain core features.
Opting into any of these features will register additional attributes on the block and provide the UI to manipulate that attribute.
anchor
- Type:
boolean
- Default value:
false
Anchors let you link directly to a specific block on a page. This property adds a field to define an id for the block and a button to copy the direct link.
This doesn't work with dynamic blocks yet. If you need to add Anchor support to a block that uses PHP rendering you need to manually add the attribute and UI for it.
// Declare support for anchor links.
"supports": {
"anchor": true
}
align
- Type:
boolean
orarray
- Default value:
false
This property adds block controls which allow to change block's alignment.
"supports": {
// Declare support for block's alignment.
// This adds support for all the options:
// left, center, right, wide, and full.
"align": true
}
"supports": {
// Declare support for specific alignment options.
"align": [ "left", "right", "full" ]
}
When the block declares support for align
, the attributes definition is extended to include an align attribute with a string
type. By default, no alignment is assigned. The block can apply a default alignment by specifying its own align
attribute with a default e.g.:
"attributes": {
"align": {
"type": "string",
"default": "right"
}
}
alignWide
- Type:
boolean
- Default value:
true
This property allows to enable wide alignment for your theme. To disable this behavior for a single block, set this flag to false
.
"supports": {
// Remove the support for wide alignment.
"alignWide": false
}
ariaLabel
- Type:
boolean
- Default value:
false
ARIA-labels let you define an accessible label for elements. This property allows enabling the definition of an aria-label for the block.
This option does not add any UI to the block editor. It is purely there for developers to add aria-label definitions to patterns, variations etc.
supports: {
// Add the support for aria label attribute
ariaLabel: true
}
className
- Type:
boolean
- Default value:
true
By default, the class .wp-block-your-block-name
is added to the root element of your saved markup. This helps having a consistent mechanism for styling blocks that themes and plugins can rely on. If, for whatever reason, a class is not desired on the markup, this functionality can be disabled.
In general it is recommended for consistency sake to stick with the core generated className
"supports": {
// Remove the support for the generated className.
"className": false
}
color
- Type:
Object
- Default value: null
- Subproperties:
background
: typeboolean
, default valuetrue
gradients
: typeboolean
, default valuefalse
link
: typeboolean
, default valuefalse
text
: typeboolean
, default valuetrue
This value signals that a block supports some of the properties related to color. When it does, the block editor will show UI controls for the user to set their values.
Note that the background
and text
keys have a default value of true
, so if the color
property is present they'll also be considered enabled:
"supports": {
"color": {
// This also enables text and background UI controls.
"gradients": true // Enable gradients UI control.
}
}
It's possible to disable them individually:
"supports": {
"color": { // Text UI control is enabled.
"background": false, // Disable background UI control.
"gradients": true // Enable gradients UI control.
}
}
color.background
This property adds UI controls which allow the user to apply a solid background color to a block.
When color support is declared, this property is enabled by default (along with text), so simply setting color will enable background color.
"supports": {
"color": true // Enables background and text
}
To disable background support while keeping other color supports enabled, set to false
.
"supports": {
"color": {
// Disable background support. Text color support is still enabled.
"background": false
}
}
When the block declares support for color.background
, the attributes definition is extended to include two new attributes: backgroundColor
and style
:
-
backgroundColor
: attribute ofstring
type with no default assigned.When a user chooses from the list of preset background colors, the preset slug is stored in the
backgroundColor
attribute.Background color presets are sourced from the
editor-color-palette
theme support.The block can apply a default preset background color by specifying its own attribute with a default e.g.:
attributes: {
"backgroundColor": {
"type": "string",
"default": "some-preset-background-slug",
}
} -
style
: attribute ofobject
type with no default assigned.When a custom background color is selected (i.e. using the custom color picker), the custom color value is stored in the
style.color.background
attribute.The block can apply a default custom background color by specifying its own attribute with a default e.g.:
"attributes": {
"style": {
"type": "object",
"default": {
"color": {
"background": "#aabbcc",
}
}
}
}
color.gradients
This property adds UI controls which allow the user to apply a gradient background to a block.
"supports": {
"color": {
"gradients": true,
// Default values must be disabled if you don't want to use them with gradient.
"background": false,
"text": false
}
}
Gradient presets are sourced from editor-gradient-presets
theme support.
When the block declares support for color.gradient
, the attributes definition is extended to include two new attributes: gradient
and style
:
-
gradient
: attribute ofstring
type with no default assigned.When a user chooses from the list of preset gradients, the preset slug is stored in the
gradient
attribute.The block can apply a default preset gradient by specifying its own attribute with a default e.g.:
"attributes": {
"gradient": {
"type": "string",
"default": "some-preset-gradient-slug",
}
} -
style
: attribute ofobject
type with no default assigned.When a custom gradient is selected (i.e. using the custom gradient picker), the custom gradient value is stored in the
style.color.gradient
attribute.The block can apply a default custom gradient by specifying its own attribute with a default e.g.:
attributes: {
"style": {
"type": "object",
"default": {
"color": {
"gradient": "linear-gradient(135deg,rgb(170,187,204) 0%,rgb(17,34,51) 100%)",
}
}
}
}
color.link
This property adds block controls which allow the user to set link color in a block, link color is disabled by default.
"supports": {
"color": true // Enables only background and text
}
To enable link color support, set to true
.
"supports": {
"color": {
"link": true
}
}
Link color presets are sourced from the editor-color-palette
theme support.
When the block declares support for color.link
, the attributes definition is extended to include two new attributes: linkColor
and style
:
-
linkColor
: attribute ofstring
type with no default assigned.When a user chooses from the list of preset link colors, the preset slug is stored in the
linkColor
attribute.The block can apply a default preset text color by specifying its own attribute with a default e.g.:
attributes: {
"linkColor": {
"type": "string",
"default": "some-preset-link-color-slug",
}
} -
style
: attribute ofobject
type with no default assigned.When a custom link color is selected (i.e. using the custom color picker), the custom color value is stored in the
style.color.link
attribute.The block can apply a default custom link color by specifying its own attribute with a default e.g.:
attributes: {
"style": {
"type": "object",
"default": {
"color": {
"link": "#ff0000",
}
}
}
}
color.text
This property adds block controls which allow the user to set text color in a block.
When color support is declared, this property is enabled by default (along with background), so simply setting color will enable text color.
"supports": {
"color": true // Enables background and text, but not link.
}
To disable text color support while keeping other color supports enabled, set to false
.
"supports": {
"color": {
// Disable text color support.
"text": false
}
}
Text color presets are sourced from the editor-color-palette
theme support.
When the block declares support for color.text
, the attributes definition is extended to include two new attributes: textColor
and style
:
-
textColor
: attribute ofstring
type with no default assigned.When a user chooses from the list of preset text colors, the preset slug is stored in the
textColor
attribute.The block can apply a default preset text color by specifying its own attribute with a default e.g.:
"attributes": {
"textColor": {
"type": "string",
"default": "some-preset-text-color-slug",
}
} -
style
: attribute ofobject
type with no default assigned.When a custom text color is selected (i.e. using the custom color picker), the custom color value is stored in the
style.color.text
attribute.The block can apply a default custom text color by specifying its own attribute with a default e.g.:
"attributes": {
"style": {
"type": "object",
"default": {
"color": {
"text": "#aabbcc",
}
}
}
}
customClassName
- Type:
boolean
- Default value:
true
This property adds a field to define a custom className for the block's wrapper.
"supports": {
// Remove the support for the custom className.
"customClassName": false
}
defaultStylePicker
- Type:
boolean
- Default value:
true
When the style picker is shown, the user can set a default style for a block type based on the block's currently active style. If you prefer not to make this option available, set this property to false
.
"supports": {
// Remove the Default Style picker.
"defaultStylePicker": false
}