Advanced Views Docs
Live PlaygroundDownload PluginGet PRO
  • 💡Help Centre
  • ⚡Getting Started
    • Introduction
      • Key Aspects
      • Creating Your First View
      • Creating Your First Card
      • Plugin Terms
      • Plugin Interface
        • Field Options
    • Installation
      • Advanced Views Lite
      • Advanced Views Pro
      • Comparison Table
      • Upgrading from Lite to Pro
    • Supported data vendors
    • Starter theme
  • 🌟Display Content
    • WordPress
      • Post
      • Taxonomy terms
      • User
      • Comments
      • Menus
    • WooCommerce Product
    • Meta fields
      • Basic fields
        • Number
      • Content fields
        • Image
        • File
        • WYSIWYG
        • oEmbed
        • Gallery
      • Choice fields
        • Select/checkbox/radio
        • True / False
      • Relationship fields
        • Link
        • Post_object
        • Page Link
        • Relationship
        • Taxonomy
        • User
      • Advanced fields
        • Google Map
        • Google Map Multiple Markers
        • ACF OpenStreetMap Field
        • Date/time picker
      • Layout fields
        • Group (Pro)
        • Repeater (Pro)
        • Flexible (Pro)
    • Object fields
    • Custom Data (Pro)
    • Custom Gutenberg Blocks (Pro)
    • Mount Points (Pro)
    • Front-end assets management (Pro)
  • 🦸‍♂️Query Content
    • Basic Filters
    • Meta Filters (Pro)
      • Current Post
      • Comparison
      • Dynamic Injection
    • Taxonomy Filters (Pro)
    • Pagination (Pro)
    • Custom Data (Pro)
  • 🏆Shortcode Attributes
    • Common Arguments
    • View Shortcode
    • Card Shortcode
  • 🧙‍♂️Templates
    • Customizing the Template
    • Template engines
      • Twig
      • Blade
    • CSS & JS
      • BEM Methodology
      • WordPress Interactivity API
    • File system storage
    • Pre-built components
    • Reusable components library (Pro)
    • Live reload
    • Multilingual
    • Custom Ajax & Rest API (Pro)
  • ☕Guides
    • Display Custom Post Type (CPT) on another post
    • Display Employees (CPT) of a Company (CPT)
    • Display Nested Repeater Fields
    • Map Marker from ACF Image
    • Display all CPT items on a single map
  • 🛠️Tools
    • Export/Import
    • Demo Import
    • Settings
    • Preview
  • 🏹Troubleshooting
    • Compatibility
    • Report a bug
    • Payment Issues
    • Lite Support (Forum)
    • Pro Support
  • ⚙️Customization
    • Filters and Hooks
      • View
      • Card
    • Suggest a feature
    • Performance
Powered by GitBook
On this page
  • About
  • Example of usage:
  • For Twig: custom.twig
  • For Blade: custom.blade.php
  • script.js
  • Notes
  • 1. WebComponent type setting
  • 2. Interactivity API Basics

Was this helpful?

  1. Templates
  2. CSS & JS

WordPress Interactivity API

PreviousBEM MethodologyNextFile system storage

Last updated 4 months ago

Was this helpful?

About

Since version 6.5, the 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 or , it offers a declarative approach and provides server-side rendering out-of-the-box.

If you're new to the WordPress Interactivity API, we recommend reading a on our blog.

View and Card templates fully support it, meaning you can use any in any template, regardless of the render method (shortcode or Gutenberg block).

Example of usage:

For Twig: custom.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

@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

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 View or Card must be set to 'None'. This means you must choose either WP Interactivity or WebComponent, as you can't use both at once. 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 View or Card 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

2.3) @wordpress/interactivity Package

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.

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.

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 to understand the difference between state and context.

Note: While you can't call any WP function directly in Twig, the wp_interactivity_state function is 'mirrored' by AVF, making it available in any Twig template. This function calls the WP function behind the scenes. Read more about our Twig integration .

WP Interactivity employs , 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.

🧙‍♂️
Interactivity API
React
Vue
detailed explanation
directives
WP documentation
here
modules