How to Add a Real-Time Word Count Overlay to WordPress Gutenberg Blocks?

Have you ever wondered how many words you’ve written in each paragraph while crafting your WordPress posts? Learn how to add a smart, real-time word count overlay that appears as you write in the Gutenberg editor. This handy tool even warns you when paragraphs get too long!

What Does This Feature Do?

This clever addition to your WordPress editor:

• Shows a live word count for each paragraph and heading
• Displays a floating counter that follows your cursor
• Changes color when paragraphs exceed 300 words
• Works seamlessly within the Gutenberg interface
• It helps you maintain optimal paragraph lengths for better readability

(see the screenshot below)

Why You Need This Feature?

1. Improved Readability: Keep your paragraphs concise and reader-friendly
2. Better Content Structure: Instantly identify overly long paragraphs
3. SEO Benefits: Maintain optimal content structure for search engines
4. Writing Efficiency: Monitor word count in real-time without switching tools

Installation Options

Method 1: Using WPCode Plugin (Recommended for Beginners)

1. Install the free WPCode plugin from WordPress.org
2. Navigate to Code Snippets → Add Snippet
3. Create a new snippet
4. Select “PHP Snippets” as the code type
5. Copy and paste our provided code
6. Set “Location” to “Universal”
7. Activate the snippet
8. Save your changes

// Add a Real-Time Word Count Overlay to WordPress Gutenberg Blocks
function enqueue_word_count_overlay() {
    // Only load on Gutenberg editor pages
    if (!is_admin()) return;

    // Add styles for the word count overlay
    wp_add_inline_style('wp-edit-blocks', '
        .word-count-overlay {
            position: absolute;
            background: #f0f0f0;
            color: #666;
            padding: 2px 6px;
            border-radius: 3px;
            font-size: 11px;
            pointer-events: none;
            z-index: 9999;
            white-space: nowrap;
        }
        .word-count-overlay.long {
            background: #fff3cd;
            color: #856404;
        }
    ');

    // Add JavaScript for word count functionality
    wp_add_inline_script('wp-blocks', '
        wp.domReady(function() {
            // Create a reusable overlay element for word counts
            const overlay = document.createElement("div");
            overlay.className = "word-count-overlay";
            document.body.appendChild(overlay);

            const updateOverlay = (block, rect, wordCount) => {
                if (!block || !rect) return;

                overlay.textContent = `${wordCount} words`;
                overlay.style.left = `${rect.left + rect.width - 80}px`;
                overlay.style.top = `${rect.top - 20}px`;
                overlay.style.display = "block";

                if (wordCount > 300) {
                    overlay.classList.add("long");
                } else {
                    overlay.classList.remove("long");
                }
            };

            const hideOverlay = () => {
                overlay.style.display = "none";
            };

            // Update the overlay dynamically
            const updateWordCount = () => {
                const blocks = wp.data.select("core/block-editor").getBlocks();

                const activeBlock = wp.data.select("core/block-editor").getBlockSelectionStart();
                const blockData = blocks.find(block => block.clientId === activeBlock);

                if (blockData && ["core/paragraph", "core/heading"].includes(blockData.name)) {
                    const blockElement = document.querySelector(`[data-block="${blockData.clientId}"]`);
                    const rect = blockElement?.getBoundingClientRect();

                    const content = blockData.attributes.content || "";
                    const wordCount = content.trim().split(/\s+/).filter(word => word.length > 0).length;

                    updateOverlay(blockElement, rect, wordCount);
                } else {
                    hideOverlay();
                }
            };

            // Monitor block selection and content changes
            wp.data.subscribe(updateWordCount);

            // Hide overlay on editor clicks
            document.querySelector(".edit-post-layout").addEventListener("click", hideOverlay);
        });
    ');
}
add_action('enqueue_block_editor_assets', 'enqueue_word_count_overlay');

Method 2: Child Theme Method (Advanced Users)

While possible, we don’t recommend adding this to your child theme’s functions.php because:

• You might lose the functionality during theme updates
• It’s harder to manage and maintain
• There’s a higher risk of syntax errors

How to Use the Word Count Overlay?

Once installed, the feature works automatically:

1. Open any post or page in the Gutenberg editor
2. Click on any paragraph or heading block
3. Look for the word count overlay in the top-right corner of the block
4. Watch it update as you type
5. Notice the yellow warning when exceeding 300 words

Customization Options

Want to adjust the feature? Here are some common modifications:

Change the word limit warning:

• Find: wordCount > 300
• Adjust the number to your preferred limit

Modify the overlay colors:

• Normal state: Edit the #f0f0f0 value
• Warning state: Edit the #fff3cd value

Adjust the position:

• Modify the left and top values in the JavaScript

Troubleshooting Common Issues

If the word count overlay isn’t appearing:

1. Clear your browser cache
2. Ensure WordPress is updated
3. Check if your theme supports Gutenberg
4. Verify the code is properly activated
5. Disable conflicting plugins temporarily

Pro Tips for Writers

• Use this tool to maintain consistent paragraph lengths
• Aim for 2-3 sentences per paragraph for web content
• Break up paragraphs showing the yellow warning
• Consider your audience when setting word count limits

Conclusion

Adding a word count overlay to your Gutenberg editor is a simple yet powerful way to improve your content creation process. While there are several ways to implement this feature, the WPCode plugin method offers the best combination of ease and reliability for most users.