JavaScript Integration - Block Accessibility Checks

JavaScript powers all real-time validation logic in the block editor. It runs instantly as users edit content, providing immediate feedback while keeping the editor fast and responsive.

Your JavaScript integrates with the Block Accessibility Checks plugin using the ba11yc.validateBlock filter. Each time a block is updated, the plugin calls your validation function to determine whether it passes or fails based on the rules you registered in PHP.

Implementing Validation Logic

Use the ba11yc.validateBlock filter to add your custom validation logic:

import { addFilter } from '@wordpress/hooks';

addFilter(
    'ba11yc.validateBlock',
    'my-plugin/validation',
    (isValid, blockType, attributes, checkName, rule) => {
        // Only handle your block type
        if (blockType !== 'my-plugin/custom-block') {
            return isValid;
        }
        
        // Implement your validation logic
        switch (checkName) {
            case 'content_length':
                const content = attributes.content || '';
                return content.length <= 500;
            default:
                return isValid;
        }
    }
);

Filter Parameters

Each validation function receives five parameters and must return either a Boolean or a custom result object.

isValid (mixed)

Current validation state.
Return it unchanged if the check doesn’t apply to your block.

if (blockType !== 'my-plugin/custom-block') {
    return isValid; // Pass through
}

blockType (string)

The name of the block being validated (e.g. 'my-plugin/custom-block').
Block types are case-sensitive and must match your registered block name.

if (blockType === 'my-plugin/card-block') {
    // Validate card block
}

attributes (object)

The block’s attributes, passed from the editor.
Use these values to test for required fields, content length, or custom logic.

const title = attributes.title || '';
const hasImage = !!attributes.imageId;
const content = attributes.content || '';

checkName (string)

The unique name of the validation check — this must match the name used in your PHP registration.

if (checkName === 'title_required') {
    return !!(attributes.title && attributes.title.trim());
}

rule (object)

The configuration object registered in PHP (includes error_msg, warning_msg, type, etc.).

// Access the error message from PHP
console.log(rule.error_msg);

// Check the severity type
if (rule.type === 'error') {
    // Handle errors differently
}

Return Values

Your validation function should return one of the following:

Boolean: true or false

Return true if the check passes, false if it fails.
This is the simplest and most common approach.

if (checkName === 'valid_url') {
    const url = attributes.url || '';
    return /^https?:\/\/.+/.test(url);
}

Object

Return a custom object when you need to override the default behavior or message.

return {
    isValid: false,              // Boolean: did the check pass?
    mode: 'error',               // String: 'error' or 'warning'
    message: 'Custom message',   // String: Override the default message
    data: {                      // Object: Additional data
        details: 'More info'
    }
};

Pass-through

If the validation doesn’t apply to your block, return the existing isValid value unchanged.

// Not your block type
if (blockType !== 'my-plugin/custom-block') {
    return isValid;
}

Accessing Validation Rules

The PHP registry automatically exposes check configurations to JavaScript through a global object. Use these rules to tailor validation behavior dynamically.

// Access all validation rules
const validationRules = window.BlockAccessibilityChecks?.validationRules || {};

// Get rules for a specific block
const myBlockRules = validationRules['my-plugin/custom-block'] || {};

// Access a specific rule
const contentLengthRule = myBlockRules.content_length;

// Use rule configuration
if (contentLengthRule) {
    console.log(contentLengthRule.error_msg);
    console.log(contentLengthRule.type);
}

Best Practices

Early return for non-matching blocks to keep validation fast.
Keep logic small — short checks run instantly, large ones can be deferred or cached.
Use helper functions for complex or repeated logic.
Avoid rebuilding regex or large data inside validation calls.
Validate only changed attributes when possible.

Example: Centralized Validation

For larger plugins with multiple blocks, organize validation by block type and import functions from separate files:

import { addFilter } from '@wordpress/hooks';
import { validateCardBlock } from './validators/card-block';
import { validateHeroBlock } from './validators/hero-block';

addFilter(
    'ba11yc.validateBlock',
    'my-plugin/validation',
    (isValid, blockType, attributes, checkName) => {
        switch (blockType) {
            case 'my-plugin/card-block':
                return validateCardBlock(attributes, checkName, isValid);
            case 'my-plugin/hero-block':
                return validateHeroBlock(attributes, checkName, isValid);
            default:
                return isValid;
        }
    }
);

Performance Tips

Early exits — always check blockType first.
Cache results for heavy calculations.
Reuse regex patterns instead of creating them inline.
Debounce expensive checks that depend on rapid typing or large attributes.