Skip to content

Commit 5d74151

Browse files
yCodeTechyCodeTech
committed
feat: add ACF Block Keys Reference documentation for PHP registration
1 parent 4f922bc commit 5d74151

File tree

1 file changed

+213
-0
lines changed

1 file changed

+213
-0
lines changed

‎WordPress/ACF-Block-Keys-Reference.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# ACF Block Keys Reference for PHP Registration
2+
3+
Complete reference for block keys available when registering a `wp/acf` block via PHP.
4+
5+
This guide covers both approaches:
6+
7+
- `acf_register_block_type()` (ACF PHP API)
8+
- `register_block_type()` with ACF-specific settings
9+
10+
## Table of Contents
11+
12+
- [ACF PHP Registration Keys](#acf-php-registration-keys)
13+
- [ACF Supports Keys](#acf-supports-keys)
14+
- [ACF Metadata Keys](#acf-metadata-keys)
15+
- [Core Block Supports Keys](#core-block-supports-keys)
16+
- [Core Block Type Keys (PHP)](#core-block-type-keys-php)
17+
- [Asset and Render Keys (Core)](#asset-and-render-keys-core)
18+
- [Complete PHP Example](#complete-php-example)
19+
20+
---
21+
22+
## ACF PHP Registration Keys
23+
24+
Keys used with `acf_register_block_type()`:
25+
26+
| Key | Type | Required | Description |
27+
| --- | --- | --- | --- |
28+
| `name` | string | Yes | Block slug without prefix. ACF registers it as `acf/{name}`. |
29+
| `title` | string | Yes | Block title shown in inserter. |
30+
| `description` | string | No | Inserter/help description. |
31+
| `category` | string | No | Inserter category (for example `formatting`, `widgets`, `layout`). |
32+
| `icon` | string/array | No | Dashicon slug, SVG, or icon config array. |
33+
| `keywords` | array | No | Search keywords in inserter. |
34+
| `post_types` | array | No | Restrict block to specific post types. |
35+
| `mode` | string | No | Default display mode: `preview`, `edit`, or `auto`. |
36+
| `align` | string | No | Default alignment: `left`, `center`, `right`, `wide`, `full`. |
37+
| `supports` | array | No | Supports map for block features (see sections below). |
38+
| `render_template` | string | No | PHP template path used to render block output. |
39+
| `render_callback` | callable | No | Callback to render block output. |
40+
| `enqueue_style` | string | No | Style URL enqueued when block appears. |
41+
| `enqueue_script` | string | No | Script URL enqueued when block appears. |
42+
| `enqueue_assets` | callable | No | Callback to enqueue scripts/styles for the block. |
43+
| `example` | array | No | Inserter preview/example configuration. |
44+
45+
### Notes
46+
47+
- Provide either `render_template` or `render_callback` (or both if your callback routes logic to templates).
48+
- `name` should be lowercase and slug-safe.
49+
- ACF recommends block metadata (`block.json`) for new projects, but PHP registration is still common.
50+
51+
---
52+
53+
## ACF Supports Keys
54+
55+
These are commonly used ACF-specific keys inside `supports`:
56+
57+
| Key | Type | Default | Description |
58+
| --- | --- | --- | --- |
59+
| `jsx` | bool | `false` | Enables JSX-powered live preview behavior for ACF blocks. |
60+
| `mode` | bool | `true` | Allows toggling between edit and preview modes. |
61+
| `multiple` | bool | `true` | Allows multiple instances of the block in content. |
62+
| `anchor` | bool | `false` | Enables HTML anchor input in block settings. |
63+
| `align` | bool/array | `true` | Enable alignments globally or limit to allowed values. |
64+
| `align_text` | bool | `false` | Adds text alignment controls for supported blocks. |
65+
| `align_content` | bool/string/array | `false` | Adds content alignment controls (varies by UI support/version). |
66+
| `full_height` | bool | `false` | Adds full-height toggle support. |
67+
68+
---
69+
70+
## ACF Metadata Keys
71+
72+
When using ACF Blocks v3 (`block.json`) with PHP registration/loading, ACF-specific keys live under the `acf` object.
73+
74+
| Key | Type | Description |
75+
| --- | --- | --- |
76+
| `mode` | string | Default mode: `preview`, `edit`, or `auto`. |
77+
| `renderTemplate` | string | Template path for server rendering. |
78+
| `renderCallback` | string/callable reference | Callback used for server rendering. |
79+
| `postTypes` | array | Allowed post types for this block. |
80+
| `blockVersion` | int | ACF block schema version (commonly `3`). |
81+
| `validate` | bool | Enables/disables ACF field validation for the block. |
82+
| `usePostMeta` | bool | Stores block field values in post meta instead of block comment JSON (when supported). |
83+
84+
---
85+
86+
## Core Block Supports Keys
87+
88+
Core `supports` keys are passed under `supports` and handled by WordPress block editor.
89+
90+
| Key | Type | Description |
91+
| --- | --- | --- |
92+
| `align` | bool/array | Alignment toolbar support. |
93+
| `anchor` | bool | HTML anchor field. |
94+
| `ariaLabel` | bool | Accessible label UI support. |
95+
| `color` | bool/array | Text/background/link color controls and related options. |
96+
| `dimensions` | bool/array | Dimension controls such as min-height/aspect ratio. |
97+
| `filter` | bool/array | Visual filter support where available. |
98+
| `html` | bool | Allow editing as raw HTML. |
99+
| `inserter` | bool | Show/hide in inserter. |
100+
| `interactivity` | bool/array | Interactivity API support. |
101+
| `layout` | bool/array | Layout settings for container-style blocks. |
102+
| `lock` | bool/array | Block locking capabilities. |
103+
| `position` | bool/array | Position controls where supported. |
104+
| `renaming` | bool | Allow block rename in list view. |
105+
| `reusable` | bool | Reusable/synced pattern support. |
106+
| `shadow` | bool/array | Shadow controls. |
107+
| `spacing` | bool/array | Margin/padding/blockGap controls. |
108+
| `splitting` | bool | Enter-to-split behavior for text blocks. |
109+
| `typography` | bool/array | Font size/line height/letter spacing/etc. |
110+
| `__experimentalBorder` | bool/array | Border controls (older/experimental naming in some versions). |
111+
| `border` | bool/array | Border controls (stable naming in newer WP versions). |
112+
113+
### Important
114+
115+
- Available supports and exact subkeys vary by WordPress version.
116+
- If a support key is unknown in your target WP version, it is ignored.
117+
118+
---
119+
120+
## Core Block Type Keys (PHP)
121+
122+
If you register blocks with `register_block_type()`, these are the main structural keys used in PHP args or metadata mapping:
123+
124+
| Key | Type | Description |
125+
| --- | --- | --- |
126+
| `api_version` | int | Block API version. |
127+
| `name` | string | Fully-qualified block name (for example `acf/hero`). |
128+
| `title` | string | Block title. |
129+
| `category` | string | Inserter category. |
130+
| `parent` | array | Allowed direct parent blocks. |
131+
| `ancestor` | array | Allowed ancestor blocks. |
132+
| `allowed_blocks` | array | Allowed child blocks for container blocks. |
133+
| `icon` | string/array | Block icon config. |
134+
| `description` | string | Block description. |
135+
| `keywords` | array | Inserter search keywords. |
136+
| `textdomain` | string | Translation domain. |
137+
| `attributes` | array | Block attribute schema. |
138+
| `provides_context` | array | Context provided to descendants. |
139+
| `uses_context` | array | Context consumed from ancestors. |
140+
| `selectors` | array | CSS selectors map used by style engine features. |
141+
| `supports` | array | Feature support map. |
142+
| `styles` | array | Block style variations. |
143+
| `variations` | array | Block variations list. |
144+
| `example` | array | Inserter preview/example data. |
145+
| `block_hooks` | array | Automatic block placement hooks. |
146+
147+
---
148+
149+
## Asset and Render Keys (Core)
150+
151+
Core registration also supports asset and render keys:
152+
153+
| Key | Type | Description |
154+
| --- | --- | --- |
155+
| `render_callback` | callable | Server-side render callback. |
156+
| `editor_script_handles` | array | Script handles for editor only. |
157+
| `script_handles` | array | Script handles for editor and frontend. |
158+
| `view_script_handles` | array | Script handles for frontend only. |
159+
| `editor_style_handles` | array | Style handles for editor only. |
160+
| `style_handles` | array | Style handles for editor and frontend. |
161+
| `view_style_handles` | array | Style handles for frontend only. |
162+
| `editor_script_module_ids` | array | ES module IDs for editor scripts. |
163+
| `view_script_module_ids` | array | ES module IDs for frontend scripts. |
164+
165+
For ACF blocks, you typically still render via `render_template` or `render_callback`, while assets can be handled by ACF enqueue keys or standard WordPress handles.
166+
167+
---
168+
169+
## Complete PHP Example
170+
171+
```php
172+
add_action('acf/init', function () {
173+
if (!function_exists('acf_register_block_type')) {
174+
return;
175+
}
176+
177+
acf_register_block_type([
178+
'name' => 'hero',
179+
'title' => 'Hero',
180+
'description' => 'Homepage hero section.',
181+
'category' => 'layout',
182+
'icon' => 'cover-image',
183+
'keywords' => ['hero', 'banner', 'header'],
184+
'post_types' => ['page'],
185+
'mode' => 'preview',
186+
'align' => 'wide',
187+
'render_template' => get_theme_file_path('template-parts/blocks/hero.php'),
188+
'enqueue_style' => get_theme_file_uri('assets/css/blocks/hero.css'),
189+
'supports' => [
190+
'jsx' => true,
191+
'align' => ['wide', 'full'],
192+
'anchor' => true,
193+
'mode' => true,
194+
'multiple' => true,
195+
'spacing' => [
196+
'margin' => true,
197+
'padding' => true,
198+
],
199+
'typography' => [
200+
'fontSize' => true,
201+
],
202+
],
203+
'example' => [
204+
'attributes' => [
205+
'mode' => 'preview',
206+
'data' => [
207+
'headline' => 'Example Hero Headline',
208+
],
209+
],
210+
],
211+
]);
212+
});
213+
```

0 commit comments

Comments
 (0)