Interactivity API: Add a data-wp-html directive

[theaminulai]

What?

Closes #83076

Adds data-wp-html, an inner-HTML equivalent of data-wp-text, and asDangerousHTML() exported from @wordpress/interactivity.

Why?

data-wp-text updates text content, but there's no equivalent for HTML: if a store value contains a description with links or other formatting, data-wp-text displays the markup as text instead of rendering it. Today, updating innerHTML reactively requires reaching outside the Interactivity API's rendering process (e.g. from a data-wp-watch callback), and those changes can be overwritten during client-side navigation. This has come up in #52904, #70531, and #81189.

How?

• packages/interactivity/src/html.ts: asDangerousHTML( html: string ) returns an immutable, opaque value (tagged with a module-private Symbol) that only the data-wp-html directive recognizes as trusted. isDangerousHTML() is the internal type guard the directive uses.
• packages/interactivity/src/directives/html.ts: the data-wp-html directive. It resolves the bound reference the same way data-wp-text does (including PENDING_GETTER handling and unwrapping a plain function value), but only ever writes element.props.dangerouslySetInnerHTML when the resolved value passes isDangerousHTML(). A plain string, null, undefined, or a pending getter is treated as "nothing to render" and leaves the element's existing content in place instead of clearing it — that's what lets a derived-state getter return null while content is loading and keep the server-rendered fallback visible, per the proposal.
• The directive also handles a Preact hydration quirk that isn't obvious from the outside: Preact skips applying dangerouslySetInnerHTML while hydrating, on the assumption that server-rendered content already matches what would be rendered (see diffElementNodes() in preact/src/diff/index.js). That assumption doesn't hold for data-wp-html, since the proposal's scope explicitly has the server leave the attribute unprocessed. Without a workaround, a value that's already available at hydration time would never actually get applied to the DOM. data-wp-style already works around the identical issue for CSS properties via useInit(); data-wp-html uses the same technique to apply the HTML directly through the element's ref on mount.
• To make the "leave existing content in place" behavior hold across renders too (not just on first hydration), the directive keeps a useRef of the last HTML it actually rendered and keeps rendering that value on a later pass where the resolved value isn't trusted HTML, rather than letting Preact's normal diffing clear innerHTML back to empty (which is what happens if a vnode stops carrying dangerouslySetInnerHTML after a previous render set it — confirmed in packages/interactivity/src/directives/test/html.jsdom.test.ts).
• packages/interactivity/src/hooks.tsx: added dangerouslySetInnerHTML?: { __html: string } to the DirectiveArgs.element VNode prop type.
• Docs: added a wp-html section to docs/reference-guides/interactivity-api/directives-and-store.md, right after wp-text.
• Changelog: added an entry to packages/interactivity/CHANGELOG.md (PR number to be filled in once this PR is open — will push a follow-up commit).

Scope, per the proposal: client-side rendering only. No PHP processor, no editor integration, and directives inside the inserted HTML are not processed (including after later updates or client-side navigation) — this matches what the proposal explicitly calls out as being left for a separate feature.

Testing Instructions

1. npm run test:unit:vitest -- packages/interactivity/src — includes the new packages/interactivity/src/directives/test/html.jsdom.test.ts, which exercises real hydration and reactive updates via preact/test-utils' act() against jsdom (not mocked), covering: rendering trusted HTML on hydration, leaving a server-rendered fallback in place while the value isn't trusted HTML yet, rejecting a plain string, keeping previously-rendered HTML in place when a later value becomes untrusted, and ignoring suffix/unique-ID variants (matching data-wp-text's behavior).
2. npm run typecheck -- packages/interactivity/tsconfig.json
3. npm run lint:js on the changed files.
4. Manual/e2e: packages/e2e-tests/plugins/interactive-blocks/directive-html/ is a new fixture block (test/directive-html) and test/e2e/specs/interactivity/directive-html.spec.ts is its Playwright spec, following the exact pattern of the existing directive-text fixture/spec. I wasn't able to run this against wp-env in my environment (no Docker available), so I'd appreciate it if a maintainer or CI could confirm it passes; I did validate the underlying hydration/reconciliation behavior directly against real Preact in the jsdom unit test above, since that's the part with the least obvious failure mode.

import { asDangerousHTML, store } from '@wordpress/interactivity';

store( 'myPlugin', {
	state: {
		get description() {
			return asDangerousHTML(
				'<p>A <strong>formatted</strong> description.</p>'
			);
		},
	},
} );

<div data-wp-interactive="myPlugin">
	<article data-wp-html="state.description">
		<p>Loading description.</p>
	</article>
</div>

[github-actions]

🤖 PR meta 🤖

🎉 Props

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: theaminulai <theaminuldev@git.wordpress.org>
Co-authored-by: DAreRodz <darerodz@git.wordpress.org>
Co-authored-by: nickchomey <nickchomey@git.wordpress.org>

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

Updated as activity occurs, without notifying anyone named here. Add the props-bot label to refresh.

[DAreRodz]

Hey, thanks for working on this, @theaminulai!

This PR is close to what we had in mind, and the API shape is the expected one. On the security side, there are a couple of things we've been investigating and that were not defined in the original issue. I'll share them here as tasks so you can address them whenever you have time (if not, we can take over the PR and continue with the development, no problem). These issues would need to be addressed before merging the PR.

1. Support Trusted Types

A string passed to dangerouslySetInnerHTML would throw on sites enforcing Trusted Types without a default policy.

• Accept string | TrustedHTML and pass native TrustedHTML through without converting it.
• Move writes into a useLayoutEffect with try/catch. If rejected, warn under SCRIPT_DEBUG, preserve existing content, and retry only when the value changes.
• Keep a stable dangerouslySetInnerHTML object so Preact leaves the children alone without doing the write itself.
• Don't create a Trusted Types policy in the runtime. The site should own that decision.

2. Make the token opaque

Instead of a frozen object with a Symbol property (discoverable) and an html string property, I'd use a frozen, null-prototype object as key backed by a private WeakMap for the HTML strings. Acceptance then depends on membership, with no exposed .html or trust carried through clones/JSON.

3. Leave fallback children inert too

Inserted HTML skips Interactivity API processing, but server-rendered children still go through toVdom, and nested islands hydrate independently.

For hosts with a default data-wp-html entry, skip converting their children to vnodes (similar to each-child). Mark descendant interactive islands as handled in hydratedIslands.

Nested router regions can be a follow-up; let's document that they're not excluded yet.

4. Spell out the security contract

The docs should make these points explicit:

• asDangerousHTML() doesn't sanitize. Trusting untrusted input is an XSS risk. Don't pass user-supplied or context values: context selects, state supplies the trusted value.
• Tokens are opaque and identity-based, as above.
• We create no Trusted Types policy. On enforcing sites, strings need a site-provided default policy; the supported route is asDangerousHTML( myPolicy.createHTML( markup ) ).
• The markup is inert only to the Interactivity API. It's still live browser HTML; scripts not executing isn't a security boundary.

Regarding a PHP processor for this directive, we're actually working on that at this moment, and releasing both client-side and server-side parts of this feature is on our current plans for WordPres 7.2.

Thanks again for getting this moving! 😊

[theaminulai]

Thanks for the detailed review @DAreRodz ! Pushed a commit addressing all four points:

1. Trusted Types — asDangerousHTML() now accepts string | TrustedHTML and stores it as-is. The DOM write happens in a useLayoutEffect, wrapped in try/catch; a rejected write warns under SCRIPT_DEBUG, leaves existing content in place, and isn't retried for the same value on a later render. dangerouslySetInnerHTML is now a single stable, frozen object reused every render, so Preact's own diffing never touches the element — only the effect does. No Trusted Types policy is created by this package.

2. Opaque token — DangerousHTML is now a frozen, null-prototype object used purely as a WeakMap key; the HTML value lives in a private module-scoped WeakMap, with no .html (or any other) property exposed on the token itself. A clone (spread, JSON round-trip) is a different object identity and is never recognized as trusted.

3. Inert fallback children — toVdom() now treats a default data-wp-html entry the same way it already treats each-child: it doesn't walk the element's children into vnodes, and any [data-wp-interactive] descendants in that subtree are added to hydratedIslands so hydrateRegions() doesn't hydrate them independently. Documented that nested router regions aren't excluded from processing yet, as a follow-up.

4. Security contract — spelled out explicitly in both the asDangerousHTML() JSDoc and directives-and-store.md: no sanitization; don't pass context values directly (context selects, state supplies the trusted value); the token is opaque/identity-based; no Trusted Types policy is created here (use asDangerousHTML( myPolicy.createHTML( markup ) ) on an enforcing site); and "inert" only means inert to the Interactivity API, not a security boundary.

Added tests for all of the above (Trusted-Types-style rejection + no-retry, token opacity/clone/JSON round-trip, and nested-island opacity), plus the existing test suite still passes unchanged. Good to know a PHP processor is in the works for 7.2 — happy to help with follow-up work there if useful. Let me know if anything needs another pass!

[DAreRodz]

Thanks @theaminulai. I'll review the changes today. 🙂

[DAreRodz]

Thanks for addressing all the feedback, @theaminulai! This looks great. 🙂

I've pushed a few commits before merging. The first two tighten the public API before it ships, since these would be hard to change after a release:

• DangerousHTML is now a nominal type. It was effectively {}, so a string or any object type-checked as DangerousHTML. It's now branded with a private unique symbol, so only values returned by asDangerousHTML() are assignable. The runtime token is unchanged.
• asDangerousHTML() rejects invalid input. It throws a TypeError unless it receives a string or a native TrustedHTML value (checked with trustedTypes.isHTML()). Before, null produced a token that cleared the element, and an object rendered as [object Object].

The third one fixes a hydration issue:

• Matching server-rendered content is kept on hydration. The directive always rewrote innerHTML on hydration, replacing the server-rendered nodes even when they were identical to the trusted HTML, which loses focus, selection, form input and embedded media state. It now skips that first write when the element's HTML already matches exactly.

I also merged trunk and checked the Playwright report: directive-html.spec.ts runs and passes in CI.

We'll handle these in follow-up PRs:

• Exclude router regions nested inside data-wp-html content from processing.
• Catch errors when data-wp-html resolves to a function. The function is currently called outside the try/catch that wraps evaluate().
• Define deterministic conflict rules for data-wp-html combined with data-wp-text, data-wp-each, data-wp-ignore or data-wp-router-region on the same element.
• Warn under SCRIPT_DEBUG when asDangerousHTML() receives a value read from context, and add an ESLint rule to @wordpress/eslint-plugin that flags the same pattern.
• Stop Preact from clearing the element the first time a trusted value arrives after hydration. It currently writes innerHTML = '' before the directive's own write, which replaces matching server-rendered nodes and may throw on sites enforcing Trusted Types.

Approving! 🚀