Create a Custom Gutenberg Block with ACF

Gutenberg, WordPress’s block editor, simplifies the process of visually creating and managing content. By using Advanced Custom Fields (ACF), you can easily build custom blocks for Gutenberg without extensive knowledge of JavaScript.

In this guide, you’ll learn how to create a custom Call to Action (CTA) block using the ACF plugin. Let’s get started!

Step 1: Register the Custom Block in functions.php

In your theme’s functions.php file, register the new block using the acf_register_block_type() function.

function register_custom_cta_block() {
    if (function_exists('acf_register_block_type')) {
        acf_register_block_type(array(
            'name'              => 'custom_cta',
            'title'             => __('Custom CTA Block'),
            'description'       => __('A custom call to action block with an image, title, description, and button.'),
            'render_template'   => 'template-parts/blocks/custom-cta.php',
            'category'          => 'common',
            'icon'              => 'megaphone',
            'keywords'          => array('cta', 'call to action', 'button'),
            'enqueue_style'     => get_template_directory_uri() . '/template-parts/blocks/custom-cta.css',
        ));
    }
}
add_action('acf/init', 'register_custom_cta_block');

This code snippet registers a custom Gutenberg block in WordPress using the Advanced Custom Fields (ACF) plugin. Here’s a detailed explanation of each part of the code:

Block Configuration Settings:

• ‘name’ => ‘custom_cta’: The unique identifier for the block. This must be lowercase and cannot contain spaces.
• ‘title’ => __(‘Custom CTA Block’): The display name of the block in the Gutenberg editor.
• ‘description’ => __(‘A custom call to action block with an image, title, description, and button.’): A brief description of the block’s functionality.
• ‘render_template’ => ‘template-parts/blocks/custom-cta.php’: The path to the PHP file that contains the template for rendering the block.
• ‘category’ => ‘common’: The category where the block will appear in the block editor.
• ‘icon’ => ‘megaphone’: The icon displayed in the block editor for the block.
• ‘keywords’ => array(‘cta’, ‘call to action’, ‘button’): Keywords that help users find the block when searching in the Gutenberg editor.
• ‘enqueue_style’ => get_template_directory_uri() . ‘/template-parts/blocks/custom-cta.css’: The URL to the CSS file used to style the block.

This code effectively registers a custom Call to Action (CTA) block for Gutenberg, allowing you to include an image, title, description, button text, and button URL.

Notice that the block is styled with a dedicated CSS file and rendered via a PHP template. This approach provides a simple way to create dynamic blocks without extensive JavaScript knowledge.

Step 2: Create the ACF Field Group for the Block

1. In your WordPress dashboard, go to ACF > Field Groups.
2. Click Add New to create a new field group.
3. Name the field group Custom CTA Block Fields.

Add the following fields:

• Title: Add a Text field for the CTA title.
• Description: Add a Text Area field for the CTA description.
• Image: Add an Image field for the CTA image.
• Button Text: Add a Text field for the button label.
• Button URL: Add a URL field for the button link.
• Background Color: Add a Color Picker field for setting the block’s background color.

It looks like this:

Create the ACF Field Group for the Block

When you’ve finished adding the fields, go to the “Location Rules” settings in the ACF field group editor. Set the rule to Block is equal to Custom CTA Block.

Step 3: Create the Block Template

In your theme directory, navigate to the template-parts/blocks/ folder. If this folder doesn’t exist, create it. Then, create a new file within this folder named custom-cta.php.

This file will serve as the template for your custom block and will define how the block’s content is rendered on the front end. Add the following code to this file:

<?php
$title = get_field('title');
$description = get_field('description');
$image = get_field('image');
$button_text = get_field('button_text');
$button_url = get_field('button_url');
$background_color = get_field('background_color');
?>

<div class="custom-cta-block" style="background-color: <?php echo esc_attr($background_color); ?>">
    <?php if ($image): ?>
        <img src="<?php echo esc_url($image['url']); ?>" alt="<?php echo esc_attr($image['alt']); ?>" class="cta-image" />
    <?php endif; ?>

    <div class="cta-content">
        <?php if ($title): ?>
            <h3 class="cta-title"><?php echo esc_html($title); ?></h3>
        <?php endif; ?>

        <?php if ($description): ?>
            <p class="cta-description"><?php echo esc_html($description); ?></p>
        <?php endif; ?>

        <?php if ($button_text && $button_url): ?>
            <a href="<?php echo esc_url($button_url); ?>" class="cta-button">
                <?php echo esc_html($button_text); ?>
            </a>
        <?php endif; ?>
    </div>
</div>

Step 4: Create the Block CSS File

Create a CSS file at template-parts/blocks/custom-cta.css and add the following CSS rules (feel free to modify them to match your design preferences):

.custom-cta-block {
    padding: 40px;
    border-radius: 15px;
    text-align: center;
    color: #fff;
    max-width: 700px;
    margin: 30px auto;
    box-shadow: 0 4px 20px rgba(0, 0, 0, 0.1);
    transition: transform 0.3s ease;
}

.custom-cta-block:hover {
    transform: translateY(-5px);
}

.cta-image {
    max-width: 120px;
    margin-bottom: 20px;
    border-radius: 50%;
    border: 4px solid #fff;
}

.cta-title {
    font-size: 28px;
    margin: 15px 0;
    font-weight: 700;
}

.cta-description {
    font-size: 18px;
    margin-bottom: 20px;
    line-height: 1.5;
}

.cta-button {
    display: inline-block;
    padding: 12px 25px;
    background-color: #ff6b6b;
    color: #fff;
    text-decoration: none;
    border-radius: 25px;
    font-weight: bold;
    text-transform: uppercase;
    letter-spacing: 1px;
    transition: background-color 0.3s ease;
}

.cta-button:hover {
    background-color: #e05656;
}

Step 5: Add the Block in the Gutenberg Editor

1. Open a post or page in the WordPress block editor.
2. Click the + button to add a new block.
3. Search for Custom CTA Block and insert it into the content.
4. Fill in the fields for the title, description, image, button text, button URL, and background color.
5. Publish or preview the post to see the block in action.

Add the Block in the Gutenberg Editor

Final Thoughts

By following these steps, you’ve successfully created a custom Gutenberg block using ACF. This method provides a powerful and flexible way to build dynamic content blocks without needing advanced JavaScript skills. You can customize the block further to fit your specific design needs and requirements.

If you encounter any issues or have questions, feel free to leave a comment below!