skilld
All skills
automattic avatar

/wp-interactivity-api

@0ddab58 official
by automatticautomattic/agent-skills211 stars
37

Use when building or debugging WordPress Interactivity API features (data-wp-* directives, @wordpress/interactivity store/state/actions, block viewScriptModule integration, wp_interactivity_*()) including performance, hydration, and directive behavior.

Ask your Agent

Use this Skill: https://skilld.dev/gh/automattic/agent-skills/wp-interactivity-api

This session only. Nothing lands on disk.

referencesdirectives-quickref.md

≈291 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Directives quick reference (high level)

Common directives to recognize in markup:

  • data-wp-interactive: declares an interactive region (and often a store namespace).
  • data-wp-context: provides server-rendered context/state.
  • data-wp-on--event: attaches event handlers (e.g. click, submit).
  • data-wp-on-async--event: async event handlers (preferred for most actions).
  • data-wp-bind--attr: binds DOM attributes to state.
  • data-wp-class--name: toggles CSS classes based on state.

Use these as search anchors when triaging bugs.

Unique directive IDs (WordPress 6.9+)

HTML doesn't allow duplicate attributes. To attach multiple handlers of the same type from different plugins, use the --- separator:

<button
  data-wp-on--click---plugin-a="actions.handleA"
  data-wp-on--click---plugin-b="actions.handleB"
>

Both handlers will fire. The ID after --- must be unique per element.

Deprecated directive

  • data-wp-ignore: Deprecated in WordPress 6.9. It was intended to prevent hydration of a region but broke context inheritance and client-side navigation. Will be removed in future versions. Avoid using it.

Source: SKILL.md on GitHub

Third-party checks

No alerts17d4 checks · Risk SAFE
  • Gen Agent Trust Hub17d

    This skill provides technical documentation and procedures for working with the WordPress Interactivity API. It is authored by a trusted vendor (Automattic) and follows standard WordPress security best practices, such as the use of nonces and server-side state initialization. No malicious patterns or security risks were identified.

  • Socket17d

    No alerts

  • Snyk17d

    Risk: LOW · No issues

  • Runlayer6mo

    1/4 files flagged

Provenance

Signed by skilld at 0ddab58. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 5 months ago.

Dormantupdated 9 months ago

Capability

Other metadata
compatibility
Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI.

Topics

  • wordpress
  • interactivity-api
  • data-wp-directives
  • javascript
  • php
  • hydration
  • block-development
  • state-management
  • server-rendering

README badge

README badge for automattic/agent-skills/wp-interactivity-api

What it does

Builds and debugs WordPress Interactivity API features using data-wp-* directives, the @wordpress/interactivity store, and block viewScriptModule integration. Covers server-side rendering, state initialization via wp_interactivity_state(), and common hydration issues in WordPress 6.9+.

Generated from the current SKILL.md.

Frequently asked

Does this skill work with WordPress versions below 6.9?
The skill targets WordPress 6.9+. Older versions do not have full Interactivity API support and will not work with this skill's workflows.
What if my project uses a custom bundler instead of @wordpress/scripts?
The skill can work with custom bundlers (webpack/vite), but you must confirm the repo's build output supports module output and module loading. Ask the user or inspect the build config if it's unclear.
How do I prevent layout shift when the client-side JavaScript loads?
Pre-render the initial state on the server using `wp_interactivity_state()` and `wp_interactivity_data_wp_context()` in PHP, and replicate derived state logic in PHP so directives like `data-wp-bind--hidden` render correctly before hydration.
What changed in WordPress 6.9 regarding directives?
`data-wp-ignore` is now deprecated and breaks context inheritance. The skill also supports unique directive IDs using the `---` separator to attach multiple directives of the same type to one element (e.g., `data-wp-on--click---plugin-a` and `data-wp-on--click---plugin-b`).
How do I debug when directives are present but nothing happens on interaction?
Verify the viewScriptModule is enqueued, the DOM element has `data-wp-interactive`, the store namespace matches the directive value, and check for JavaScript errors before hydration. Consult the bundled debugging guide for detailed steps.

Generated from the current SKILL.md. These answers refresh after source changes.