WordPress Block Supports: The Controls Themes Can Expose

WordPress block supports are standard capabilities a block declares. They can add colour, spacing, typography, layout, locking, and other editor controls. WordPress handles much of the related storage and output.

Three layers determine the visible result. The block opts into a feature. The theme supplies or limits choices. The user selects an allowed value.

A theme cannot reliably force support the block never declared. A block declaration also does not guarantee every theme exposes unlimited choices. Compatibility requires the whole handshake.

The block-supports handshake

1. Block

Declares a supported capability.

2. Theme

Provides presets, defaults, and restrictions.

3. User

Chooses an available value.

WordPress connects these layers through shared APIs. Developers avoid rebuilding common controls. Themes gain more consistent design integration across supported blocks.

Where blocks declare supports

Modern blocks usually declare supports within block.json. The supports object contains booleans or nested options. WordPress reads those declarations during registration.

{
  "supports": {
    "color": true,
    "spacing": {
      "margin": true,
      "padding": true
    },
    "typography": {
      "fontSize": true,
      "lineHeight": true
    }
  }
}

This example opts into colour, margin, padding, font size, and line height. Theme configuration can still narrow available values. User roles can affect access.

What WordPress adds automatically

A support declaration can extend the block’s attributes. WordPress can add sidebar controls, toolbar controls, classes, styles, and wrapper properties. Exact behaviour varies by support.

Developers still need correct wrapper integration. Static blocks use saved block props. Dynamic blocks use server wrapper helpers. Missing integration can break frontend output.

The official Block Supports reference documents each capability and generated attribute. Treat that reference as version-specific authority.

Colour supports

Colour supports can expose text, background, gradient, link, heading, button, and related controls. Available subfeatures depend on the block and WordPress version.

Theme palettes provide named presets. Users may receive custom colour controls when allowed. Presets create more durable design references than arbitrary values.

A block must apply generated wrapper properties or suitable selectors. Otherwise, saved colour choices may not reach the intended element. Complex blocks need deliberate targeting.

Every available pairing needs contrast testing. Supporting colour does not make all user choices accessible. Themes should provide a restrained, tested palette.

Spacing supports

Spacing supports can expose margin, padding, and block gap. Themes can provide spacing presets and custom-value rules. Blocks can enable only suitable directions.

Not every block should offer every spacing control. Arbitrary negative margins can break layouts. Internal block structure can also make some values misleading.

Presets improve rhythm across a site. They also simplify responsive design. Fixed local values create more work during later redesigns.

Test nested blocks carefully. Parent padding and child margin can combine unexpectedly. One control can appear correct until another container supplies spacing.

Typography supports

Typography supports can expose font size, line height, alignment, family, appearance, and decoration. Each subproperty needs explicit support.

WordPress can store preset font sizes separately from custom style values. Theme type scales supply the named choices. Blocks can provide their own sensible defaults.

Typography affects readability and layout. Test zoom, wrapping, long words, and translations. A control working technically can still create unusable content.

Border, shadow, and dimensions

Border supports can expose colour, radius, style, and width. Shadow supports provide approved or custom shadows. Dimension supports can cover minimum height and aspect ratios.

These tools are powerful and easy to misuse. A theme should expose values matching its design system. Blocks should avoid controls their markup cannot honour.

Minimum height can create empty space or clipping across viewports. Aspect ratios can crop meaningful media. Test content extremes before enabling broad choice.

Alignment and layout supports

Alignment supports can expose wide, full, left, right, or centred options. Theme layout configuration determines meaningful width boundaries. Templates supply the surrounding context.

Layout supports let containers manage inner-block flow. Constrained, flex, and grid layouts can expose different controls. WordPress versions continue expanding this system.

A block should declare only layouts it renders correctly. Themes should test supported combinations. Editor previews and frontend output must agree.

Position and structural supports

Position support can expose sticky or related placement features where available. Structural supports can govern multiple instances, reusable use, locking UI, and allowed HTML editing.

Some supports change editor behaviour rather than visual design. The multiple support can restrict one block type per document. Lock support can hide locking controls.

Reusable support affects pattern-related use. HTML support can expose raw editing. Inserter and renaming controls also shape authoring without changing frontend styles.

These options require workflow testing. Removing one menu action can block a legitimate maintenance task. Document the reason for every restriction.

How themes influence block supports

Themes use theme.json to enable settings, define presets, and restrict custom choices. A declared support can remain narrow because the theme limits its values.

For example, a block can support font size. The theme can provide five approved sizes. It can also disable arbitrary custom sizing.

Classic themes can use related settings too. Block-theme architecture is not required for every support. The complete Global Styles interface does require a block theme.

Theme switching can change available presets and controls. Saved block values may remain. Test historical content against the destination theme.

Where support values are stored

Preset choices can use dedicated attributes or recognised class names. Custom design values commonly enter the shared style attribute. The exact representation depends on support.

That style object can contain colour, spacing, typography, border, and other nested values. Several supports share it. One block instance owns its selected values.

WordPress serialises unsupported local values within block content. Removing a visible control does not necessarily erase historical attributes. Old content needs regression testing.

The wrapper contract

Block supports commonly apply generated classes and styles to a wrapper element. Static blocks use editor and save helpers. Dynamic blocks use the server wrapper function.

A missing wrapper contract creates mismatches. Controls appear and values save, but frontend output ignores them. Validation can also fail for static blocks.

Inspect the final wrapper after adding each support. Confirm editor and frontend parity. Do not enable ten supports before testing one output path.

Using selectors for inner elements

Some complex blocks need supported styles applied below the wrapper. The Selectors API can map support-generated rules to suitable inner elements.

A block might direct typography toward a content element. Colour could target another element. This avoids awkward CSS targeting after values save.

Selectors increase implementation responsibility. Changed markup can break them. Stable semantic structure and regression tests remain essential.

Why a block control may be missing

• The block did not declare that support.
• The theme disabled or limited the feature.
• The active WordPress version lacks the subfeature.
• The user role lacks relevant editing access.
• The current layout context makes it unavailable.
• A plugin or editor filter removed the control.
• The block provider implemented support incorrectly.

Start by testing another core block with the same theme. Then test the block under another theme. This separates provider and theme ownership quickly.

Why a saved setting may not render

The wrapper may omit generated properties. A selector may target missing markup. Theme or plugin CSS can override the saved rule.

Caching can preserve older output or stylesheets. Clear the relevant layer once. Then inspect the saved attribute, rendered wrapper, and winning CSS.

Dynamic blocks need server-side support registration too. Otherwise, frontend callbacks can lack recognised attributes. Shared metadata reduces this mismatch.

Block supports and performance

Standard supports can reduce custom control and CSS code. WordPress generates common output consistently. That can simplify assets and maintenance.

More controls can produce more inline values and design variants. They can also increase editor complexity. The API alone does not guarantee lean pages.

Measure complete markup and styles. Check many instances with different settings. A rarely used support can still increase testing burden substantially.

Block supports, theme settings, and styles differ

Block supports describe what a block can accept and render. Theme settings define which tools and values the site permits. Theme styles provide defaults and authored appearance.

These layers cooperate, but they do not replace one another. Confusing them creates unclear ownership and brittle fixes.

A theme preset does not prove every block supports that setting. A block support does not supply a thoughtful site-wide palette. A saved user value can override a theme default.

Debug each layer separately before changing code. First inspect the block registration. Then inspect theme settings and the saved instance. Finally inspect generated markup and CSS.

How to choose supports for custom blocks

Begin with real content tasks. Editors may need spacing around a promotion. They may not need arbitrary borders on every nested component.

Map each requested choice to a stable design token where possible. Tokens make later redesigns easier. They also reduce accidental variations across otherwise related pages.

Consider the block’s semantic purpose before adding visual freedom. A notice block needs dependable hierarchy and contrast. Unlimited colour choices can weaken both.

• Enable only controls matching a documented editorial task.
• Prefer theme presets over unrestricted custom values.
• Provide defaults that work without further configuration.
• Test every support against empty and extreme content.
• Confirm nested layouts preserve expected spacing and widths.
• Keep labels and control locations familiar.
• Record intentional restrictions for future maintainers.
• Remove confusing options before public release.

A support is worthwhile when its flexibility exceeds its maintenance cost. That balance differs between general blocks and tightly branded components.

Versioning and backward compatibility

Support options evolve across WordPress releases. A new subproperty may be unavailable on an older installation. Set the plugin’s minimum version honestly.

Adding support later can change the editor without changing old content. Editors gain new choices when reopening existing blocks. Defaults should avoid surprising visual changes.

Removing support deserves greater caution. Stored attributes can remain after controls disappear. Users might see styling they can no longer adjust.

Deprecation paths matter for static markup changes. Dynamic blocks can adapt output during rendering. Both approaches still require tests with historical attributes.

Keep fixtures representing earlier block versions. Open, edit, save, and render each fixture. This catches silent losses that fresh examples cannot reveal.

A practical release checklist

Review declared supports beside the product requirements. Remove accidental capabilities inherited from scaffolding. Check registered metadata on both server and client.

Build examples covering every exposed control. Include preset and custom values where both exist. Test resets, undo, copy, paste, and duplicated blocks.

Inspect mobile widths and enlarged text. Repeat tests inside constrained templates. Confirm the saved page remains usable when the plugin is unavailable.

Finally, document supported settings for users. Clear limits reduce support requests. They also prevent themes from assuming capabilities the block never promised.

Accessibility and design governance

Every exposed control creates possible outputs. Test colour contrast, text resizing, spacing, focus, and responsive layouts. Restrict combinations that repeatedly fail.

Theme presets can provide safer choices. They cannot prevent every local mistake. Content and accessibility review remain necessary.

Expose supports by editorial need, not API availability. A complete settings panel can overwhelm users. Fewer reliable controls often create better sites.

A compatibility testing workflow

1. List every declared support and subproperty.
2. Test the default theme configuration.
3. Test restricted presets and custom values.
4. Save and reopen each configured block.
5. Compare editor and frontend wrappers.
6. Test nested and template contexts.
7. Test author and administrator roles.
8. Switch to a representative second theme.
9. Test historical blocks after updates.
10. Document expected controls and fallbacks.

Automate stable output checks where possible. Visual controls create large combinations. Prioritise supported presets, edge values, and known risk contexts.

Frequently asked questions

The verdict

Shared support APIs help specialised blocks feel native across themes. WP Block Suite uses the WordPress design system where suitable. Try each free plugin first. Then compare the $299 lifetime suite for several Pro needs.