Use this skill when plugin code needs to read or modify HTML. The goal is to avoid regex-based HTML parsing and unsafe manual escaping. WordPress' HTML API understands malformed real-world HTML better than ad hoc string code and keeps escaping rules in one place.
\nThis skill is not about React, Gutenberg editor internals, or client-side DOM work.
\nThe HTML API is a parser and mutation API, not an HTML sanitizer. It\npreserves existing scripts, event-handler attributes, and unsafe URL schemes,\nand setter escaping only prevents broken markup. Sanitize untrusted HTML with\nwp_kses()/wp_kses_post() at the trust boundary, then mutate the accepted\nHTML. Validate values such as href by semantic type before setting them.
Trigger when ANY of the following is true:
\nstr_replace() to modify HTML tags, attributes, classes, or text nodes.DOMDocument for frontend HTML fragments and then fights encoding, wrapper tags, or HTML5 parsing differences.WP_HTML_Tag_Processor, WP_HTML_Processor, set_attribute, add_class, serialize_token, or data-* attributes.the_content, shortcode output, widget output, email HTML, REST-rendered HTML, or third-party markup.| Task | \nPrefer | \n
|---|---|
| Add/remove/read attributes on matching tags | \nWP_HTML_Tag_Processor | \n
| Add/remove classes on matching tags | \nWP_HTML_Tag_Processor | \n
| Replace text in modifiable text nodes | \nWP_HTML_Tag_Processor::set_modifiable_text() | \n
| Traverse nested structure or serialize matched tokens | \nWP_HTML_Processor | \n
| Normalize malformed HTML into well-formed HTML | \nWP_HTML_Processor::normalize() | \n
Map between data-* HTML names and JS dataset names | \nwp_js_dataset_name() / wp_html_custom_data_attribute_name() | \n
For most plugin output filters, start with WP_HTML_Tag_Processor. Reach for WP_HTML_Processor only when you need document/fragment structure, nesting, or token serialization.
function myplugin_add_tracking_attr( string $html ): string {\n $processor = new WP_HTML_Tag_Processor( $html );\n\n while ( $processor->next_tag( array( 'tag_name' => 'a' ) ) ) {\n $href = $processor->get_attribute( 'href' );\n if ( ! is_string( $href ) || ! str_starts_with( $href, 'https://example.com/' ) ) {\n continue;\n }\n\n $processor->add_class( 'myplugin-tracked-link' );\n $processor->set_attribute( 'data-myplugin-source', 'content' );\n }\n\n return $processor->get_updated_html();\n}\nImportant WP 6.9 behavior: set_attribute() and set_modifiable_text() escape all character references. Pass normal unescaped text. Do not pre-escape with esc_attr(), esc_html(), or htmlspecialchars() before calling these methods, or you will produce double-escaped output.
// WRONG - pre-escaped value can become double-escaped.\n$processor->set_attribute( 'title', esc_attr( 'Eggs & Milk' ) );\n\n// RIGHT - pass the raw intended value; HTML API encodes it.\n$processor->set_attribute( 'title', 'Eggs & Milk' );\nset_modifiable_text() only works when the current token is modifiable text. It is not a general \"replace all visible text\" function.
$processor = new WP_HTML_Tag_Processor( $html );\n\nwhile ( $processor->next_token() ) {\n if ( '#text' !== $processor->get_token_type() ) {\n continue;\n }\n\n $text = $processor->get_modifiable_text();\n if ( null === $text ) {\n continue;\n }\n\n // \"\\u{1F642}\" is the slightly-smiling-face code point, written as a PHP\n // escape so the source stays plain-ASCII (7.0+ double-quoted syntax).\n $processor->set_modifiable_text( str_replace( ':)', \"\\u{1F642}\", $text ) );\n}\n\n$html = $processor->get_updated_html();\nIf the target text may be inside script, style, or complex nested content, inspect the processor behavior on the target WP version before shipping.
next_token() now recognizes HTML processing instructions such as\n<?my-target data?>. Check get_token_type() === '#processing-instruction';\nget_tag() returns the case-sensitive target, while get_token_name() returns\nthe static token name.
This follows HTML tokenization, not generic XML parsing. A recognized target\nstarts with an ASCII letter or _ and continues with ASCII alphanumerics, -,\nor _. Reserved xml / xml-stylesheet and XML-only target characters become\ncomment-like tokens instead. The token ends at the first >, so do not use the\nAPI as an XML processor.
get_modifiable_text() returns PI data without entity decoding.\nset_modifiable_text() supports it in 7.1 and normalizes the result to a space,\nthe supplied data, and ?>. It rejects data containing > or beginning with\nwhitespace because those values cannot be represented unambiguously. It does\nnot escape PI data. Attribute/class setters return false because a processing\ninstruction is not an HTML tag. Always check mutation return values.
Use WP_HTML_Processor when you need safe token serialization or fragment-level structure:
$processor = WP_HTML_Processor::create_fragment( $html );\n$links = array();\n\nwhile ( $processor->next_tag( array( 'tag_name' => 'a' ) ) ) {\n $links[] = $processor->serialize_token();\n}\nIn WP 6.9, WP_HTML_Processor::serialize_token() is public. It serializes the current token in normalized form; it is not a full outerHTML extractor for arbitrary subtrees unless you explicitly walk and collect the nested tokens you need.
data-* attribute namesHTML data-* names and JS dataset properties do not map by simple dash removal in every case. For generated attributes that must line up with JS, use the core mapping helpers:
$attribute = wp_html_custom_data_attribute_name( 'myPluginSource' );\nif ( null !== $attribute ) {\n $processor->set_attribute( $attribute, 'content' );\n}\n\n$dataset_name = wp_js_dataset_name( 'data-my-plugin-source' );\nWP_HTML_Tag_Processor first for simple mutations; it is cheaper and simpler than structural processing.WP_HTML_Processor for structure, nested traversal, normalization, and serialize_token().get_updated_html() after lexical updates; returning the original $html drops changes.// WRONG - regex breaks on attribute order, quotes, nesting, and malformed HTML.\n$html = preg_replace( '/<a /', '<a rel=\"nofollow\" ', $html );\n\n// RIGHT\n$p = new WP_HTML_Tag_Processor( $html );\nwhile ( $p->next_tag( array( 'tag_name' => 'a' ) ) ) {\n $p->set_attribute( 'rel', 'nofollow' );\n}\n$html = $p->get_updated_html();\n\n// WRONG - escapes before the API escapes.\n$p->set_attribute( 'title', esc_attr( $title ) );\n\n// RIGHT\n$p->set_attribute( 'title', $title );\nwp-security-audit when HTML contains user input or saved admin settings.wp-i18n-audit when replacing visible text with translated strings.wp-rest-api when HTML is returned from an endpoint and should instead be structured JSON.WP_HTML_Tag_Processor: wp-includes/html-api/class-wp-html-tag-processor.phpWP_HTML_Processor: wp-includes/html-api/class-wp-html-processor.phpwp-includes/script-loader.php