Add a Preview Image to an ACF Block

Show a styled preview screenshot in the block inserter instead of a generic icon.

php blocks

| April 2026

Show a styled preview screenshot in the block inserter instead of a generic icon.

Add an example property to your block.json with sample data. ACF will render a live preview using these values in the block inserter:

{
    "name": "acf/testimonial",
    "title": "Testimonial",
    "category": "theme",
    "acf": {
        "mode": "preview",
        "renderTemplate": "blocks/testimonial/render.php"
    },
    "example": {
        "attributes": {
            "mode": "preview",
            "data": {
                "quote": "This product completely transformed our workflow.",
                "author": "Jane Smith",
                "role": "Head of Engineering",
                "is_preview": true
            }
        }
    }
}

To show a static screenshot image instead of a live render, check for the preview flag in your template:

<?php
if ( get_field( 'is_preview' ) ) : ?>
    <img
        src="<?php echo esc_url( get_template_directory_uri() . '/blocks/testimonial/preview.png' ); ?>"
        alt="Testimonial block preview"
        style="width:100%;height:auto;"
    />
    <?php return;
endif;
?>

<!-- Normal block output below -->

This gives editors a polished visual in the inserter without needing to render the full block with placeholder data.

Related Snippets

php blocks

Create an ACF Block with InnerBlocks

Enable InnerBlocks within an ACF block to allow nesting other Gutenberg blocks inside your custom block.

{
    "name": "acf/hero",
    "title": "Hero Section",
    "category": "theme",

php blocks

Detect Preview Mode in ACF Block Templates

Use the $is_preview variable to render different output in the editor vs the front end.

/**
 * Google Map Block Template.
 *
 * @param array $block The block settings and attributes.

php blocks

Get the Additional CSS Class on an ACF Block

Access the 'Additional CSS class(es)' value from the block sidebar to apply custom styles in your render template.

/**
 * Card Block Template.
 *
 * @param array $block The block settings and attributes.

php blocks

Register an ACF Block with block.json

{
    "name": "acf/testimonial",
    "title": "Testimonial",
    "description": "A custom testimonial block.",

Stay Updated

Get ACF tips and new extensions in your inbox

No spam. Unsubscribe anytime.