Developer · Guide
How to Use the WordPress HTML API
Short answer
To use the WordPress HTML API, create a WP_HTML_Tag_Processor with your HTML, call next_tag() to find the tag you want, change it with set_attribute(), add_class(), or remove_attribute(), then call get_updated_html() to get the changed HTML back. Put that code in a small plugin or a child theme, hook it to render_block for block output, and check the result on a staging site first.
Key takeaways
- WP_HTML_Tag_Processor arrived in WordPress 6.2 and changes tag attributes in PHP without regular expressions.
- The basic pattern is three steps: create the processor, find a tag with next_tag(), then change it and call get_updated_html().
- next_tag() returns true when it finds a match and false when it reaches the end of the HTML.
- WP_HTML_Processor arrived in WordPress 6.4 for nested HTML, and it stops early on markup it does not support.
- The Tag Processor handles escaping for you, so pass plain values to set_attribute() instead of pre-escaped text.
- Use the render_block filter to change block output, and use render_block_core/image at priority 16 or higher for lightbox markup.
What do you need before you start using the HTML API?
You need WordPress 6.2 or later, a staging site, and a place to put a small amount of PHP code.
The HTML API is a set of PHP classes in WordPress core for reading and changing HTML. Make WordPress Core says WordPress 6.2 introduces WP_HTML_Tag_Processor, the first component in the new HTML API. That date matters because the classes do not exist on older sites.
Check your version under “Dashboard → Updates” before you write code. If the site is older than 6.2, update WordPress first and check the site still works. A staging copy lets you check that update without risk to live pages.
Block authors can find more background on the Gutenberg project, which is the block editor project behind the HTML the API changes.
You also need a code location that survives theme updates. A small custom plugin or a child theme works for this job. Theme vs plugin guidance explains where site features should live, and a code change like this belongs in a plugin when it is not tied to one theme design.
Back up the site before you add code. How to back up WordPress shows the steps, and a backup gives you a fast way back if a filter changes more markup than you planned.
How do you add a class to a tag with WP_HTML_Tag_Processor?
Create the processor, find the tag with next_tag(), add the class, then call get_updated_html().
The WP_HTML_Tag_Processor reference lists three steps: create a new class instance with your input HTML, find the tag you want, then request changes to its attributes. That short pattern covers most first jobs with the API.
Start with this example. It finds the first div and adds the class bold to it.
// $html is the HTML string you want to change.
$p = new WP_HTML_Tag_Processor( $html );
if ( $p->next_tag( 'div' ) ) {
$p->add_class( 'bold' );
}
echo $p->get_updated_html();
The output adds the class bold to that div. The method next_tag() moves the cursor to the next tag that matches your query, and it returns true when it finds one.
You can narrow the search with a tag name, a class name, or both. The reference shows a tag name query for images and a class name query for any tag with that class.
The class helpers are safe to call without a prior check. Adding a class that is already present leaves the tag unchanged, and removing the only class removes the whole class attribute. That behaviour is stated in the WP_HTML_Tag_Processor reference.
How do you set or remove an attribute on a tag?
Use set_attribute() to add or change a value, and remove_attribute() to delete an attribute.
The 6.2 dev note on Make WordPress Core shows this alt-text example, which sets alt on the first image in a block of HTML.
// $html is the HTML string you want to change.
$p = new WP_HTML_Tag_Processor( $html );
if ( $p->next_tag() ) {
$p->set_attribute( 'alt', 'Husky in the snow' );
}
echo $p->get_updated_html();
The output adds the alt value to that image tag. Calling next_tag() with no argument finds the next tag of any kind, which is fine when the HTML has only one tag.
Pass a plain value to set_attribute(). The reference says the method handles all needed HTML encoding, so you give it normal text and it encodes the result for the browser. Do not pre-escape the value with esc_attr() first.
set_attribute() overwrites an existing value when the attribute is already there. remove_attribute() has no effect when the attribute is missing, so you do not need to check first. The WP_HTML_Tag_Processor reference states both rules in its section on modifying attributes.
Read a value before you change it with get_attribute(). That method returns null when the attribute is absent, an empty string when it is present but empty, and true for a boolean attribute with no value. Use that return value to decide whether to skip a tag.
| Method | What it does | When to use it |
|---|---|---|
next_tag() | Moves to the next matching tag | Find one tag or start a loop |
get_attribute() | Reads one attribute value | Check a value before you change it |
set_attribute() | Adds or overwrites an attribute | Set alt text, titles, data attributes, or ARIA values |
remove_attribute() | Deletes an attribute | Remove a test id or an unwanted attribute |
add_class() | Adds one CSS class | Mark a tag for styling |
remove_class() | Removes one CSS class | Drop a class that no longer applies |
get_updated_html() | Returns the changed HTML string | Get the final result after your changes |
How do you change only one type of block with render_block?
Hook your function to render_block_{block-name} so it runs only for that block type.
The render_block hook reference says render_block filters the content of a single block, and it passes three values: the block HTML, the full block array, and the block instance. The instance value was added in WordPress 5.9, as of November 2026.
Use the general hook when you want to change many block types. Use the dynamic hook when you want one type only. The dynamic form is render_block_core/paragraph for paragraphs and render_block_core/image for images, with the block name after the prefix.
This example adds a class to every image block. It returns the original HTML unchanged when the processor finds no image tag.
add_filter( 'render_block_core/image', 'wpl_add_image_class', 10, 2 );
function wpl_add_image_class( $block_content, $block ) {
$p = new WP_HTML_Tag_Processor( $block_content );
if ( $p->next_tag( 'img' ) ) {
$p->add_class( 'wpl-image' );
return $p->get_updated_html();
}
return $block_content;
}
Add the code with “Appearance → Theme File Editor” only if you know that editor is safe on your host, or use a code snippets plugin or a custom plugin file instead. Many hosts disable the file editor, and a plugin file is easier to turn off when you need to undo a change.
Watch the filter priority for images. The dynamic hook reference notes that a built-in image filter runs at priority 15 in WordPress 6.4 for the Expand on Click lightbox. Use priority 16 or higher when your code needs to see that lightbox markup.
How do you loop through every matching tag in a page?
Use a while loop with next_tag() and return get_updated_html() after the loop ends.
The progress report on Make WordPress Core shows a loop that visits every img tag, reads its alt value, and sets a new value only when the current value is empty. That pattern is the usual way to fix many tags in one pass.
$processor = new WP_HTML_Tag_Processor( $html );
while ( $processor->next_tag( 'img' ) ) {
$alt = $processor->get_attribute( 'alt' );
if ( null !== $alt && '' !== $alt ) {
continue;
}
$processor->set_attribute( 'alt', 'Descriptive alt text' );
}
return $processor->get_updated_html();
The loop stops on its own when next_tag() returns false. That return value means no more matching tags were found, or the document ended in the middle of a syntax element. Do not call get_updated_html() inside the loop, because the processor is still moving through the HTML.
The processor only moves forward. The WP_HTML_Tag_Processor reference says that once the cursor reaches the end, you must recreate the processor to start over. Bookmarks are the one exception to that rule.
Set a bookmark with set_bookmark() when you may need to return to a tag later in the same pass. Then call seek() with that bookmark name to move back to it. Keep bookmark names short and fixed, and avoid creating a new bookmark name for every item in a loop.
When should you use WP_HTML_Processor instead of the Tag Processor?
Use WP_HTML_Processor when you need nested HTML structure, and use the Tag Processor for simple attribute changes.
The WP_HTML_Processor reference says the HTML Processor safely parses and modifies an HTML document, and it supports a subset of the HTML5 specification. The Tag Processor scans tags in order, while the HTML Processor tracks how tags relate to each other.
A 2024 progress report on Make WordPress Core gives the timeline: the Tag Processor arrived in WordPress 6.2, the HTML Processor in WordPress 6.4, and token traversal in WordPress 6.5. Use those dates to pick the right class for the WordPress version on your site.
Create the HTML Processor with a static creator method, not with new in the usual way.
$processor = WP_HTML_Processor::create_fragment( $html );
The HTML Processor is a subclass of the Tag Processor, so it keeps the same methods for reading and changing attributes. The 6.4 update on Make WordPress Core notes that in WordPress 6.4 the only new feature is breadcrumbs, which you can inspect with get_breadcrumbs().
Check for failure after you run it. The HTML Processor stops early when it meets markup it does not support, so that it does not break your document. Call get_last_error() to find out why it stopped, and return the original HTML unchanged in that case.
How do you check that your change worked?
View the page source in your browser and search for the tag and attribute you changed.
Open the page on staging, right-click, and choose “View page source” or “Inspect” in your browser. Search for the class or attribute you added, such as wpl-image or the new alt value. If it is there on the right tag, the filter ran.
Check a page that should not change as well. Open a post with no image block, for example, and confirm that its HTML is unchanged. A filter that runs on every block can change pages you did not plan to touch.
Look at the rendered page, not only the source. A missing image, a broken layout, or a lost style can show that a class change had a side effect. Clear any page cache before you check, or you may see the old HTML.
If the change does not appear, check the hook name, the priority, and the block name first. A typo in render_block_core/image means the filter never runs, and the steps in How to use AI to fix WordPress errors can help you trace it.
How long does a first HTML API change take?
Plan 30 to 60 minutes for a first small change, including staging checks.
A single attribute change is short code, often under 20 lines. Most of the time goes to setup: making a backup, adding the code in the right place, clearing cache, and checking two or three pages. That setup is the part to protect, not the code itself.
The API itself adds little load for this kind of work. The WP_HTML_Tag_Processor reference says it runs fast enough for critical hot code paths and needs almost no memory.
What can the HTML API not do yet?
The Tag Processor cannot change inner HTML, build a DOM tree, or find nested tags.
The 6.2 dev note on Make WordPress Core lists those limits in plain terms: it does not build a DOM document tree, find nested tags, or update a tag's inner HTML or inner text. Plan your code around that limit instead of trying to work past it.
The Tag Processor also treats some elements in a special way. The reference lists SCRIPT, STYLE, TITLE, TEXTAREA, IFRAME, and XMP as elements whose contents are not parsed as HTML.
The HTML rules the API follows come from the HTML Standard, which defines how browsers parse tags, attributes, and text.
Do not use regular expressions as a fallback for these jobs. The progress report on Make WordPress Core explains why regex code for HTML grows hard to read and still misses cases, such as single-quoted attributes or a > inside an attribute value. The HTML API exists to replace that pattern.
The HTML Processor covers more structure than the Tag Processor, but it still supports only a subset of HTML5, as of November 2026. When it meets unsupported markup, it stops and reports an error instead of guessing. That safe stop is a feature, not a bug to work around.
What mistakes should you avoid?
Avoid editing HTML with string replace, skipping staging, and running a filter on every block when one block type will do.
String replace and regex can match text inside comments, attribute values, or TEXTAREA content. The Tag Processor knows those contexts and will not mistake them for real tags. The 6.2 dev note shows a messy HTML sample where only the real div gets the new class, while look-alike text inside a TEXTAREA stays untouched.
Do not run a wide render_block filter when a dynamic hook fits. A wide filter runs for every block on every page, so use render_block_core/image for images and render_block_core/paragraph for paragraphs.
Do not forget to return the HTML from your filter function. A filter that changes the processor but returns nothing will blank the block output. Always return $block_content unchanged when no tag matches, and return $p->get_updated_html() only after a change.
Do not pre-escape values or double-encode them. The progress report on Make WordPress Core says updates through the HTML API are handled by default, and you do not need to call esc_attr() or esc_html() on the values you pass in. Plain PHP values go in, and the API encodes the output.
Do not ignore the error check for the HTML Processor. If get_last_error() reports a problem, return the original HTML and log the error for later review. Publishing a partial result from a stopped processor can leave a page with broken markup, so a clean fallback is the safer choice.
Frequently asked questions
Do I need a plugin to use the WordPress HTML API?
No, but a small custom plugin is the safest place for the code. The API classes are part of WordPress core from version 6.2, so you do not need to install a library. Put your filter in a custom plugin or a child theme so a theme update does not delete it.
Can the HTML API change text inside a tag?
The Tag Processor cannot change inner HTML or inner text. It changes attributes on tag openers only. The HTML Processor adds more structure support, but you should check its current limits and use get_last_error() when it stops. For text changes, use a block filter that replaces the full block content instead.
Why does my render_block filter not run on images?
Check the hook name, the block name, and the priority. Use render_block_core/image for image blocks, and use priority 16 or higher if you need the lightbox markup added in WordPress 6.4. Also confirm the code is active, the cache is cleared, and you are viewing a page with an image block.
Is the HTML API faster than DOMDocument?
Yes, for the jobs it is built for. The official reference says the Tag Processor is faster than DOMDocument, uses considerably less memory, and needs almost no memory overhead. It is slower than a simple regular expression, but it avoids the parsing errors that make regex unsafe for HTML.
What should I do if WP_HTML_Processor stops on my HTML?
Return the original HTML unchanged and check get_last_error() to see why it stopped. The processor stops early on markup it does not support to avoid breaking the document. Try the simpler Tag Processor if you only need attribute changes, or narrow the HTML you pass to the processor.
Can I use the HTML API on classic editor content?
Yes, you can use it on any HTML string in PHP, not only block output. Create a Tag Processor with that string, change the tags you need, and use get_updated_html() for the result. The render_block hook is specific to blocks, so use a different filter for classic content.
Sources
- WP_HTML_Tag_Processor – Class WordPress Developer Resources
- Introducing the HTML API in WordPress 6.2 Make WordPress Core
- Progress Report: HTML API Make WordPress Core
- WP_HTML_Processor – Class WordPress Developer Resources
- render_block – Hook WordPress Developer Resources
- Updates to the HTML API in 6.4 Make WordPress Core
- Progress Report: HTML API (2023) Make WordPress Core
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.
Thanks — we review requests within 3 business days.
