Welcome to the Block Accessibility Checks Validation API — your toolkit for building accessibility checks and validation directly into your WordPress blocks.
This API makes it simple to register custom checks, provide instant feedback to editors, and maintain consistent accessibility standards across your content. Whether you’re developing custom blocks, plugins, or themes, you can extend the plugin to enforce accessibility rules automatically and in real time.
How It Works
The Block Accessibility Checks plugin uses a hybrid architecture that combines PHP and JavaScript:
- PHP handles registration, configuration, and admin UI integration
- JavaScript runs all validation logic live in the block editor
When a user edits a block, the plugin automatically runs your registered checks, displaying contextual messages or preventing publishing when critical errors are found. This setup ensures that validation runs instantly as users type, while remaining performant and fully configurable for administrators.
Core Concepts
Before you start, here are the key terms used throughout the API:
- Checks — Individual validation rules that test block content (e.g., “Image must include alt text”).
- Registry — The central system that stores all registered checks and their configuration.
- Severity Levels — Each check can be configured as an Error, Warning, or Disabled, giving flexibility across sites.
- Categories — Checks are grouped by type:
- Accessibility — WCAG and usability compliance.
- Validation — General content or structural quality checks.
- Plugin Integration — Each plugin that registers checks automatically gets its own section in Settings → Block Checks, where admins can adjust severity or disable rules.
Developer Workflow
Creating your own checks follows a simple three-step process:
- Register your check (PHP)
Define what to test, the severity type, and descriptive messages. - Implement validation (JavaScript)
Write logic that runs in the editor, returning pass/fail results in real time. - Enqueue your script
Load your JavaScript only in the block editor, ensuring compatibility with the Block Accessibility Checks plugin.
Your PHP configuration defines what to validate and how to display it; your JavaScript defines when it triggers and how it behaves.
Plugin Integration
External plugins that register their own checks are automatically recognized by the API. If your plugin uses register_check_with_plugin_detection(), it will:
- Automatically appear in Settings → Block Checks → [Your Plugin Name]
- Display your plugin’s name, version, and registered checks
- Allow site admins to enable, disable, or adjust severity levels per check
No extra setup or menu registration is needed — the system handles it for you.
Summary
The Validation API provides a powerful foundation for extending accessibility validation in WordPress:
- Simple: One consistent interface for all checks.
- Flexible: Works with any block, theme, or plugin.
- Scalable: Designed to support enterprise-level use with minimal overhead.
With just a few lines of code, you can make your custom blocks not only functional — but inclusive and accessible for everyone.