Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared Managed Cloud India
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Best lists Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Explainers · Explainer

What Is the HTML API in WordPress? A Plain Explanation

Short answer

The HTML API is a PHP system built into WordPress core that finds HTML tags and safely changes their attributes. It started with WP_HTML_Tag_Processor in WordPress 6.2.0, and WP_HTML_Processor in WordPress 6.4.0 added an understanding of HTML structure. It replaces fragile regex and DOMDocument edits with parsing that follows HTML rules.

Key takeaways

  • The HTML API is a PHP system in WordPress core that reads and changes HTML on the server.
  • WP_HTML_Tag_Processor arrived in WordPress 6.2.0 and finds tags and changes their attributes.
  • WP_HTML_Processor arrived in WordPress 6.4.0 and understands nesting and HTML structure.
  • The Tag Processor scans forward only and cannot build a DOM tree or match closing tags.
  • WordPress 6.7.0 brought the HTML Processor close to full HTML support, as of November 2026.
  • The API handles HTML encoding for values you set, so you pass plain text, not escaped text.

What is the HTML API in WordPress?

The HTML API is a PHP system built into WordPress core that reads and changes HTML safely, without regex or a full DOM parser.

It gives PHP code a controlled way to find HTML tags and change their attributes. Make WordPress Core describes it as a PHP subsystem designed to reliably and efficiently interact with HTML and HTML-related needs. You can read that definition in the HTML API progress report.

The API lives in WordPress core, not in a plugin or theme. It runs on the server, in PHP, before a page reaches a browser.

How does the HTML API work?

It scans HTML from start to finish, one token at a time, and changes only the tags you ask it to change.

A token is one piece of HTML, such as a tag, a text node, or a comment. The processor moves its cursor forward through those tokens. When it finds a tag that matches your query, it stops there so you can read or change that tag.

The WP_HTML_Tag_Processor reference lists three steps: create an instance with your HTML, find the tag you want, then request changes to its attributes.

$tags = new WP_HTML_Tag_Processor( $html );
if ( $tags->next_tag( 'img' ) ) {
    $tags->set_attribute( 'alt', 'A garden gate' );
}
$html = $tags->get_updated_html();

That example finds the first img tag, sets its alt attribute, and returns the updated HTML.

The processor cannot move backward. Developer.WordPress.org states that once the cursor reaches the end, you must recreate the processor to start over. Bookmarks are the one exception: you can set a named bookmark and return to it with seek().

What are the two main classes in the HTML API?

The two main classes are WP_HTML_Tag_Processor for tags and attributes, and WP_HTML_Processor for HTML structure.

The Tag Processor is the lower-level class. It scans a document from tag to tag and reads or changes attributes on existing tags. It does not understand where one element begins and ends.

The HTML Processor builds on the Tag Processor. It tracks nesting, so it knows which tags sit inside other tags. It can also visit text nodes, comments, and virtual nodes that the HTML rules imply, even when they do not appear as text.

Use this table to tell them apart at a glance.

ClassIntroducedMain jobStructure aware?
WP_HTML_Tag_ProcessorWordPress 6.2.0Find tags, read and change attributesNo
WP_HTML_ProcessorWordPress 6.4.0Parse and change HTML with nesting in mindYes
WP_HTML_DecoderWordPress 6.6.0Decode text and attribute values as a browser wouldNot applicable

The WP_HTML_Processor reference says the class properly parses and modifies HTML5 documents, and aborts early on unsupported markup rather than breaking the document.

When did the HTML API arrive in WordPress?

It arrived in stages, starting with the Tag Processor in WordPress 6.2.0 and growing in each release after that.

WordPress 6.2.0, released in March 2023, introduced WP_HTML_Tag_Processor. Make WordPress Core called it the first component in a new HTML processing API, built for block authors who needed to adjust tag attributes in block markup.

WordPress 6.4.0 added the first HTML Processor. The 6.4 update note describes it as a higher-level partner that understands HTML structure, including nesting and misnesting.

WordPress 6.5.0 added token scanning to the Tag Processor. The 6.5 update note says next_token() can now scan every token in a document, not just tags.

WordPress 6.6.0 added a spec-compliant text decoder, get_current_depth(), and expects_closer(), per the 6.6 update note. WordPress 6.7.0 brought the HTML Processor close to full HTML support, per the 6.7 update note.

That staged history matters for site owners. A site on WordPress 6.2 has only the Tag Processor, while a site on WordPress 6.7 has the fuller set. Check your version before you assume a method exists, as of November 2026.

Why did WordPress need an HTML API?

WordPress needed it because the old tools for changing HTML in PHP, regex and DOMDocument, kept corrupting markup.

Before the API, developers often used regular expressions to edit HTML strings. Make WordPress Core shows how that approach breaks on single-quoted attributes, unquoted values, a > inside an attribute, and uppercase attribute names. Each fix made the pattern longer and harder to read.

DOMDocument was the other common choice, and it had its own faults. Make WordPress Core notes that it finds an img tag inside a TEXTAREA, where no tag can exist, and treats a typed heart symbol as a tag.

A bad edit can break a page layout or open a path for unsafe input. The HTML API was built to follow the HTML rules in the HTML Standard so developers do not have to memorise them. The work grew out of the block editor, which you can read about on the Gutenberg page.

What can the HTML API change, and what can it not change?

It can read and change attributes and some text, but the Tag Processor alone cannot add tags, remove tags, or change inner HTML.

With the Tag Processor you can:

  • Find a tag by name, class, or both, with next_tag().
  • Read an attribute with get_attribute().
  • Set or replace an attribute with set_attribute().
  • Remove an attribute with remove_attribute().
  • Add or remove a CSS class with add_class() or remove_class().
  • Get the finished HTML with get_updated_html().

Developer.WordPress.org states that get_attribute() returns null when an attribute is absent, an empty string when it is present but empty, and true for a boolean attribute with no value.

The same reference says set_attribute() handles HTML encoding for you. You pass a plain value, such as Eggs & Milk, and the API encodes it so the browser reads it as intended. You do not need to escape it first.

The HTML Processor adds more. It can visit every token with next_token(), read text with get_modifiable_text(), and, from WordPress 6.7.0, change some text with set_modifiable_text().

Even so, limits remain. The Tag Processor cannot match an opening tag with its closing tag, and it cannot return the inner markup of an element. If you need a full tree, with parent and child queries, this API is not a browser DOM.

How does the HTML API handle messy or broken HTML?

It follows HTML parsing rules, so it treats messy markup the way a browser would, instead of guessing with string edits.

Real WordPress content is messy, with unclosed tags and pasted markup from other editors. The HTML API was designed for that input, not just for clean pages.

Some elements get special treatment because their contents are not HTML. Developer.WordPress.org lists SCRIPT, STYLE, TITLE, TEXTAREA, IFRAME, NOEMBED, NOFRAMES, and XMP. Text that looks like a tag inside one of those elements is treated as text, not as a tag.

That rule stops a common mistake. A script block can hold the text of its own closing tag inside a comment, and a TEXTAREA can hold text that looks like an img tag. The API does not act on those fake tags.

When the HTML Processor meets markup it cannot support, it stops early.

Make WordPress Core says it bails by returning false and storing an error you can read with get_last_error(). WordPress 6.7.0 narrowed that gap a lot. The 6.7 update note says only rare fostering cases stay unsupported, and those arise in roughly 0.5% of all websites on the web, as of November 2026.

How can you check whether your site uses the HTML API?

You can check your WordPress version and look for the API classes in your theme or plugin code, because the API has no settings screen.

There is no HTML API page in the WordPress admin. It is a developer tool, so it shows up in code and in version numbers, not in “Settings”.

Start with the version. Go to “Dashboard → Updates” in your admin and note the WordPress version. WordPress 6.2.0 or newer has the Tag Processor, WordPress 6.4.0 or newer has the HTML Processor, and WordPress 6.7.0 or newer has the fuller set.

Next, ask your developer or check your code for the class names. Search your theme and plugin files for WP_HTML_Tag_Processor or WP_HTML_Processor.

A match means that code uses the API. No match means your site may still benefit from it indirectly, because core and blocks use it themselves.

Make WordPress Core notes that WordPress requires PHP 7.4 or higher, so the API runs on that PHP base. If you find the API in a plugin you did not expect, do not remove it by hand. Back up the site before any code change, as our guide to backing up WordPress explains.

Is the HTML API the same as the Interactivity API?

No, they are separate APIs, but the Interactivity API uses the HTML API on the server to process block markup.

The Interactivity API adds interactive behaviour to blocks, such as state and client-side updates. It runs in the browser with JavaScript, and it also has server-side parts in PHP.

The HTML API is the lower layer that reads and changes HTML. When the Interactivity API needs to process directives in server-rendered markup, it uses the HTML Processor classes to walk through the tags. That is a good example of the API doing quiet work inside core.

Think of it this way: the HTML API knows how to read HTML, and the Interactivity API knows what to do with that reading. One does not replace the other. A comparison of Gutenberg and page builders looks at the editor side, while the HTML API sits underneath the editor output.

What myths about the HTML API should you ignore?

The most common myth is that the HTML API is a browser DOM in PHP, and the second is that it can fix any broken HTML.

It is not a DOM. A DOM builds a full tree of nodes, with parents, children, and queries across the whole document.

The Tag Processor scans forward in a straight line and never builds that tree. The HTML Processor adds structure, but it is still a streaming parser, not a full DOM library.

It also does not magically fix every page. It can handle common messy markup, but it stops when it meets input it cannot support. That stop is a feature, not a bug: it protects your content from a bad rewrite.

A third myth is that the API is only for block developers. Blocks were the first use, but any PHP code that edits HTML can use it, including themes and plugins. The place where the code lives matters more than the label on it, as our guide on themes versus plugins explains.

A fourth myth is that regex is just as safe if you write it well. The Make WordPress Core report shows a short regex that looks correct yet fails on five different inputs.

The API exists because that failure pattern kept repeating across core. If an error appears after a code change, our guide on using AI to fix WordPress errors can help you narrow down the cause.

What mistakes should you avoid?

Avoid using the wrong class for the job, assuming a method exists on an old WordPress version, and editing HTML with regex when the API fits.

Check the list below before you, or a developer working for you, reach for the API.

  • Do not use the Tag Processor when you need nesting, depth, or inner content; use WP_HTML_Processor instead.
  • Do not call create_full_parser() or set_modifiable_text() on a site below WordPress 6.7.0, since those arrived in that release.
  • Do not expect next_tag() to find a closing tag for a special element such as SCRIPT or STYLE; the processor already matched it with the opening tag.
  • Do not create a bookmark for every tag in a loop; Developer.WordPress.org warns that bookmarks add overhead, so use known literal names only.
  • Do not ignore a false return from next_tag() or next_token(); it can mean the tag was not found, or the document ended mid-token.
  • Do not skip a backup before changing theme or plugin code that edits HTML on your live site.

Frequently asked questions

Do I need to install anything to use the HTML API?

No. The HTML API is built into WordPress core, so it is already present on a site running WordPress 6.2.0 or newer. The Tag Processor arrived in 6.2.0, and later releases added the HTML Processor and token scanning. You only need code that calls it, which usually comes from a theme, a plugin, or core itself.

Can the HTML API change text inside a paragraph?

The Tag Processor alone cannot change inner text. From WordPress 6.5.0 you can read text with get_modifiable_text(), and from WordPress 6.7.0 you can change some text with set_modifiable_text(). That method works for text nodes and for special elements such as SCRIPT, STYLE, TITLE, and TEXTAREA. It does not turn the API into a full editor for inner HTML.

Is the HTML API faster than using DOMDocument in PHP?

Yes, for the jobs it is built for. Developer.WordPress.org says it is faster than full HTML parsers such as DOMDocument and uses considerably less memory, with negligible overhead. It avoids building a tree, which keeps it lean. That speed comes with a trade-off: it cannot do full tree queries the way a DOM parser can.

What WordPress version do I need for the full HTML Processor?

WordPress 6.4.0 introduced the first HTML Processor, but it only supported a subset of HTML at first. WordPress 6.7.0 brought it close to full support, adding create_full_parser(), set_modifiable_text(), normalize(), and serialize(). If you want the fuller set, run WordPress 6.7.0 or newer, as of November 2026.

Does the HTML API work on any HTML, even broken HTML?

It handles much messy HTML by following HTML parsing rules, including unclosed and overlapping tags. It also treats the contents of SCRIPT, STYLE, and TEXTAREA as text, not tags. When it meets markup it cannot support, it stops early instead of guessing. That stop protects your content, and you can read the error with get_last_error().

Can a non-developer use the HTML API?

Not directly. The HTML API is PHP code, so using it means writing or editing PHP in a theme or plugin. As a site owner, you benefit from it indirectly when core, blocks, or plugins use it to edit markup safely. Your useful checks are your WordPress version, your PHP version, and whether your theme or plugin code mentions the API classes.

Sources

  1. WP_HTML_Tag_Processor – Class WordPress Developer Resources
  2. WP_HTML_Processor – Class WordPress Developer Resources
  3. Progress Report: HTML API Make WordPress Core
  4. Updates to the HTML API in 6.5 Make WordPress Core
  5. Updates to the HTML API in 6.6 Make WordPress Core
  6. Updates to the HTML API in 6.7 Make WordPress Core
  7. HTML Standard WHATWG

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

WPLegible editors

Researched from the primary sources listed above and checked against our editorial rules. About the site · How we test