# WordPress Interactivity API

## About

Since version 6.5,  the [Interactivity API](https://wplake.org/blog/wordpress-interactivity-api/) is a part of WordPress. It's a standard system of directives, based on declarative code, for adding front-end interactivity to blocks. Similar to [React](https://react.dev/) or [Vue](https://vuejs.org/), it offers a declarative approach and provides server-side rendering out-of-the-box.

{% hint style="info" %}
If you're new to the WordPress Interactivity API, we recommend reading a [detailed explanation](https://wplake.org/blog/wordpress-interactivity-api/) on our blog. 
{% endhint %}

*Layout* and *Post Selection* templates fully support it, meaning you can use any [directives](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/api-reference/) in any template, regardless of the render method (shortcode or Gutenberg block).

## Example of usage:

### For Twig: custom.twig

```twig
{{ wp_interactivity_state('my-unique-name', {
  isHidden: false,
}) }}
<div data-wp-interactive="my-unique-name"
     data-wp-context="{{ {'postId': _view.object_id }|json_encode }}">
  <div data-wp-bind--hidden="state.isHidden">
    My post id is <span data-wp-text="context.postId"></span>
  </div>
  <button data-wp-on--click="actions.toggle">Toggle</button>
</div>
```

### For Blade: custom.blade.php

```markup
@php wp_interactivity_state('my-unique-name', {
  isHidden: false,
}) @endphp
<div data-wp-interactive="my-unique-name"
      {!! wp_interactivity_data_wp_context(["postId" => $_view.object_id,]) !!}
  <div data-wp-bind--hidden="state.isHidden">
    My post id is <span data-wp-text="context.postId"></span>
  </div>
  <button data-wp-on--click="actions.toggle">Toggle</button>
</div>
```

### script.js

```javascript
import { getContext, store } from '@wordpress/interactivity';

const { state } = store('my-unique-name', {
  actions: {
    toggle: () => {
      state.isHidden = !state.isHidden;
      console.log('Toggled state for ' + getContext().postId);
    }
  }
});
```

## Notes

### 1. WebComponent type setting

If you're using the WP Interactivity API, the `webComponent` type setting of the target *Layout* or *Post Selection* must be set to 'None'. This means you must choose either WP Interactivity or WebComponent, as you can't use both at the same time. Otherwise, the JS code won't be added as-is but will be wrapped into a web component, causing the top import to fail.

### **2. Interactivity API Basics**

#### 2.1) Block name

To use the WP Interactivity API, you should add `data-wp-interactive='x'` to the top tag of your element. The name can be any, but we recommend using the *Layout* or *Post Selection* name or ID.

#### 2.2) Context

Using `data-wp-context`, you can declare any variables of the template as context, which will be used in directives and available in the JS code. Don't forget to use the Twig `json_encode` filter to turn the object into a string, as shown in the example.

#### 2.3) State

Using the `wp_interactivity_state` function, you can declare any variables of the template as state, which will be used in directives and available in JS code. This function must be called before the `data-wp-interactive` attribute, so you should place it above the top tag of your template. Check the [WP documentation](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/api-reference/#the-store) to understand the difference between state and context.

{% hint style="info" %}
Note: While you can't call any WP function directly in Twig, the `wp_interactivity_state` function is 'mirrored' by Advanced Views, making it available in any Twig template. This function calls the WP function behind the scenes. Read more about our Twig integration [here](/advanced-views/templates/template-engines/twig.md).
{% endhint %}

#### 2.3)  @wordpress/interactivity Package

WP Interactivity employs [modules](https://javascript.info/modules-intro), which are already supported in all modern browsers. The `@wordpress/interactivity` package is an alias for the built-in WP interactivity script, which will be enqueued as a module automatically, so you don't need to worry about manual enqueueing in your theme.

#### 2.4) Server Side Rendering

The directives will initially be processed on the server side. For example, if you change the `isHidden` state to true, the div with the hidden bind will have the `hidden` attribute inside the HTML, so the client won't wait until the JS executes to hide that div.&#x20;

WP also takes care of hydration/rehydration, keeping everything in sync when you change state or context in the JS code during client-side execution as well.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wplake.gitbook.io/advanced-views/templates/css-and-js/wordpress-interactivity-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.