Introducción a la Interactivity API de WordPress

La Interactivity API¹ de WordPress fue lanzada en la versión 6.5², y proporciona un método para poder agregar interacciones en el Frontend de nuestros bloques, en éste breve tutorial, crearemos un bloque muy simple utilizando estas herramientas de mostrando el proceso paso a paso.

PRE-REQUISITOS

WordPress 6.5 o superior
Soporte para Node.js y npm

¿QUÉ CONTRUIREMOS?

Para este bloque simplemente construiremos una pantalla de notificaciones de chat, simplemente nos mostrará un recuadro con una ventana de texto.

PASO 1: LA BASE DEL BLOQUE

Comenzaremos con la creación básica del bloque, no voy a profundizar mucho en este tema porque realmente no es el punto de este tutorial, pero para hacer las cosas más sencillas utilizaré la herramienta oficial de WordPress @wordpress/create-block:

Simplemente necesitamos ejecutar estos comandos (mah-interactivity-block es el nombre del directorio donde se creará el plugin).

1npx @wordpress/create-block@latest mah-interactivity-block --wp-env --template @wordpress/create-block-interactive-template
2cd mah-interactivity-block
3npx wp-env start
4npm start
5

Nota

Utilizando wp-env

La bandera wp-env nos permite crear un ambiente local en el que funcionará nuestro plugin, si ya tienes un ambiente que usas para pruebas esto no es necesario.

Si no eres muy familiar con ambientes locales te invito a ver mi video Creando un ambiente local para WordPress con WP-ENV en youtube donde explico una manera fácil de lograrlo con las herramientas que ofrece WordPress.

Consejo

La bandera --template nos permite definir una base a utilizar para el nuevo bloque, y utilizamos el template @wordpress/create-block-interactive-template para hacer las cosas más rápido.

Una vez instalado podemos buscar en el archivo block.json los atributos importantes, en este caso:

1// block.json
2{
3	// ...
4	"supports": {
5		"interactivity": true
6	},
7	// ...
8}
9

Esto le dice a WordPress que vamos a utilizar la API en este bloque, ahora estamos listos para comenzar. Así que iniciamos el comando para poder empezar a trabajar en nuestro bloque.

1npm run start
2

PASO 2: TRABAJANDO CON STORES

La base de la API de Interactividad son los stores—básicamente es donde definimos acciones, lo que se traducirán en funciones que serán ejecutadas cuando una interacción sucede.

También podemos definir un state—que son datos que los bloques insertados en una página pueden acceder.

Precaución

Si estás acostumbrado a trabajar con React esto puede ser un poco confuso para ti, pero piensa que es más como un estado global que la forma tradicional de usar state en React.

Así que comenzamos buscando el archivo view.js y eliminamos el contenido de muestra, después lo reemplazamos con esto:

1/**
2* WordPress dependencies
3*/
4import { store } from '@wordpress/interactivity';
5
6const BLOCK_NAME = 'mah/interactivity-api'
7
8const { state } = store( BLOCK_NAME, {
9	actions: {
10		// Acción para alternar el estado de la ventana entre abierto y cerrado.
11		toggleOpen() {
12			state.isOpen = ! state.isOpen;
13		}
14	}
15} );
16

PASO 3: CREAR EL MARKUP DE NUESTRO BLOQUE

Lo que sigue es crear las etiquetas necesarias en nuestro bloque. Como por ahora sólo debemos abrir y cerrar la ventana, esta será una tarea sencilla, simplemente creamos un contenedor con su header y algo de texto de muestra:

1<?php
2// file://render.php
3// Definimos el state.
4wp_interactivity_state( 'mah/interactivity-api', [
5	'isOpen' => false,
6] );
7
8// Cremos un ID único para el botón.
9$unique_id = wp_unique_id( 'mah-' );
10?>
11
12<div
13	<?php echo get_block_wrapper_attributes(); ?>
14>
15	<button
16		class="chat-toggle-button"
17		id="button-<?php echo esc_attr( $unique_id ); ?>"
18	>	
19		<?php esc_html_e( 'Chat', 'mah-interactivity-block' ); ?>
20	</button>
21
22	<div class="chat-window">
23		<div class="chat-content">
24			<p><?php esc_html_e( '¡Bienvenido al chat!', 'mah-interactivity-block' ); ?></p>
25		</div>
26	</div>
27</div>
28

1// file://style.scss
2
3.wp-block-create-block-mah-interactivity-block {
4	display: flex;
5	flex-direction: column;  
6
7	.chat-toggle-button {
8		color: white;
9		background-color: blue;
10		border: 2px solid darkblue;
11		cursor: pointer;
12		font-weight: bold;
13		padding: 1rem;
14		text-align: left;
15	}  
16
17	.chat-window {
18		display: none;
19		
20		&.is-open {
21			display: block;
22			border: 2px solid gray;
23			margin-top: 1rem;
24			padding: 1rem;
25		}
26	}
27}
28

Nota

La función wp_interactivity_state³ es la forma en PHP que se utiliza para crear el state, esto sería el equivalente a esto en JS:

1const { state } = store( BLOCK_NAME, {
2	state: {
3		isOpen: false,
4	},
5	
6  actions: {
7  	// Acción para alternar el estado de la ventana entre abierto y cerrado.
8  	toggleOpen() {
9  		state.isOpen = ! state.isOpen;
10  	}
11  }
12} );
13

Es recomendable iniciarlo en PHP cuando sea posible (cuando utilicemos le archivo render.php) porque así nos aseguramos que se ejecute antes que cualquier código en JS, pero funciona de ambas formas.

Si agregamos nuestro bloque en un post, veremos algo como esto en el frontend:

https://res.cloudinary.com/dyfxhbbnf/image/upload/v1766184002/Zight_2025-12-19_at_4.36.10_p.m._v5patb.png

Por ahora sólo tenemos el bloque, aún no está ligado a nuestro código, así que para ello, debemos agregar algunos atributos data- al nuestro HTML:

1<?php
2// file://render.php
3// Definimos el state.
4wp_interactivity_state( 'mah/interactivity-api', [
5	'isOpen' => false,
6] );
7
8// Cremos un ID único para el botón.
9$unique_id = wp_unique_id( 'mah-' );
10?>
11
12<div
13	<?php echo get_block_wrapper_attributes(); ?>
14>
15	<button
16		class="chat-toggle-button"
17		id="button-<?php echo esc_attr( $unique_id ); ?>"
18		<?php // Denifinimos la acción a ejecutar en click. ?>
19		data-wp-on--click="actions.toggleOpen"
20	>	
21		<?php esc_html_e( 'Chat', 'mah-interactivity-block' ); ?>
22	</button>
23
24	<div
25		class="chat-window"
26		<?php // Especificamos que la clase `is-open` debe agregarse si state.isOpen es verdadera. ?>
27		data-wp-class--is-open="state.isOpen"
28	>
29		<div class="chat-content">
30			<p><?php esc_html_e( '¡Bienvenido al chat!', 'mah-interactivity-block' ); ?></p>
31		</div>
32	</div>
33</div>
34

Y ahora si recargamos nuestro bloque, podremos ver nuestra acción en funcionamiento:

https://res.cloudinary.com/dyfxhbbnf/image/upload/v1766185805/Zight_Recording_2025-12-19_at_05.09.43_p.m._cdvaby.gif

Nota

Las directivas que estamos utilizando son las siguientes:

data-wp-interactive: es la principal, le dice a WP que habilitaremos la API en este elemento y todos sus hijos.
data-wp-class: indica que dependiendo de la orden, se activará o quitará la clase que coloquemos después del doble guión—en este caso .is-open.
data-wp-on: especifica el evento (y la función) a ejecutar, en este caso ejecutamos la función toggleIsOpen dentro de actions cuando el evento click se ejecute.

PASO 4: RECIBIR UN MENSAJE

Ahora que podemos abrir y cerrar nuestro chat, ¿qué tal si imitamos la recepción de un mensaje? Para esto simplemente crearemos un intervalo⁴ que envíe un mensaje después de cierto tiempo, y prepararemos nuestro código para la recepción del mensaje y la notificación.

Lo primero que hacer es agregar un nuevo espacio en nuestro state, a este lo llamaremos messages, entonces modificamos el código así:

1// file://render.php
2
3// Definimos el state.
4wp_interactivity_state( 'mah/interactivity-api', [
5	'isOpen' => false,
6	'messages' => [
7		[
8			'user'      => 'John Doe',
9			'content'   => 'Duis neque turpis, bibendum sit.',
10			'timestamp' => get_the_time( 'T' ),
11		],
12	],
13] );
14
15// Cremos un ID único para el botón.
16$unique_id = wp_unique_id( 'mah-' );
17?>
18
19<div
20	<?php echo get_block_wrapper_attributes(); ?>
21	data-wp-interactive="mah/interactivity-api"
22	<?php // Indicamos que función debe correr en window.load. ?>
23	data-wp-on-window--load="actions.initMessagingTimer"
24>
25	<button
26		class="chat-toggle-button"
27		id="button-<?php echo esc_attr( $unique_id ); ?>"
28		data-wp-on--click="actions.toggleOpen"
29	>
30		<?php esc_html_e( 'Chat', 'mah-interactivity-block' ); ?>
31
32		<?php // Modifica el contenido de texto con `newMessagesCount`. ?>
33		<span class="chat-notification-dot" data-wp-text="state.newMessagesCount"></span>
34	</button>
35
36	<div
37		class="chat-window"
38		data-wp-class--is-open="state.isOpen"
39	>
40		<div class="chat-content">
41			<p><?php esc_html_e( '¡Bienvenido al chat!', 'mah-interactivity-block' ); ?></p>
42		</div>
43	</div>
44</div>
45
46

1// file://view.js
2/**
3 * WordPress dependencies
4 */
5import { store } from '@wordpress/interactivity';
6
7const BLOCK_NAME = 'mah/interactivity-api'
8
9const { state } = store( BLOCK_NAME, {
10	state: {
11		// Nuevo objeto en el state, únicamente lee la cuenta de mensajes.
12		get newMessagesCount() {
13			return state.messages.length;
14		}
15	},
16
17	actions: {
18		// Acción para alternar el estado de la ventana entre abierto y cerrado. 
19		toggleOpen() {
20			state.isOpen = ! state.isOpen;
21		},
22
23		// Acción para crear un timer que agregue un mensaje cada minuto.
24		initMessagingTimer() {
25			// Si ya existe el intervalo no hagamos nada.
26			if ( state.messagingTimer ) {
27				return;
28			}
29
30			state.messagingTimer = setInterval( () => {
31			
32				const user = 'John Doe';
33				const content = 'Duis neque turpis, bibendum sit.';
34				const timestamp = new Date().toISOString();
35
36				state.messages.push( { user, content, timestamp } );
37			}, 60000 );
38		},
39	},
40} );
41
42

Y ahora podemos ver algo como esto en nuestro bloque:

https://res.cloudinary.com/dyfxhbbnf/image/upload/v1766440968/Zight_2025-12-22_at_4.02.28_p.m._oir3j1.png

Y si esperamos por lo menos un minuto, ¡veremos como la cuenta aumenta! Esto es porque indicamos que cada minuto, un nuevo mensaje se agregue a nuestro state. Ahora es tiempo de mostrarlos:

1// file://render.php
2
3<?php
4// Definimos el state.
5wp_interactivity_state( 'mah/interactivity-api', [
6	'isOpen' => false,
7	'messages' => [
8		[
9			'user'      => 'John Doe',
10			'content'   => 'Duis neque turpis, bibendum sit.',
11			'timestamp' => get_the_time( 'T' ),
12		],
13	],
14] );
15
16// Cremos un ID único para el botón.
17$unique_id = wp_unique_id( 'mah-' );
18?>
19
20<div
21	<?php echo get_block_wrapper_attributes(); ?>
22	data-wp-interactive="mah/interactivity-api"
23	data-wp-on-window--load="actions.initMessagingTimer"
24>
25	<button
26		class="chat-toggle-button"
27		id="button-<?php echo esc_attr( $unique_id ); ?>"
28		data-wp-on--click="actions.toggleOpen"
29	>
30		<?php esc_html_e( 'Chat', 'mah-interactivity-block' ); ?>
31
32		<span class="chat-notification-dot" data-wp-text="state.newMessagesCount"></span>
33	</button>
34
35	<div
36		class="chat-window"
37		data-wp-class--is-open="state.isOpen"
38	>
39		<div class="chat-content">
40			<?php // Agregamos un template para mostrar todos los mensajes disponibles. ?>
41			<ul class="chat-messages" data-wp-context="state.messages">
42				<template data-wp-each="state.messages">
43					<li class="chat-message">
44						<strong data-wp-text="context.item.user"></strong>: <span data-wp-text="context.item.content"></span>
45					</li>
46				</template>
47		</div>
48	</div>
49</div>
50
51

Nota

La forma en que mostramos la lista es gracias a la directiva wp-each, esta, acompañada del contexto que damos—wp-context— nos permite pasar datos que serán utilizados sólo en este elemento y sus hijos, automáticamente pasan con la variable item, así que simplemente debemos leer sus propiedades.

1// file://style.scss
2
3.chat-messages {
4	display: flex;
5	flex-direction: column;
6	list-style: none;
7	margin: 0;
8	padding: 0;
9
10	.chat-message {
11		background-color: aqua;
12		border: 1px solid darkcyan;
13		border-radius: 0.5rem;
14		inline-size: fit-content;
15		margin-block-end: 0.5rem;
16		padding: 0.5rem;
17
18		&:nth-child(2n) {
19			align-self: flex-end;
20			background-color: gray;
21			border-color: lightgray;
22			color: white;
23		}
24	}
25}
26

Ahora con esto hemos terminado, si recargamos nuestra página podemos ver una conversación en tiempo real (mas o menos):

CONCLUSIÓN

Como podemos ver, no es muy complicado utilizar la Interactivity API en WordPress, pero si es algo más que aprender. Tenemos la ventaja de que ha sido escrita para trabajar en el frontend, lo que a mi parecer, siempre ha sido un punto débil al trabajar en WordPress. Pero con esto, estamos un paso más cerca de lograr una buena integración entre el editor de bloques y el frontend de nuestro sitio.

LEER MÁS…

Notas al pie

API de interactividad en español ↩
La versión 6.5 fue lanzada el 3 de Abril de 2024 ↩
Documentación de wp_interactivity_state ↩
setInterval en mdn ↩

Mario Aguiar.

#PRE-REQUISITOS

#¿QUÉ CONTRUIREMOS?

#PASO 1: LA BASE DEL BLOQUE

#PASO 2: TRABAJANDO CON STORES

#PASO 3: CREAR EL MARKUP DE NUESTRO BLOQUE

#PASO 4: RECIBIR UN MENSAJE

#CONCLUSIÓN

#LEER MÁS…

#Notas al pie

PRE-REQUISITOS

¿QUÉ CONTRUIREMOS?

PASO 1: LA BASE DEL BLOQUE

PASO 2: TRABAJANDO CON STORES

PASO 3: CREAR EL MARKUP DE NUESTRO BLOQUE

PASO 4: RECIBIR UN MENSAJE

CONCLUSIÓN

LEER MÁS…

Notas al pie