A client came to me last week set on a word-flipping effect they had seen on some high-end SaaS homepage. You probably know the one: a heading that reads “We make [Software, Apps, Magic]” and cycles through the words with an animation. They wanted to know whether getting that one effect meant moving the whole site onto a page builder. It does not. My own first instinct was wrong too, though, because I started sketching out a custom block.
A custom block would have meant the client deleting their existing headings and paragraphs and moving all that content into my new Word Swapper block. Nobody should have to do that to get an animation. The better option is to extend the Interactivity API core blocks already in the editor, keeping what is there and layering the behavior on top.
Extending core blocks without a migration
This takes a couple of the newer WordPress APIs working together. The Format API adds a button to the rich-text toolbar, so the editor highlights a list of comma-separated words and tags them in place. No new block to learn and no extra sidebar, just the editing experience they already have. The approach here comes from the Interactivity API guide on the Developer Blog.
My first attempt processed the HTML with a regex replace inside a PHP filter, which fell apart quickly on nested spans and anything with a few attributes on it. Use WP_HTML_Tag_Processor instead. It injects attributes into core block markup without wrecking the surrounding layout, which regex will not reliably do.
add_filter( 'render_block_core/paragraph', 'bbioon_word_switcher_render', 10, 2 );
function bbioon_word_switcher_render( $block_content, $block ) {
if ( strpos( $block_content, 'class="word-switcher"' ) === false ) {
return $block_content;
}
$processor = new WP_HTML_Tag_Processor( $block_content );
// Find our tagged span and inject Interactivity directives
while ( $processor->next_tag( [ 'tag_name' => 'span', 'class_name' => 'word-switcher' ] ) ) {
$processor->set_attribute( 'data-wp-text', 'state.currentWord' );
$processor->set_attribute( 'data-wp-class--fade', 'context.isFading' );
}
return $processor->get_updated_html();
}What the Interactivity API handles for you
Once the HTML API has done its work on the server, the Interactivity API picks things up in the browser. Rather than a pile of jQuery hunting for elements and toggling classes by hand, you define a store. The store holds the timing and the state, and the UI follows whenever the state changes. It is declarative, and it stays out of the way of other plugins.
Script Modules, another native feature, mean that JavaScript only loads on pages that need it. That matters more than it sounds: pulling in a whole animation library site-wide for one heading effect is how sites get slow one small decision at a time.
What to take from this
- Extend core blocks rather than building custom ones where you have the choice, because your client pays for the migration either way.
- Manipulate block HTML with the HTML API. Regex is not up to the job.
- The Interactivity API keeps complicated frontend state manageable, which is where hand-rolled scripts usually start to hurt.
Most of this gets fiddly once a site grows. If you have inherited someone else’s setup and you would rather it just worked on current standards, my team does this work. Send us a message.
