Block variations: Support innerContent for the Custom HTML block

[youknowriad]

What?

Follow-up to #79115. Lets a block variation provide innerContent so a variation of the Custom HTML block can preset static markup with editable inner-block slots.

wp.blocks.registerBlockVariation( 'core/html', {
	name: 'card',
	title: 'Card',
	innerContent: [ '<div class="card"><h2>Heading</h2>', null, '</div>' ],
	innerBlocks: [ [ 'core/paragraph', { content: 'Editable body' } ] ],
} );

Inserting this variation produces a Custom HTML block with the static <div>/<h2> and an editable paragraph mounted in the null slot.

Why?

After #79115 the Custom HTML block stores its markup as innerContent (static fragments interleaved with inner blocks). Block variations could carry attributes and innerBlocks, but not innerContent, so there was no way to ship a preset HTML-block layout with editable slots as a variation. The only workaround was a block pattern.

How?

• Add an innerContent field to the BlockVariation type.
• Carry it into the inserter item in getItemFromVariation.
• Pass it to createBlock as the 4th argument when inserting from use-block-types-state (the single place that builds a block from an inserter item's innerBlocks).

createBlock already stores innerContent only for core/html (the hardcoded mechanism from #79115), so non-HTML variations passing it are ignored with a warning. Variation previews already work via getBlockFromExample's example.innerContent (added in #79115).

Testing Instructions

1. Register the variation above (e.g. from the browser console with wp.blocks.registerBlockVariation).
2. Open the inserter, find the "Card" variation under Custom HTML, insert it.
3. Confirm the static heading renders and the paragraph is editable in place, but can't be moved/removed.
4. Save and reload — the structure round-trips.

Testing Instructions for Keyboard

Insert the variation via the inserter using the keyboard, then Tab into the editable paragraph and type — editing should work without a pointer.

🤖 Generated with Claude Code

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

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: youknowriad <youknowriad@git.wordpress.org>
Co-authored-by: priethor <priethor@git.wordpress.org>
Co-authored-by: talldan <talldanwp@git.wordpress.org>

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

[github-actions]

Size Change: +154 B (0%)

Total Size: 7.62 MB

📦 View Changed

Filename	Size	Change
build/scripts/block-editor/index.min.js	385 kB	+91 B (+0.02%)
build/scripts/blocks/index.min.js	45.2 kB	+63 B (+0.14%)

_{compressed-size-action}

[github-actions]

Flaky tests detected in 677dee5.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/28405410295
📝 Reported issues:

• [Flaky Test] Should save the changes #78689 in /test/e2e/specs/editor/plugins/wp-editor-meta-box.spec.js

[talldan]

This seems ok, but some lingering concerns:

• The innerContent / innerBlocks props seem a bit clunky to specify versus only specifying the html.
• I think specifying block as [ 'core/paragraph', { content: 'Editable body' } ] is something we already have in trunk. I never understood it personally, as doesn't this bypass migrations/deprecations? Possibly the block has to support that attribute set forever, and if it ever changes in implementation it'll break.
• Once inserted, the instance becomes an html block, so it doesn't feel like inserting a distinct type like most variations do. There's nothing for the variation matcher to match on. I guess this can be resolved in a follow-up, but I think it'd be better to have a spike style exploration to see where this is going. I personally think the html block and variations might end up being too limiting. For example, it might be difficult to support 'alignfull', and I wonder if these kinds of blocks should be like full-width sections. Especially if they're AI generated.

[youknowriad]

The innerContent / innerBlocks props seem a bit clunky to specify versus only specifying the html.
I think specifying block as [ 'core/paragraph', { content: 'Editable body' } ] is something we already have in trunk. I never understood it personally, as doesn't this bypass migrations/deprecations? Possibly the block has to support that attribute set forever, and if it ever changes in implementation it'll break.

This format exists, it's the actual block JSON object, so I don't want to change it because of a new property being added. The questions you raise are valid and we do have too many ways to define block instances.

Once inserted, the instance becomes an html block, so it doesn't feel like inserting a distinct type like most variations do. There's nothing for the variation matcher to match on. I guess this can be resolved in a follow-up, but I think it'd be better to have a spike style exploration to see where this is going

I think this is a good point and yeah ideally it should match the initial variation. I'll explore it.

[youknowriad]

@talldan On the last point, these are the two options that we have

Match on a marker attribute (e.g. set metadata.name on the variation, isActive: ['metadata.name']). Works mechanically, but it's a hack: it co-opts the block's user-facing "rename" feature as variation identity and pollutes saved content with a marker. Reviewers would rightly push back.
Extend isActive to receive innerContent/inner blocks.

My thinking right now, is the latter but only checking that "innerContent" array are deeply equal which means

• if someone changes the inner blocks, the variation still matches
• If someone changes the innerContent, the variation doesn't match anymore.

It's not perfect though.

[talldan]

This format exists, it's the actual block JSON object, so I don't want to change it because of a new property being added.

Yeah, I do understand that, I think in most uses it's internal and in-memory only. There are definitely a few other APIs via which blocks are specified as data (template being the main one). I get why, it's a nice enough format, but I think there's no back/forwards compatibility for those types of declarations. I'm not sure it's a good option to keep using if there are alternatives.

[youknowriad]

I don't think the current PR changes the statusquo though, the variations API is the same, we're just fixing a gap and I don't really want to invent a new variations API right now tbh.

[priethor]

Once inserted, the instance becomes an html block, so it doesn't feel like inserting a distinct type like most variations do

+1 on the "becomes a plain HTML block" concern. For the cases where you do want a distinct type (its own name for styles/theme.json), I think that's where #79598 fills the gap. This looks solid, and I think the two are complementary.

[priethor]

The HTML block's behavior with innerContent is already tested, but maybe a small test to ensure that the variation's innerContent actually reaches the block on insert?

[youknowriad]

Good call — the existing test replicated the insert path rather than exercising a handler. I've added a direct test of the block autocompleter's getOptionCompletion (afb2938), which asserts a variation's innerContent reaches the created block through the real slash-command handler — the path that was actually dropping it. The other insert paths (the onSelectItem hook, drag/preview components) are e2e-level to exercise realistically and not worth it.

(This is my agent's replied, modified by myself, replying to you or your agent)

[youknowriad]

I fixed the "isActive" variation check to consider innerContent.

[youknowriad]

Anything missing here?

[priethor]

Looks good, especially with the latest changes. I don’t see any blockers.