Create Custom Gutenberg Blocks Using Voxycure WP Plugin

Last updated on : December 7, 2025

Welcome, developers!

The Voxycure Framework allows theme and plugin authors to easily create dynamic Gutenberg blocks using PHP templates and field groups powered by the framework.

This guide shows you how to register custom blocks using the voxycure_blocks filter and how to structure your template files for frontend rendering.

What is voxycure_blocks?

The voxycure_blocks filter allows you to define a list of custom blocks (with unique IDs, labels, and template file paths) that the framework will recognize, register, and render dynamically within the Gutenberg editor.

💡 These blocks are backed by dynamic fields defined in the Voxycure Framework admin panel.

How to Register Custom Blocks

Here’s an example of how a developer can register blocks from their theme or plugin using this filter:

PHP

<?php
/**
 * Register Custom Gutenberg Blocks using Voxycure Framework
 *
 * Add this inside your theme's functions.php or inside a custom block registering file.
 * This filter extends the default block list and makes your block available in Gutenberg.
 */

add_filter( 'voxycure_blocks', function( $blocks ) {

    /**
     * Directory where all block templates are stored.
     * Make sure your template file exists here:
     *  /your-theme/template-parts/blocks/hero-banner.php
     */
    $template_dir = get_stylesheet_directory() . '/template-parts/blocks/';

    /**
     * Register Custom Blocks
     * Each block entry supports:
     * - id          → Unique identifier (Required)
     * - label       → Block Name (Shown inside editor)
     * - template    → Absolute path to template file (.php)
     * - description → (Optional) Short summary shown in block inserter
     * - category    → (Optional) Block Category like 'theme', 'layout', 'media'
     * - keywords    → (Optional) Search keywords in editor
     * - icon        → (Optional) Dashicon name or SVG
     *
     * You can register multiple blocks by adding more arrays.
     */
    $custom_blocks = [
        [
            'id'          => 'hero-banner',                  // Unique block slug (no spaces)
            'label'       => 'Hero Banner Block',            // Name visible to user in editor
            'template'    => $template_dir . 'hero-banner.php', // Block render template
            'description' => 'A hero section with heading, subheading & CTA button.',
            'category'    => 'theme',                        // Where block appears in inserter
            'keywords'    => [ 'hero', 'banner', 'header', 'cta', 'top section' ],
            'icon'        => 'megaphone',                    // Dashicon | Use SVG for custom icon
        ],
    ];

    /**
     * Merge with existing Voxycure blocks
     */
    return array_merge( $blocks, $custom_blocks );
});

Explanation of Each Parameter

id : A unique identifier for the block. (Used as slug and handle)
label : A human-readable name shown in the editor block list.
template : Absolute path to the PHP file that renders the block HTML.
description : A short summary about what the block does. This is displayed inside the block sidebar/inserter in Gutenberg. Helps users understand the purpose of the block before inserting it. Keep it brief and meaningful.
category : Defines the group/section where the block will appear inside the block inserter panel. Example categories include: theme, layout, media, widgets, or any custom one you register. Used for better organization.
keywords : An array of search terms related to your block. When the user types any of these words in block search, the block will appear. Improves discoverability inside the editor.
organization.
icon : Displays a visual icon for the block in the inserter. Can be a built-in Dashicon slug (e.g. megaphone, admin-users) or a custom SVG string/path for branding. Helps users recognize the block quickly.

You’ve Successfully Registered Your Block with Voxycure!

Nice work — your custom Gutenberg block is now connected to the Voxycure Framework using the voxycure_blocks hook.

But the real power of Voxycure comes from its field group system, which lets you visually define what kind of content your blocks will use. Here’s how you tie your block to real, editable fields:

Step 1 : Navigate to the Voxycure Admin Page

First, log in to your WordPress dashboard. On the left-hand menu, find and click on the “Voxycure” menu item.

This will take you to the main dashboard for the Voxycure Framework, where all the magic happens.

Step 2 : Create a New Field Group

In the Voxycure dashboard, click “Create New Field Group.” This opens the editor where you’ll define what fields your block will use.

Step 3 : Configure Your Field Group

This is the most important step, where you tell Voxycure Framework what your fields are for and where they should appear.

Group Name: Give your group a meaningful name (e.g., “Hero Banner”).
Group Type: This is important — from the “Group Type” dropdown, choose “Blocks.”

🧠 Tip: You’ll only see the list of blocks here if you’ve already registered them using the voxycure_blocks filter.
Also, make sure your block’s id in the filter matches the group’s ID exactly — that’s how Voxycure links your fields to the right template.

Step 4 : Add Your Custom Fields

Once your group is set, click “Add Field” to start adding content fields.
You can add anything — text, images, buttons, repeaters, sliders — whatever your block needs.

Not sure what each field type does? Check out the full field types documentation here.

Once you’re done, your block will now show up in the block editor with your custom fields, and it will render on the front end using the template file you registered.

You’re now building dynamic, field-powered Gutenberg blocks — without writing any JavaScript. 🙌

How to Build the Template File

Each block template receives an $attributes array which contains the field values defined in the framework UI (ACF-like). You can access and use these values like so:

PHP

<?php
$title       = $attributes['title'] ?? '';
$description = $attributes['description'] ?? '';
$button      = $attributes['button'] ?? [];
?>

<section class="custom-block">
    <h2><?php echo esc_html($title); ?></h2>
    <p><?php echo esc_html($description); ?></p>

    <?php if ($button['text'] && $button['url']) : ?>
        <a href="<?php echo esc_url($button['url']); ?>" class="btn">
            <?php echo esc_html($button['text']); ?>
        </a>
    <?php endif; ?>
</section>

🧠 Tip: Use helper functions like esc_html(), esc_url(), and wp_kses_post() to keep the output secure.

How the Framework Uses Your Blocks

The block appears inside the Gutenberg editor.
Its field settings are pulled dynamically from the Voxycure Framework UI.
When rendered on the frontend, the template file is loaded and $attributes are passed automatically.
You don’t need to register JS manually—Voxycure handles it.

Pro Tip: Use Dynamic Fields via Framework

All block data comes from the Group editor inside Voxycure (similar to ACF). Just match the block_id with the id you use in the voxycure_blocks array.

Here is full working theme with demo blocks :
https://github.com/Voxycure-Infotech/voxycure-theme/blob/main/includes/class-theme-blocks.php
https://github.com/Voxycure-Infotech/voxycure-theme/blob/main/template-parts/blocks/hero.php

Conclusion

With just a few simple steps, you’ve learned how to register custom Gutenberg blocks using the voxycure_blocks filter and connect them to dynamic field groups through the Voxycure Framework. This flexible system gives developers full control over both the editing experience and front-end output—without needing to write React or JavaScript. Whether you’re building hero banners, testimonials, or complex layouts, Voxycure makes it easy to create powerful, reusable blocks backed by clean PHP templates and field management.

Create Custom Gutenberg Blocks with Voxycure Framework WordPress Plugin