PHPackages                             starring-jane/acf-gutenberg-blocks - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. starring-jane/acf-gutenberg-blocks

ActiveLibrary[Utility & Helpers](/categories/utility)

starring-jane/acf-gutenberg-blocks
==================================

An elegant way for developers to register Gutenberg blocks using the ACF PRO blocks feature

1.1.0(5y ago)2751MITPHPPHP >7.0

Since Dec 1Pushed 5y ago4 watchersCompare

[ Source](https://github.com/starringjane/acf-gutenberg-blocks)[ Packagist](https://packagist.org/packages/starring-jane/acf-gutenberg-blocks)[ Docs](https://starringjane.com)[ RSS](/packages/starring-jane-acf-gutenberg-blocks/feed)WikiDiscussions main Synced yesterday

READMEChangelog (3)Dependencies (3)Versions (4)Used By (0)

ACF Gutenberg blocks
====================

[](#acf-gutenberg-blocks)

An elegant way for developers to register Gutenberg blocks using the Advanced Custom Fields PRO features.

- [Installation](#installation)
- [Define blocks](#define-blocks)
- [Register blocks](#register-blocks)
- [Configure fields](#configure-fields)
- [Retrieve data](#retrieve-data)
- [Define classes](#define-classes)
- [Render blocks](#render-blocks)

Installation
------------

[](#installation)

You can install this package through composer:

```
composer require starring-jane/acf-gutenberg-blocks
```

Define blocks
-------------

[](#define-blocks)

You can define custom blocks by creating classes that extend the base block class provided by this package.

By extending from the base block enables you to easily define custom blocks with a minimum of configuration:

```
use StarringJane\GutenbergBlocks\Block;

class MyCustomBlock extends Block
{
    protected $name = "custom";

    protected $title = "My Custom block";

    protected $description = "This is a custom block!";

    protected $category = 'custom';

    public function render()
    {
        // Render the HTML
    }
}
```

The base block class configures a few things by default behind the scence for convenience but can be changed easily. The following properties are defined out of the box:

```
protected $name;

protected $title;

protected $description;

protected $keywords = [];

protected $category;

protected $icon;

protected $mode = 'preview';

protected $default_align = '';

protected $align = ['wide', 'full'];

protected $allow_mode_switch = true;

protected $allow_multiple = true;

protected $parent = [];

protected $inner_blocks = false;

protected $wrap = true;
```

Register blocks
---------------

[](#register-blocks)

To enable the custom blocks you need to register them by hooking into the `acf/init` filter. This allows for a flexible way to define which blocks should be enabled.

You can enable blocks by passing an array with classes:

```
add_filter('acf/init', function () {
    \StarringJane\GutenbergBlocks\Gutenberg::register([
        MyCustomBlock::class,
    ]);
});
```

To automatically register all blocks in a directory can provide the relative path in the current theme:

```
add_filter('acf/init', function () {
    // Registers all blocks in `wp-content/themes/{current_theme}/blocks`
    \StarringJane\GutenbergBlocks\Gutenberg::register('blocks');
});
```

### Defining a parent block

[](#defining-a-parent-block)

You can define a block to have a parent block by updating the `$parent` property on your block class. This will result in the block being hidden from the blocks list in Gutenberg but only available as a "sub block" for the parent block.

```
class ChildBlock extends Block
{
    // ...

    protected $parent = [
        ParentBlock::class,
    ];
}
```

> For the child block to be selectable within the parent block you will need to set `$inner_blocks = true` on the parent block.

Configure fields
----------------

[](#configure-fields)

Fields can be added to a custom block by defining a `fields()` method on the class and make it return an array of fields to add.

This package includes [wordplate/extended-acf](https://github.com/wordplate/extended-acf) to define fields for a block in an easy and elegant way. Make sure to read the documentation to see which field types are available.

Below you can find an example of how you can define fields using this package:

```
public function fields()
{
    return [
        Text::make('Title')
            ->required(),

        Text::make('Body'),

        Url::make('Link', 'url')
            ->required()
            ->instructions('The url that should be displayed.'),
    ];
}
```

Retrieve data
-------------

[](#retrieve-data)

To retrieve the data from the defined fields you have a few options.

```
// Retrieve all fields as an array
$data = $this->data();

// Retrieve only the title
$title = $this->get('title');

// Retrieve the body and provide a default value as fallback
$body = $this->get('body', 'Hello world!');

// ...
```

Define classes
--------------

[](#define-classes)

By default a few classes are added to the wrapper HTML-element to be able to add general styles and specific styles for blocks and respect the alignment and other input from the Gutenberg editor.

You can simply fetch the CSS-classes using `getClasses()`.
To override or extend the classes that are added by defining your own `setClasses()`:

```
// Override the default classes
protected function setClasses($block)
{
    return [
        'my-custom-css-class',
        //
    ]);
}

// Extend the default classes
protected function setClasses($block)
{
    return array_merge(parent::setClasses($block), [
        'my-custom-css-class',
    ]);
}
```

> Please note that when overriding the default classes some Gutenberg behaviour will no longer work and will have to be added from the `$block` parameter to prevent this from happening!

Render blocks
-------------

[](#render-blocks)

All blocks require a `render()` method to be implemented. The way you render a block is up to you, an example with Wordpress' `get_template_part()` is given below:

```
public function render()
{
    // Make the data available in our template
    set_query_var('data', $this->data());

    return get_template_part('path-to-my-block-template');
}
```

Another great option is to use our [Wordpress Blade package](https://github.com/starringjane/wordpress-blade) for this. That will enable a lot of useful features for handling the views for the custom blocks. To use blade when rendering you only need to include the provided trait:

```
use StarringJane\GutenbergBlocks\Block;
use StarringJane\WordpressBlade\RendersBlade;

class MyCustomBlock extends Block
{
    use RendersBlade;

    // ...

    public function render()
    {
        return $this->view('blade.custom-block', [
            'data' => $this->data(),
        ]);
    }
}
```

### Wrapper Element

[](#wrapper-element)

By default every block is wrapped in a `` with the default classes when rendered. You can disable this globally by calling `Gutenberg::withoutWrapping()` **before** registering blocks.

When wrapping is disabled and you want to add the default CSS-classes in your own template you can add them like so:

```
public function render()
{
    // Make the CSS-classes available as a variable in the template
    set_query_var('default_classes', $this->getClasses());

    return get_template_part('path-to-my-block-template');
}
```

License
-------

[](#license)

[MIT](LICENSE) © [Starring Jane](https://starringjane.com/)

###  Health Score

25

—

LowBetter than 37% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity13

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~2 days

Total

3

Last Release

1984d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/24898080?v=4)[Starring Jane](/maintainers/starringjane)[@starringjane](https://github.com/starringjane)

---

Top Contributors

[![beblife](https://avatars.githubusercontent.com/u/9271492?v=4)](https://github.com/beblife "beblife (1 commits)")

###  Code Quality

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/starring-jane-acf-gutenberg-blocks/health.svg)

```
[![Health](https://phpackages.com/badges/starring-jane-acf-gutenberg-blocks/health.svg)](https://phpackages.com/packages/starring-jane-acf-gutenberg-blocks)
```

###  Alternatives

[barryvdh/laravel-ide-helper

Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion.

14.9k123.0M686](/packages/barryvdh-laravel-ide-helper)[yajra/laravel-datatables-oracle

jQuery DataTables API for Laravel

4.9k33.8M338](/packages/yajra-laravel-datatables-oracle)[orchestra/canvas

Code Generators for Laravel Applications and Packages

21017.2M158](/packages/orchestra-canvas)[illuminate/session

The Illuminate Session package.

9937.4M753](/packages/illuminate-session)[ashallendesign/favicon-fetcher

A Laravel package for fetching website's favicons.

190272.4k3](/packages/ashallendesign-favicon-fetcher)[recca0120/laravel-erd

Laravel ERD automatically generates Entity-Relationship Diagrams from your Laravel models and displays them using Vuerd.

36072.0k](/packages/recca0120-laravel-erd)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)