# Lazy Blocks

> Lazy Blocks is a WordPress plugin for building custom Gutenberg blocks. A block is
> defined on a screen in wp-admin rather than in a code editor, its fields are called
> controls, and its output is written in Handlebars, PHP, or a template file in the
> theme. There is no React and no build step.

The free plugin is at https://wordpress.org/plugins/lazy-blocks/. Pro adds nine more control types (Posts,
Taxonomy, Users, Link, Units, Token Field, Panel, Divider, Message), conditional logic on
controls, RichText editing on the canvas, custom block namespaces and collections, editor
block preloading, and Rank Math and Yoast content analysis of rendered blocks. Pro plans
are yearly: Personal $49 (1 website), Freelancer $169 (20 websites), Agency $299 (unlimited websites).

Every link below points at the Markdown version of the page. The HTML page is the same
address without the .md suffix. The whole corpus in one file is at
https://www.lazyblocks.com/llms-full.txt.

---

# Overview

Source: https://www.lazyblocks.com/docs/overview/

Lazy Blocks is a WordPress plugin for building custom blocks. You define a block on a screen in wp-admin rather than in a code editor, and you write its markup in Handlebars or PHP rather than in React. There is no build step and no `block.json` to maintain.

## What a block is here

A block is a WordPress post of the `lazyblocks` type. It holds three things:

**Controls.** The fields a person filling in the block sees. A control has a type, a name, and a place to appear, either in the inspector sidebar or in the block body on the canvas. Roughly thirty types ship with the plugin, from a plain text field to an image picker to a repeater. See [Controls](https://www.lazyblocks.com/docs/blocks-controls/overview/).

**Code.** What the block outputs. Each control's value arrives in your markup under the name you gave it. See [Block Code](https://www.lazyblocks.com/docs/blocks-code/overview/).

**Settings.** The title, icon, category and keywords that put the block in the inserter, plus the WordPress block supports you want enabled, such as alignment, colour or spacing. See [Create Block](https://www.lazyblocks.com/docs/create-block/).

Once saved and published, the block registers like any other and appears in the inserter. Deactivating it takes it out again without deleting it. See [Blocks Screen](https://www.lazyblocks.com/docs/managing-blocks/blocks-screen/).

## Writing the output

Three output methods, chosen per block:

[HTML + Handlebars](https://www.lazyblocks.com/docs/blocks-code/handlebars/) is the default. Control values are interpolated as `{{control-name}}`, and the plugin registers helpers for truncating a string, comparing two values, running a shortcode and formatting a date.

[PHP](https://www.lazyblocks.com/docs/blocks-code/php/) gives you `$attributes['control-name']` and the whole WordPress API. Use it when the block queries something or branches on more than a template can express.

[Theme Template](https://www.lazyblocks.com/docs/blocks-code/theme-template/) moves the markup into a file in your theme, at `blocks/<block-slug>/block.php`, so it lives in version control alongside the rest of the theme.

Alongside the markup you can attach CSS and a front-end script, both loaded only on pages where the block is used. See [Styles & Scripts](https://www.lazyblocks.com/docs/blocks-code/styles-scripts/).

Four components work inside block code regardless of the output method: [useBlockProps](https://www.lazyblocks.com/docs/blocks-code/use-block-props/) for the block wrapper, [InnerBlocks](https://www.lazyblocks.com/docs/blocks-code/inner-blocks/) for nesting other blocks inside yours, [RichText](https://www.lazyblocks.com/docs/blocks-code/rich-text/) for editing a value directly on the canvas, and a [PHP callback](https://www.lazyblocks.com/docs/blocks-code/php-callback/) for rendering from a function in your theme.

## Fields without a block

A control can store its value in post meta instead of in the block. That turns the block builder into a custom fields editor: define the fields, place the block on the post, and read the values in your theme with `get_lzb_meta( 'field_name' )`. See [Display Custom Fields](https://www.lazyblocks.com/docs/examples/display-custom-fields-meta/).

## Free and Pro

The free plugin on [WordPress.org](https://wordpress.org/plugins/lazy-blocks/) builds complete blocks. It carries the block builder, all three output methods, block styles and scripts, and twenty of the control types, including Repeater, Gallery, Image, Rich Text and Inner Blocks.

Pro adds nine more control types, the ones that query WordPress or lay the inspector out: Posts, Taxonomy, Users, Link, Units, Token Field, Panel, Divider and Message. It also adds:

- [Conditional Logic](https://www.lazyblocks.com/docs/blocks-controls/conditional-logic/), which hides a control until its rules pass
- [RichText on the canvas](https://www.lazyblocks.com/docs/blocks-code/rich-text/), so a value is typed in place instead of in the sidebar
- [Collections and custom namespaces](https://www.lazyblocks.com/docs/managing-blocks/collections/), which register your blocks under your own name rather than `lazyblock/`
- [Editor preloading](https://www.lazyblocks.com/docs/performance/), which renders block previews with the edit screen instead of one request per block
- [Rank Math and Yoast support](https://www.lazyblocks.com/docs/integrations/seo-plugins/), so their content analysis reads the rendered block rather than the raw markup

[Free vs Pro](https://www.lazyblocks.com/free-vs-pro/) compares the two feature by feature.

## Getting started

[Install the plugin](https://www.lazyblocks.com/docs/getting-started/install-lazy-blocks-plugin/), then [build your first block](https://www.lazyblocks.com/docs/create-block/). The [Alert Block](https://www.lazyblocks.com/docs/examples/alert-block/) walkthrough builds one end to end.

If you are weighing this against writing a block in React, [WordPress custom blocks](https://www.lazyblocks.com/wordpress-custom-blocks/) compares the three ways of building one.

---

# Install Lazy Blocks Plugin

Source: https://www.lazyblocks.com/docs/getting-started/install-lazy-blocks-plugin/

There are two ways to install the Lazy Blocks plugin on your WordPress site. Choose the method that works best for you.

## Method 1: Install from WordPress Dashboard (Recommended)

1. Navigate to **Admin Menu → Plugins → Add New**
2. In the search field, type **"Lazy Blocks"**
3. Click **Install Now** when you see the plugin
4. After installation completes, click **Activate**

Once activated, you'll see **Lazy Blocks** in your admin menu:

## Method 2: Manual Installation

1. Download the plugin from [WordPress.org](https://wordpress.org/plugins/lazy-blocks/)
2. Go to **Admin area → Plugins → Add New**
3. Click **Upload Plugin** at the top of the page
4. Choose the downloaded file and click **Install Now**

## Next Steps

After installation, check out our [block creation guide](https://www.lazyblocks.com/docs/create-block/) to learn how to create your first block.

---

# Purchase Lazy Blocks Pro plugin

Source: https://www.lazyblocks.com/docs/getting-started/purchase-pro-version/

Welcome! You've made a great decision choosing to build your custom blocks with Lazy Blocks plugin. While the free version is more than enough for you to build a powerful blocks, it doesn't offer as many perks as Lazy Blocks Pro.

In this guide, we'll walk you through the complete process for upgrading to Lazy Blocks Pro. Let's get started!

## How to select a plan

Lazy Blocks Pro has **3 plans** you can choose from:

1. The Personal plan
2. The Freelancer plan
3. The Agency plan

All 3 plans comes with the same features, which you can find on the [Free vs Pro](https://www.lazyblocks.com/free-vs-pro/) page. The only difference is the number of sites where the Lazy Blocks Pro can be used.

|              | Personal | Freelancer     | Agency          |
| ------------ | -------- | -------------- | --------------- |
| **Websites** | 1 Site   | Up to 20 Sites | Unlimited Sites |

## How to make purchase

1. Go to [Lazy Blocks Pro pricing page](https://www.lazyblocks.com/pro/#pricing)
2. Select the plan and click **Buy Now**
3. You will see the checkout form in the popup, where you will need to fill the required fields and make a payment:

Once you've purchased the Lazy Blocks Pro plugin, you will receive the full information about this purchase in your email. There will be a download link (available for 72 hours), license key and a link to your account page.

## How to install Lazy Blocks Pro

Head over to [Install Lazy Blocks Pro version article](https://www.lazyblocks.com/docs/getting-started/install-pro-version/) for a step-by-step guide on how to install Lazy Blocks Pro on your website.

---

# Install Lazy Blocks Pro version

Source: https://www.lazyblocks.com/docs/getting-started/install-pro-version/

**Congratulations on signing up for Lazy Blocks Pro.** The plugin arrives as a zip file with your order, installs like any other WordPress plugin, and needs your license key for automatic updates.

## Which receipt you have

Where the download and the license key are depends on who sent your receipt:

- **The Lemon Squeezy logo is at the top.** Follow the steps on this page.
- **It came from "Devoice LLC via Paddle", with the Paddle logo at the bottom, or from nkdev.info.** Your subscription started on Paddle and still renews there. See [Licenses bought through Paddle](https://www.lazyblocks.com/docs/getting-started/legacy-licenses/).

Not sure which one you have? [Find your download](https://www.lazyblocks.com/account/) shows both receipts side by side.

## Download from Email

Once you've purchased the Lazy Blocks Pro plugin, you will receive the full information about this purchase in your email. There will be a download link, license key and a link to your account page.

Just click on the link to download the plugin archive. If you can't download it, follow the next step.

  <figcaption>Example of a Lemon Squeezy receipt.</figcaption>

## Download from Account

1. After purchasing Lazy Blocks Pro, go to your <a href="https://app.lemonsqueezy.com/my-orders" target="_blank">Lemon Squeezy orders</a>
2. Once logged in, you will see all your orders. Select the Lazy Blocks Pro order page.
3. On the right side you will see files to download and license key

## Install

1. Head over to your site, to the WordPress dashboard
2. Open **Admin Menu → Plugins** and click on the **Add New** button
3. Choose the zip file you have just downloaded. Click on **install** and **activate**

## Free and Pro side by side

Lazy Blocks Pro is an independent plugin and does not need the free one. Keeping both active is the normal state from free version 4.4.1 onwards. Nothing is switched off, and two entries in the Plugins list mean the setup is correct.

A free copy older than that cannot run next to Pro, because it declares the same core classes a second time. Activating either plugin deactivates the free one and prints a warning on the Plugins screen, once:

  This version of Lazy Blocks is too old to run next to Lazy Blocks Pro. We've
  automatically deactivated Lazy Blocks.

A pre-release of 4.4.1 counts as 4.4.1, so an alpha, a beta or a release candidate of it is new enough. Update the free plugin and activate it again to get both running.

## Activate

To receive automatic updates of the Pro plugin, activate your license:

1. After installing the Lazy Blocks Pro, go to your <a href="https://app.lemonsqueezy.com/my-orders" target="_blank">Lemon Squeezy orders</a>
2. Select the Lazy Blocks Pro order page.
3. Copy the license key

   

4. Head over to your site, to the WordPress dashboard, and click on **Admin Menu → Lazy Blocks → Updates**
5. Insert your license key and push the **Activate License** button

   

If you cannot find the key, the **Where is my license key?** link next to the field opens a page that sends you to the right store for your receipt.

---

# Manage your subscription

Source: https://www.lazyblocks.com/docs/getting-started/manage-your-subscription/

A Lazy Blocks Pro license is a yearly subscription billed through Lemon Squeezy. Everything about it lives in your <a href="https://app.lemonsqueezy.com/my-orders" target="_blank">Lemon Squeezy orders</a>: sign in with the email you bought with, and every order and license key is there. The receipt email links to the same page.

## Renewal

The subscription renews once a year on the date you bought it, on the card or PayPal account you paid with. A license that is not renewed keeps working: the plugin stays active and your blocks keep rendering. What stops is updates and support.

## Cancel

1. Open your <a href="https://app.lemonsqueezy.com/my-orders" target="_blank">Lemon Squeezy orders</a> and sign in with the email you bought with.
2. Select the Lazy Blocks Pro subscription.
3. Cancel it.

The license stays valid until the end of the paid year, and nothing is charged after that. Cancelling does not remove the plugin from your site.

## Refund

The refund policy covers a first purchase for 14 days. Write to us through the [contact page](https://www.lazyblocks.com/contact/) from the email you bought with and name the order. Renewals are not refundable. A refund ends the license, so the plugin has to be removed from the site. The [terms](https://www.lazyblocks.com/terms/#refund-policy) have the detail.

## Change the email on an order

Write to us through the [contact page](https://www.lazyblocks.com/contact/) from the email the order was placed with and give us the new address. We move the order to it. The same goes for passing a license on to somebody else.

## Move the license to another site

Deactivate the plugin on the old site and activate it on the new one. The sites a license is active on are also listed on the order in your Lemon Squeezy orders, where you can remove one.

## Licenses bought through Paddle

If your receipt came from Paddle or nkdev.info, your subscription is managed in the nkdev.info account instead. See [Licenses bought through Paddle](https://www.lazyblocks.com/docs/getting-started/legacy-licenses/).

---

# Licenses bought through Paddle

Source: https://www.lazyblocks.com/docs/getting-started/legacy-licenses/

Before Lazy Blocks Pro moved to Lemon Squeezy, it was sold through Paddle, with customer accounts on nkdev.info. Those subscriptions still renew through Paddle every year. This page applies to you if your receipt came from "Devoice LLC via Paddle" with the Paddle logo at the bottom, or from nkdev.info, whatever the date on it. Your card statement shows these payments as PADDLE.NET\* NKDEV.INFO.

  <figcaption>Example of a Paddle receipt.</figcaption>

If your receipt has the Lemon Squeezy logo, see [Install Pro version](https://www.lazyblocks.com/docs/getting-started/install-pro-version/) instead. Not sure which one you have? [Find your download](https://www.lazyblocks.com/account/) shows both receipts.

## Sign in

Go to <a href="https://nkdev.info/account/" target="_blank">nkdev.info/account</a> and sign in with the email you paid with. If you never set a password, click **Lost Password?** on the sign-in form and set one.

If no account opens under any of your emails, [write to us](https://www.lazyblocks.com/contact/) and list every email you may have paid with. We will find the order.

## Download

In the account, open **Downloads** and download the Lazy Blocks Pro ZIP. Install it as described in [Install Pro version](https://www.lazyblocks.com/docs/getting-started/install-pro-version/#install).

## License key

Open **Licenses** and copy the key. In WordPress, go to **Lazy Blocks → Updates**, paste the key and click **Activate License**.

## Renew

The subscription renews automatically each year through Paddle. If a renewal failed or was cancelled, the reminder email links to a checkout. Without the email, sign in, find the license under **Licenses** and click **Renew Now**.

## Cancel

Open **Subscriptions** to see the renewal date and cancel the subscription. The license stays valid until the end of the paid year. If the subscription shows no cancel option, [write to us](https://www.lazyblocks.com/contact/) and we cancel it.

## Manage sites

Open **Licenses**, then **Manage Sites** on the key, to add or remove the site URLs it is active on. This is where to fix [Download Failed: Unauthorized](https://www.lazyblocks.com/docs/troubleshooting/download-failed-unauthorized/) after a license was activated on a temporary URL.

## Change the email

[Write to us](https://www.lazyblocks.com/contact/) from the email the order was placed with and give us the new address.

---

# Create Block

Source: https://www.lazyblocks.com/docs/create-block/

Lazy Blocks allows you to create custom blocks with HTML or PHP output. You can build blocks for content display or create custom meta fields that can be accessed in your theme code.

## Getting Started

1. Navigate to **WordPress Admin → Lazy Blocks**
2. Click **Add New** button

   

## Setup Wizard

When creating a new block, you'll first see the Setup Wizard screen where you can choose from predefined starter blocks:

- **Basic** - Simple content block with basic controls
- **Hero** - Hero section with background and text controls
- **Testimonials** - Testimonial block with author and quote controls
- **Alert** - Alert/notice block with message and type controls

Each preset comes with its controls, code and styles already filled in.

With Pro active the four presets keep their names and generate different code. Their text controls become [``](https://www.lazyblocks.com/docs/blocks-code/rich-text/) components, so a new block is edited in place on the canvas and comes out looking like the finished section rather than an empty one. Colors, links, images and repeater children keep their inspector controls. The generated CSS goes into the Style editor field, where the free plugin puts an inline `<style>` block in the markup instead.

## Block Builder

After completing the Setup Wizard, you'll see the Block Builder screen where you can customize your block further.

    The block builder screen where you set up your custom block.

### Controls

Configure the options available in your block. Controls determine what users can customize when using your block. [Learn more about controls](https://www.lazyblocks.com/docs/blocks-controls/overview/)

### Block Code

Choose between HTML + [Handlebars](https://handlebarsjs.com/), PHP or Theme Template to determine how your block code displays. [See detailed code documentation](https://www.lazyblocks.com/docs/blocks-code/overview/)

- **block.html** / **block.php** - code that displays in editor and frontend
- **frontend.html** / **frontend.php** - code that displays in frontend only
- **editor.html** / **editor.php** - code that displays in editor only
- **Output Method** - Choose between HTML + Handlebars, PHP or Theme Template

Assets settings:

- **block.css** - styles loaded in the editor and on the front end, on pages where the block is used
- **editor.css** - styles loaded in the editor only
- **view.js** - script loaded on the front end, on pages where the block is used

Additional settings:

- **Unified Block Code** - use a single editor (**block.html** / **block.php**) with code that displays in editor and frontend
- **With Editor Style** - additional CSS enqueued in editor only
- **Code Output in Editor** - Control when the block code appears in editor

### Preview and Code Editors

The **Preview** tab renders the block from the code you are looking at, saved or not, filling each control with its default value rather than with real content.

A block whose **Output Method** is PHP previews only for users allowed to run unfiltered HTML, which on a single site means administrators. Everyone else sees `Not allowed to execute PHP code.` in its place. The preview of any block needs the `edit_lazyblocks` capability, the same one the builder itself takes.

The code editors autocomplete as you type and expand Emmet abbreviations. Typing `$` in a PHP editor offers `$attributes['name']` for every control, `{` in an HTML editor offers `{{name}}`, and the CSS editor offers the block's generated class.

### Block Settings

- **Title** - The block's name in the inserter
- **Collection & Namespace**  - Put the block in a collection and give it your own namespace. [Learn more about collections](https://www.lazyblocks.com/docs/managing-blocks/collections/)
- **Slug** - Unique identifier (lowercase letters, numbers, and dashes only)
- **Description** - Brief explanation shown in the inspector
- **Icon** - Pick from around 900 icons, searchable by name and grouped into 16 categories
- **Category** - Group your block with similar blocks
- **Keywords** - Search terms (max 3) to help users find your block
- **Style Variations** - Alternative visual styles
- **Supports**
  - **Color** - Enable color controls
  - **Typography** - Add typography controls, including text columns and text shadow (text shadow needs WordPress 7.2)
  - **Spacing** - Add spacing (padding/margin) controls
  - **Dimensions** - Enable aspect ratio, minimum height, width and height controls
  - **Border** - Add border color, radius, style and width controls
  - **Background** - Add a background image and its size
  - **Shadow** - Enable shadow controls
  - **Duotone** - Add a duotone filter to the block
  - **Sticky Position** - Let the block stick to the top of the screen while the page scrolls
  - **Layout** - Add layout options
  - **Align** - Add alignment options
  - **Anchor** - Add ID attribute support
  - **Class Name** - Enable custom CSS classes
  - **Multiple** - Allow multiple instances per page
  - **Inserter** - Show in blocks inserter
  - **Reusable** - Allow conversion to reusable block
  - **Lock** - Enable block locking
  - **Interactivity** - Process [Interactivity API](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/) directives in the block output

  Every support is off in a new block. The style supports (Color, Typography, Spacing, Dimensions, Border, Background, Shadow, Duotone and Sticky Position) style the element that carries [useBlockProps](https://www.lazyblocks.com/docs/blocks-code/use-block-props/). When the frontend code has no such element, the builder shows a notice, and the styles go to an extra `<div>` wrapper around your code.
- **Supports Ghost Kit** - Enable [Ghost Kit](https://wordpress.org/plugins/ghostkit/) compatibility
- **Condition** - Restrict block to specific post types. If no post types selected, the block will be shown everywhere
- **Relationships**  - Create connected blocks with advanced settings:
  - **Provide Context to Blocks** - Share current block's attributes with selected child blocks
  - **Ancestor** - Restrict where this block can be inserted (parent block requirements)
  - **Allowed Blocks** - Control which blocks can be inserted as children in ``

---

# Controls

Source: https://www.lazyblocks.com/docs/blocks-controls/overview/

Controls let users customize blocks by managing block attributes in the block editor. Each control handles a different kind of data, from a text input to a file uploader or a repeater. When the block renders, you can access these values to output them in your block.

## Adding Controls

Add controls to your block using the "Add Control" button in the block builder. You can add multiple controls to manage different aspects of your block.

## Control Settings

Each control has a set of common settings that determine how it works and displays:

### Basic Settings

- **Label** (`label`) - the name shown in the block editor
- **Name** (`name`) - unique identifier for reading the control's value in code
- **Type** (`type`) - the kind of control, `text` for a new one
- **Default value** (`default`) - the value a newly inserted block starts with

### Display Settings

- **Placement** (`placement`) - where the control appears, `content` by default, and the other options are Inspector and Both
- **Width** (`width`) - width in the Content area, `100` by default, and the other options are 25, 50 and 75
- **Help text** (`help`) - text shown under the control

### Advanced Settings

- **Required** (`required`) - off by default. Blocks publishing while the control is empty
- **Hide if block is not selected** (`hide_if_not_selected`) - off by default. Shows the control only while the block is selected
- **WPML Translation** (`translate`) - off by default, and offered only on the eight controls that store text. [Learn more here](https://www.lazyblocks.com/docs/multilingual/)
- **Save in Meta** (`save_in_meta`) - off by default. Stores the value in a post meta field instead of on the block
- **Conditional Logic**  (`conditional_logic`) - shows or hides the control by rules on other controls

## Control Placement

Controls can be placed in 2 locations: **Inspector** and **Content** (inside block body). However, **we recommend using the Inspector** for your controls to follow WordPress best practices. Native WordPress blocks use the Inspector panel for all controls, while the Content area is reserved for rendering the actual block output.

When you add controls to the Content area, Lazy Blocks will automatically add a frame border and title to your block to distinguish it from regular content. This visual change helps users understand that the block contains editable controls.

## Inspector Groups

A control placed in the Inspector belongs to one of five groups. The **Group** row is only shown when **Placement** is Inspector or Both, so a control sitting in the Content area has no group at all.

| Group     | Stored value | Where the control appears                        |
| --------- | ------------ | ------------------------------------------------ |
| Settings  | `settings`   | Settings tab                                     |
| Content   | `content`    | Content tab                                      |
| List View | `list`       | List View tab                                    |
| Styles    | `styles`     | Styles tab                                       |
| Advanced  | `advanced`   | Advanced panel at the bottom of the Settings tab |

The first four are WordPress's own inspector tabs, and a tab only appears when a block has something to put in it. A control lands in the same place a core block's control would.

A new control starts in **Settings**. Content and List View were added in 4.3.0.

Controls saved before that store `default`, which the builder reads as `settings`. `Default` is a legacy value, not a label you can pick today.

## Custom Meta Field

Each control has the possibility to save its value in the [custom fields](https://wordpress.org/documentation/article/assign-custom-fields/), so this value will be available in the post meta data and developers may get this value. For example:

```php /get_lzb_meta( 'control_meta_name' )/
<p><?php echo get_lzb_meta( 'control_meta_name' ); ?></p>
```

You should add a **unique** custom field name, as 3rd-party plugins/themes may use the same name and it will be conflicted. For example, if you want to use this block in your theme "My Super Theme", we recommend adding a slug prefix to the name, such as **mst_control_meta_name**.

## Reserved Control Names

These six names are already block attributes. A control given one of them is overwritten, and the block's own value takes its place:

| Name               | Description                                    |
| ------------------ | ---------------------------------------------- |
| `lazyblock`        | internal block data used by Lazy Blocks plugin |
| `className`        | block custom classname                         |
| `align`            | block align, registered by the Align support   |
| `anchor`           | block custom ID                                |
| `blockId`          | block unique ID, generates automatically       |
| `blockUniqueClass` | block unique class, generates automatically    |

Ghost Kit support adds two more, `ghostkitSpacings` and `ghostkitSR`. A [Rich Text](https://www.lazyblocks.com/docs/blocks-code/rich-text/) component named after any of these eight stores nothing, so `` never gets a value.

The builder does not check the list. The Name field rejects characters outside `A-Z a-z 0-9 - _` and nothing more, and even that error leaves the block saveable. Treat the table as advice.

## All Controls

### Basic

      <figcaption>Email</figcaption>

      <figcaption>Number</figcaption>

      <figcaption>Password</figcaption>

      <figcaption>Range</figcaption>

      <figcaption>Text</figcaption>

      <figcaption>Textarea</figcaption>

      <figcaption>URL</figcaption>

### Content

      <figcaption>Classic Editor</figcaption>

      <figcaption>Code Editor</figcaption>

      <figcaption>File</figcaption>

      <figcaption>Gallery</figcaption>

      <figcaption>Image</figcaption>

      <figcaption>Rich Text</figcaption>

### Choice

      <figcaption>Checkbox</figcaption>

      <figcaption>Radio</figcaption>

      <figcaption>Select</figcaption>

      <figcaption>Toggle</figcaption>

      <figcaption>Token Field</figcaption>

### Advanced

      <figcaption>Color Picker</figcaption>

      <figcaption>Date Time Picker</figcaption>

      <figcaption>Posts</figcaption>

      <figcaption>Taxonomy</figcaption>

      <figcaption>Units</figcaption>

      <figcaption>Users</figcaption>

      <figcaption>Link</figcaption>

### Layout

      <figcaption>Divider</figcaption>

      <figcaption>Message</figcaption>

      <figcaption>Panel</figcaption>

      <figcaption>Repeater</figcaption>

---

# Conditional Logic

Source: https://www.lazyblocks.com/docs/blocks-controls/conditional-logic/

Conditional Logic hides a control in the block editor until its rules pass. A block with a Layout select and eight layout-specific options shows two controls instead of nine, and the seven that do not apply are out of the way rather than greyed out.

Rules are set per control. Open the control in the block builder, find **Conditional Logic** in its settings, and add a rule.

## What a rule can test

A rule has three parts: what to look at, an operator, and a value to compare against.

The first dropdown lists every control on the block under a **Controls** heading, and two more sources under **Other**:

| Source | What it reads |
| ------ | ------------- |
| any control | that control's stored value |
| `CSS Class Name` | the block's `className` attribute, which holds whatever a user typed in the Advanced panel |
| `Block Styles` | the applied style variation, matched through `className` |

**Block Styles** is greyed out until the block has at least one style variation.

A control inside a Repeater appears in the list under its parent, and stores its target as `parent-name.child-name`.

## Operators

Nine operators exist. Which ones the second dropdown offers depends on the control type, because most of them only make sense for some kinds of value.

| Label | Stored value | Offered for |
| ----- | ------------ | ----------- |
| `Has any value` | `!=empty` | every control except Checkbox, Toggle, Inner Blocks and Message, plus both `Other` sources |
| `Has no value` | `==empty` | the same list |
| `Is equal to` | `==` | Text, Textarea, Number, Range, URL, Email, Password, Rich Text, Classic Editor, Code Editor, Select, Radio, Color Picker, Date Time Picker, Units, Checkbox, Toggle |
| `Is not equal to` | `!=` | the same list |
| `Contains` | `==contains` | the `Is equal to` list minus Checkbox and Toggle, plus `CSS Class Name` |
| `Is greater than` | `>` | Number, Range, Gallery, Posts, Taxonomy, Users, Repeater |
| `Is less than` | `<` | the same list |
| `Has class` | `==class` | `CSS Class Name` |
| `Has no class` | `!=class` | `CSS Class Name` |

On **Block Styles** the last two are labelled `Has style` and `Has no style`.

Two control types behave differently from the rest. Checkbox and Toggle are not offered the empty operators at all, and their value field is locked to a single option, `Checked`. **Inner Blocks** has a name so it appears in the list, but no operator applies to it, so its operator dropdown comes up empty.

The value field changes with the source. Select and Radio give you a dropdown of their own choices, Block Styles gives you a dropdown of the block's style variations, and everything else is a text field.

### A count, not a value

For Gallery, Repeater, Posts, Taxonomy and Users, `Is greater than` and `Is less than` compare the **number of items**, not the value. "Is greater than 2" on a Gallery control means the block has three images or more. On a Repeater it means three rows or more.

The same conversion makes the empty operators work on these controls: an empty gallery counts as no value, so `Has no value` passes.

Posts, Taxonomy and Users only hold a list when their **Multiple** setting is on. With Multiple off they hold a single value, and the range operators compare that value as a number instead of counting it.

## Rules, and groups of rules

Inside a group, **and** joins the rules. Every rule in the group has to pass.

Between groups, **or** joins them. The control is shown when any one group passes in full.

So this pair of groups:

```
Group 1   layout        Is equal to        grid
          images        Is greater than    2

or

Group 2   Block Styles  Has style          outline
```

shows the control on a grid layout with more than two images, or on any block using the `outline` style.

Add a rule to the current group with the **and** button. Add a whole new group with **Add Rule Group**.

## Matching a style or a class

`Has class` matches a whole class name, not a fragment. A rule of `Has class` and `card` passes for `card wide` and fails for `card-wide`. Use `Contains` when you want a fragment.

**Block Styles** stores the style's name and matches the class Gutenberg generates from it. A variation named `outline` is stored as `outline` and matched against `is-style-outline`, so you pick the name from the dropdown and never type the class yourself.

A block that has never had a class or a style applied has no `className` attribute at all, and a rule against it is skipped rather than passed or failed.

## What it does not do

Conditional Logic is an editor feature and nothing more. It decides whether a control is drawn in the inspector or in the block body. It does not touch the stored value and it does not touch the rendered block.

Three consequences follow, and all three surprise people:

- **A hidden control keeps its value.** Hide a control after someone filled it in and the value is still on the block, still passed to your block code, and still printed on the front end.
- **Your template has to repeat the condition.** If the output should disappear along with the control, guard it in Handlebars with `{{#if}}` or in PHP with an `if` of your own.
- **A required control that is hidden still blocks saving.** The save lock checks every control on the block without consulting its rules, so a required control hidden by conditional logic locks the post with no visible field to fix. Do not mark a conditional control as required.

## Where the rules are stored

The rules live on the control itself, under `conditional_logic`, as an array of groups where each group is an array of rules. Exporting a block carries them along.

```json title="Block JSON"
"control_a1b2c3": {
  "type": "number",
  "name": "columns",
  "label": "Columns",
  "placement": "inspector",
  "conditional_logic": [
    [
      { "control": "layout", "operator": "==", "value": "grid" },
      { "control": "images", "operator": ">", "value": "2" }
    ],
    [
      { "control": "__BLOCK_STYLE__", "operator": "==class", "value": "outline" }
    ]
  ]
}
```

`value` is always a string, even for the numeric comparisons, and it is absent on a rule using one of the empty operators. `__BLOCK_STYLE__` is how Block Styles is stored; `CSS Class Name` is stored as `className`.

A rule that targets a Repeater child from outside the Repeater reads the first row only. Rules on controls inside the Repeater are evaluated per row, so each row shows and hides its own controls independently.

---

# Email

Source: https://www.lazyblocks.com/docs/blocks-controls/email/

Email control allows you to add and validate email addresses in your blocks.

## Control Settings

- **Placeholder** (`placeholder`) - text displayed when the value is empty. Empty by default
- **Characters Limit** (`characters_limit`) - the `maxlength` put on the input, from 0 to 524288. Empty by default, which is no limit

## Usage

```php title="PHP" /$attributes['control_name']/
<p>
  <a href="mailto:<?php echo esc_attr( $attributes['control_name'] ); ?>">
    Contact us
  </a>
</p>
```

```hbs title="Handlebars" /{{control_name}}/
<p>
  <a href="mailto:{{control_name}}">
    Contact us
  </a>
</p>
```

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<p>
  <a href="mailto:<?php echo esc_attr( get_lzb_meta( 'control_meta_name' ) ); ?>">
    Contact us
  </a>
</p>
```

---

# Number

Source: https://www.lazyblocks.com/docs/blocks-controls/number/

Number control allows you to add numeric input fields with optional minimum, maximum, and step values.

## Control Settings

- **Minimum Value** (`min`) - lowest number the field accepts
- **Maximum Value** (`max`) - highest number the field accepts
- **Step Size** (`step`) - how far one press of an arrow moves the value
- **Placeholder** (`placeholder`) - text shown while the field is empty

All four are empty by default. With no Minimum and no Maximum the field takes any number, and with no Step Size the arrows move in whole numbers. Enter `0.5` or `0.01` to step in fractions. The Minimum Value and Maximum Value fields in the block builder carry the same step, so a fractional bound needs a fractional Step Size first.

## Usage

```php title="PHP" /$attributes['control_name']/
<div class="price">
  <?php echo esc_html( $attributes['control_name'] ); ?>
</div>
```

```hbs title="Handlebars" /{{control_name}}/
<div class="price">
  {{control_name}}
</div>
```

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<div class="price">
  <?php echo esc_html( get_lzb_meta( 'control_meta_name' ) ); ?>
</div>
```

Use control settings to create proper value constraints for better user experience (e.g., price range from 0 to 1000 with steps of 0.5).

---

# Password

Source: https://www.lazyblocks.com/docs/blocks-controls/password/

Password control provides a masked input field for entering sensitive text. The control uses the standard HTML password input type.

This control only masks the input in the editor using `<input type="password" />`. It does not encrypt or provide additional security for the stored value.

## Control Settings

- **Placeholder** (`placeholder`) - text shown when no value is entered. Empty by default
- **Characters Limit** (`characters_limit`) - the `maxlength` put on the input, from 0 to 524288. Empty by default, which is no limit

## Usage

```php title="PHP" /$attributes['control_name']/
<div>
  <?php echo esc_html( $attributes['control_name'] ); ?>
</div>
```

```hbs title="Handlebars" /{{control_name}}/
<div>
  {{control_name}}
</div>
```

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<div>
  <?php echo esc_html( get_lzb_meta( 'control_meta_name' ) ); ?>
</div>
```

Consider using WordPress core functions like `wp_hash_password()` if you need to store passwords securely.

---

# Range

Source: https://www.lazyblocks.com/docs/blocks-controls/range/

Range control provides a slider for selecting numeric values within a defined range. Perfect for settings like opacity, columns count, or padding.

## Control Settings

- **Minimum Value** (`min`) - left end of the slider
- **Maximum Value** (`max`) - right end of the slider
- **Step Size** (`step`) - distance between two slider stops

All three are empty by default. An empty end leaves the slider with no limit there, and an empty Step Size moves it in whole numbers. The Minimum Value and Maximum Value fields in the block builder carry the Step Size as their own step, so set it first when the ends are fractional.

## Usage

```php title="PHP" /$attributes['control_name']/
<div style="opacity: <?php echo esc_attr( $attributes['control_name'] / 100 ); ?>">
  Content with opacity
</div>
```

```hbs title="Handlebars" /{{control_name}}/
<div style="opacity: calc({{control_name}} / 100)">
  Content with opacity
</div>
```

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<?php
$value = get_lzb_meta( 'control_meta_name' );
?>
<div class="columns-<?php echo esc_attr( $value ); ?>">
  Content with columns
</div>
```

Common uses for Range control:
- Opacity (0-100)
- Number of columns (1-6)
- Spacing values (0-100)
- Font size (12-72)

---

# Text

Source: https://www.lazyblocks.com/docs/blocks-controls/text/

Text control provides a simple input field for single-line text content. It's perfect for headings, titles, or any short text input.

## Control Settings

- **Placeholder** (`placeholder`) - text shown when the field is empty. Empty by default
- **Characters Limit** (`characters_limit`) - the `maxlength` put on the input, from 0 to 524288. Empty by default, which is no limit

## Usage Examples

### Basic Output

```php title="PHP" /$attributes['control_name']/
<h2 class="title">
    <?php echo esc_html( $attributes['control_name'] ); ?>
</h2>
```

```hbs title="Handlebars" /{{control_name}}/
<h2 class="title">
  {{control_name}}
</h2>
```

### With HTML Attributes

```php title="PHP" /$attributes['control_name']/
<a href="#" title="<?php echo esc_attr( $attributes['control_name'] ); ?>">
    Link with title
</a>
```

### Post Meta

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<?php
$text = get_lzb_meta( 'control_meta_name' );
if ( $text ) {
    echo '<h2 class="title">' . esc_html( $text ) . '</h2>';
}
?>
```

Always use proper escaping functions:
- `esc_html()` for regular text output
- `esc_attr()` for HTML attributes

---

# Textarea

Source: https://www.lazyblocks.com/docs/blocks-controls/textarea/

Textarea control provides a multi-line text input field, perfect for longer content like descriptions, excerpts, or any text that needs multiple paragraphs.

## Control Settings

- **Placeholder** (`placeholder`) - text shown when the field is empty. Empty by default
- **Characters Limit** (`characters_limit`) - the `maxlength` put on the textarea, from 0 to 524288. Empty by default, which is no limit

## Usage Examples

### Basic Output

```php title="PHP" /$attributes['control_name']/
<div class="description">
    <?php echo wp_kses_post( nl2br( $attributes['control_name'] ) ); ?>
</div>
```

```hbs title="Handlebars" /{{control_name}}/
<div class="description">
  {{control_name}}
</div>
```

### Post Meta

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<?php
$text = get_lzb_meta( 'control_meta_name' );
if ( $text ) {
    echo '<div class="description">';
    echo wp_kses_post( nl2br( $text ) );
    echo '</div>';
}
?>
```

Use `nl2br()` to convert line breaks to `<br>` tags, or `wpautop()` to convert them to paragraphs.

---

# URL

Source: https://www.lazyblocks.com/docs/blocks-controls/url/

Need more link options like title, target, nofollow, or CSS classes? Check out the [Link control](https://www.lazyblocks.com/docs/blocks-controls/link/) available in the Pro version.

URL control provides a link input field with post/page search functionality. Users can enter custom URLs or search and select from existing WordPress content.

The control supports searching through your site's content - just start typing the post or page name:

## Control Settings 

Pro adds one panel of three settings to the control.

- **Link Suggestions** (`link_suggestions`) - `Automatic` by default, which searches every viewable post type. `Disable suggestions` turns the search off, and picking one post type limits the search to it
- **Show Initial Suggestions** (`show_initial_link_suggestions`) - off by default. Lists suggestions before anything is typed, and the row is hidden while Link Suggestions is `Disable suggestions`
- **Rich Preview** (`rich_preview`) - off by default. Shows the target's site title and image inside the field

## Usage Examples

### Basic Link

```php title="PHP" /$attributes['control_name']/
<?php if ( $attributes['control_name'] ) : ?>
    <a href="<?php echo esc_url( $attributes['control_name'] ); ?>"
       class="button">
        Visit Link
    </a>
<?php endif; ?>
```

```hbs title="Handlebars" /control_name/
{{#if control_name}}
  <a href="{{control_name}}" class="button">
    Visit Link
  </a>
{{/if}}
```

### Link with Custom Text

```php title="PHP" /$attributes['control_name']/
<?php
$url = $attributes['control_name'];
if ( $url ) : ?>
    <div class="cta-button">
        <a href="<?php echo esc_url( $url ); ?>"
           class="button"
           target="_blank"
           rel="noopener noreferrer">
            Learn More
        </a>
    </div>
<?php endif; ?>
```

### Post Meta

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<?php
$url = get_lzb_meta( 'control_meta_name' );
if ( $url ) {
    echo '<div class="link-wrapper">';
    printf(
        '<a href="%1$s" class="button">%2$s</a>',
        esc_url( $url ),
        esc_html__( 'Read More', 'your-text-domain' )
    );
    echo '</div>';
}
?>
```

- Always use `esc_url()` when outputting URLs to prevent XSS attacks.
- Consider adding `target="_blank"` and `rel="noopener noreferrer"` for external links.

---

# Classic Editor (WYSIWYG)

Source: https://www.lazyblocks.com/docs/blocks-controls/classic-editor-wysiwyg/

Classic Editor control provides a familiar WYSIWYG editing experience within your blocks.

## Control Settings

The control adds no settings of its own, so the block builder shows only the [rows every control has](https://www.lazyblocks.com/docs/blocks-controls/overview/). **WPML Translation** is among them, which is not true of most controls.

## Usage

```php title="PHP" /$attributes['control_name']/
<div>
  <?php echo $attributes['control_name']; ?>
</div>
```

```hbs title="Handlebars" /{{{control_name}}}/
<div>
  {{{control_name}}}
</div>
```

When outputting HTML in Handlebars, use triple curly brackets: `{{{` and `}}}`

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<div>
  <?php echo get_lzb_meta( 'control_meta_name' ); ?>
</div>
```

---

# Code Editor

Source: https://www.lazyblocks.com/docs/blocks-controls/code-editor/

Code editor control lets you add and edit code snippets with syntax highlighting support.

## Control Settings

- **Language**  (`language`) - the syntax to highlight, picked from a fixed list of 36 that runs from Arduino to YAML

No language is picked to start with, and the editor highlights nothing until you pick one. The setting changes the editor alone, so the front end gets the text exactly as it was typed whichever language is set. Without Pro the control is a plain textarea with no highlighting and no Language row.

## Usage

```php title="PHP" /$attributes['control_name']/
<div>
  <?php echo $attributes['control_name']; ?>
</div>
```

```php title="PHP Preformatted" /$attributes['control_name']/
<pre>
  <?php echo esc_html( $attributes['control_name'] ); ?>
</pre>
```

```hbs title="Handlebars" /{{{control_name}}}/
<div>
  {{{control_name}}}
</div>
```

```hbs title="Handlebars Preformatted" /{{control_name}}/
<pre>
  {{control_name}}
</pre>
```

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<div>
  <?php echo get_lzb_meta( 'control_meta_name' ); ?>
</div>
```

The value is stored and returned as plain text, so print it through `esc_html()` inside a `<pre>` when you want the code shown rather than run by the browser.

---

# File

Source: https://www.lazyblocks.com/docs/blocks-controls/file/

File control lets you upload and select files using the WordPress Media Library. The control stores file information as an array.

## Control Settings

- **Allowed Mime Types** (`allowed_mime_types`) - the file types the media picker accepts. Empty by default, and an empty list allows every type WordPress allows

The field is a multi-select over the file types WordPress allows uploading, so the choices are extension groups such as `jpg|jpeg|jpe`, `png` and `mp4|m4v` rather than free text.

## Saved Data

The control saves the following file information:

| Name      | Description                                 |
| --------- | ------------------------------------------- |
| `id`      | Unique ID of uploaded file                  |
| `url`     | URL to access the file                      |
| `alt`     | Optional alt attribute used in `<img>` tags |
| `title`   | Attachment title                            |
| `caption` | Optional caption                            |
| `link`    | Link to file                                |

## Usage

```php title="PHP" /$attributes['control_name']['url']/
<audio src="<?php echo esc_url( $attributes['control_name']['url'] ); ?>" controls>
</audio>
```

```hbs title="Handlebars" /{{control_name.url}}/
<audio src="{{control_name.url}}" controls>
</audio>
```

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<?php
$file = get_lzb_meta( 'control_meta_name' );
?>
<audio src="<?php echo esc_url( $file['url'] ); ?>" controls>
</audio>
```

The control uses the native WordPress Media Library for file uploads and selection.

---

# Gallery

Source: https://www.lazyblocks.com/docs/blocks-controls/gallery/

Gallery control allows you to add multiple images to your blocks using the WordPress Media Library. Users can select, reorder, and remove images easily.

## Control Settings

The control has a single panel, **Preview Grid**, with two number inputs. Both take a value from 1 to 20 and both may be left empty:

- **Columns** (`preview_columns`) - tiles per row. Empty fits the grid to the width of the control.
- **Rows** (`preview_rows`) - rows of tiles. Empty falls back to 4.

The grid shows `columns * rows` images at most. When the gallery holds more than that, the last tile becomes a `+N` counter and the grid drops to one image fewer. A gallery that fits the grid exactly gets no counter.

The **Default value** row is hidden for this control.

## Saved Data

The control saves the following information for each image:

| Name          | Description                          |
| ------------- | ------------------------------------ |
| `id`          | Unique ID of uploaded image          |
| `url`         | URL to access the image              |
| `alt`         | Alt text for image accessibility     |
| `title`       | Attachment title                     |
| `caption`     | Optional image caption               |
| `description` | Attachment description               |
| `link`        | Link to original image               |
| `sizes`       | Available image sizes and their URLs |

## Usage

### Basic Image Output

```php title="PHP" /$attributes['control_name']/
<?php foreach( $attributes['control_name'] as $image ): ?>
  <img src="<?php echo esc_url( $image['url'] ); ?>"
       alt="<?php echo esc_attr( $image['alt'] ); ?>">
<?php endforeach; ?>
```

```hbs title="Handlebars" /control_name/
{{#each control_name}}
  <img src="{{url}}" alt="{{alt}}" />
{{/each}}
```

### Using WordPress Image Function

```php title="PHP with wp_get_attachment_image" /$attributes['control_name']/
<?php
foreach( $attributes['control_name'] as $image ) {
  if ( isset( $image['id'] ) ) {
    echo wp_get_attachment_image( $image['id'], 'large' );
  }
}
?>
```

```hbs title="Handlebars with wp_get_attachment_image" /control_name/
{{#each control_name}}
  {{{wp_get_attachment_image this "large"}}}
{{/each}}
```

### Post Meta Usage

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<?php
$gallery = get_lzb_meta( 'control_meta_name' );

foreach ( $gallery as $image ) {
  if ( isset( $image['id'] ) ) {
    echo wp_get_attachment_image( $image['id'], 'large' );
  }
}
?>
```

  Use `wp_get_attachment_image()` to get responsive images and proper HTML
  markup automatically.

---

# Image

Source: https://www.lazyblocks.com/docs/blocks-controls/image/

Image control allows you to add a single image to your blocks using the WordPress Media Library or custom URL.

## Control Settings

- **Allow insert from URL** (`insert_from_url`) - off by default. Turning it on adds an Insert from URL button to the media placeholder
- **Preview Size** (`preview_size`) - registered image size used for the thumbnail inside the editor, `medium` by default

The list holds the image sizes the editor offers, each labelled with its dimensions, as in `Medium (300 × 300)`. Preview Size changes the editor thumbnail only, and the saved `url` is the full file whatever the preview shows.

## Saved Data

The control saves the following image information:

| Name          | Description                          |
| ------------- | ------------------------------------ |
| `id`          | Unique ID of uploaded image          |
| `url`         | URL to access the image              |
| `alt`         | Alt text for image accessibility     |
| `title`       | Attachment title                     |
| `caption`     | Optional image caption               |
| `description` | Attachment description               |
| `link`        | Link to original image               |
| `sizes`       | Available image sizes and their URLs |

Every key except `id` is read back from the media library on each render, so an image renamed or re-captioned in the library outputs its new text without the block being touched. An image inserted from a URL is not an attachment, and it stores `url` on its own.

## Usage

### Basic Image Output

```php title="PHP" /$attributes['control_name']/
<?php if ( isset( $attributes['control_name']['url'] ) ) : ?>
  <img src="<?php echo esc_url( $attributes['control_name']['url'] ); ?>"
       alt="<?php echo esc_attr( $attributes['control_name']['alt'] ); ?>">
<?php endif; ?>
```

```hbs title="Handlebars" /control_name/
<img src="{{control_name.url}}" alt="{{control_name.alt}}" />
```

### Using WordPress Image Function

```php title="PHP with wp_get_attachment_image" /$attributes['control_name']['id']/
<?php
if ( isset( $attributes['control_name']['id'] ) ) {
  echo wp_get_attachment_image( $attributes['control_name']['id'], 'large' );
}
?>
```

```hbs title="Handlebars with wp_get_attachment_image" /control_name/
{{{wp_get_attachment_image control_name "large"}}}
```

### Post Meta Usage

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<?php
$image = get_lzb_meta( 'control_meta_name' );

if ( isset( $image['id'] ) ) {
  echo wp_get_attachment_image( $image['id'], 'large' );
}
?>
```

Use `wp_get_attachment_image()` to get responsive images and proper HTML markup automatically.

---

# Rich Text (WYSIWYG)

Source: https://www.lazyblocks.com/docs/blocks-controls/rich-text-wysiwyg/

Rich Text control provides a native WordPress editor interface for formatted text content. It supports basic text formatting like bold, italic, and links.

## Control Settings

The control adds no settings of its own, so the block builder shows only the [rows every control has](https://www.lazyblocks.com/docs/blocks-controls/overview/). **WPML Translation** is among them, which is not true of most controls.

To edit the value on the canvas instead of in the inspector, point a [Rich Text](https://www.lazyblocks.com/docs/blocks-code/rich-text/) component at the control from your block code. A single-line field comes from `disableLineBreaks` on that component.

## Usage

### Basic Output

```php title="PHP" /$attributes['control_name']/
<div class="content">
  <?php echo wp_kses_post( $attributes['control_name'] ); ?>
</div>
```

```hbs title="Handlebars" /{{{control_name}}}/
<div class="content">
  {{{control_name}}}
</div>
```

### Post Meta

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<div class="content">
  <?php echo wp_kses_post( get_lzb_meta( 'control_meta_name' ) ); ?>
</div>
```

Use `wp_kses_post()` in PHP to safely output HTML content while preventing XSS attacks.

When using Handlebars, use triple curly brackets `{{{` and `}}}` to output HTML content properly.

---

# Checkbox & Toggle

Source: https://www.lazyblocks.com/docs/blocks-controls/checkbox-toggle/

Checkbox and Toggle both store a boolean. Checkbox has a Multiple mode on top of that, which turns it into a group of boxes and stores an array of the ticked choices. Toggle has no such mode.

## Control Settings

### Checkbox

- **Alongside Text** (`alongside_text`) - the label printed beside the box, hidden while Multiple is on
- **Checked by default** (`checked`) - the state a newly inserted block starts in, off by default
- **Multiple** (`multiple`) - off by default. Replaces the single box with one box per choice, hides Alongside Text and the default checkbox, and puts Choices and Output Format in their place
- **Choices** (`choices`) - a `Label` and a `Value` for each box, dragged into order by the handle and added with **+ Add Choice**. With Multiple on and no choices, the control renders nothing in the block editor
- **Output Format** (`output_format`) - what a ticked box contributes to the saved array. `Value` is the default, `Label` stores the label in place of the value, and `Both (Array)` stores the two together

### Toggle

- **Alongside Text** (`alongside_text`) - the label printed beside the toggle
- **Checked** (`checked`) - the state a newly inserted block starts in, off by default

Toggle has those two settings and nothing else. There is no Multiple, no Choices and no Output Format, so a group of options needs the Checkbox control, [Select](https://www.lazyblocks.com/docs/blocks-controls/select/) or [Radio](https://www.lazyblocks.com/docs/blocks-controls/radio/).

## Usage

### Single Checkbox/Toggle

```php title="PHP" /$attributes['control_name']/
<?php if ( $attributes['control_name'] ) : ?>
  <p>The value is True</p>
<?php else: ?>
  <p>The value is False</p>
<?php endif; ?>
```

```hbs title="Handlebars" /{{#if control_name}}/
{{#if control_name}}
  <p>The value is True</p>
{{else}}
  <p>The value is False</p>
{{/if}}
```

### Multiple Checkboxes

```php title="PHP with Value format" /$attributes['control_name']/
<?php
// Returns array of selected values
foreach ( $attributes['control_name'] as $value ) {
    echo '<p>' . esc_html( $value ) . '</p>';
}
?>
```

```php title="PHP with Label format" /$attributes['control_name']/
<?php
// Returns array of selected labels
foreach ( $attributes['control_name'] as $label ) {
    echo '<p>' . esc_html( $label ) . '</p>';
}
?>
```

```php title="PHP with Both format" /$attributes['control_name']/
<?php
// Returns array of arrays with value and label
foreach ( $attributes['control_name'] as $choice ) {
    echo '<p>Value: ' . esc_html( $choice['value'] ) . '</p>';
    echo '<p>Label: ' . esc_html( $choice['label'] ) . '</p>';
}
?>
```

```hbs title="Handlebars with Value format" /control_name/
{{#each control_name}}
  <p>{{this}}</p>
{{/each}}
```

```hbs title="Handlebars with Label format" /control_name/
{{#each control_name}}
  <p>{{this}}</p>
{{/each}}
```

```hbs title="Handlebars with Both format" /control_name/
{{#each control_name}}
  <p>Value: {{this.value}}</p>
  <p>Label: {{this.label}}</p>
{{/each}}
```

### Post Meta

```php title="Single Checkbox" /get_lzb_meta( 'control_meta_name' )/
<?php if ( get_lzb_meta( 'control_meta_name' ) ) : ?>
  <p>The value is True</p>
<?php else: ?>
  <p>The value is False</p>
<?php endif; ?>
```

```php title="Multiple Checkboxes" /get_lzb_meta( 'control_meta_name' )/
<?php
$selected_choices = get_lzb_meta( 'control_meta_name' );

// Output depends on selected Output Format
foreach ( $selected_choices as $choice ) {
    echo '<p>' . esc_html( $choice ) . '</p>';
}
?>
```

With Multiple on, the Checkbox control returns an array of the ticked choices. The format of the array items depends on the Output Format setting.

---

# Radio

Source: https://www.lazyblocks.com/docs/blocks-controls/radio/

Radio control lets you add a set of options where users can select one choice. Each option can have a label for display and a value for storing.

## Control Settings

- **Choices** (`choices`) - a `Label` and a `Value` for each option, added with **+ Add Choice**. Empty by default
- **Allow Null** (`allow_null`) - off by default. On, a required Radio accepts an empty value. It adds no clear option to the buttons themselves, unlike [Select](https://www.lazyblocks.com/docs/blocks-controls/select/), which gains a `-- Select --` entry
- **Output Format** (`output_format`) - `Value` by default:
  - `Value` - Returns option value
  - `Label` - Returns option label
  - `Both (Array)` - Returns both value and label

To add options, fill the Choices setting:

## Usage

### Basic Usage

```php title="PHP" /$attributes['control_name']/
<div class="option">
  <?php echo esc_html( $attributes['control_name'] ); ?>
</div>
```

```hbs title="Handlebars" /{{control_name}}/
<div class="option">
  {{control_name}}
</div>
```

### With Array Output Format

```php title="PHP" /$attributes['control_name']/
<?php if ( $attributes['control_name'] ) : ?>
  <div class="option">
    <span class="label"><?php echo esc_html( $attributes['control_name']['label'] ); ?></span>
    <span class="value"><?php echo esc_html( $attributes['control_name']['value'] ); ?></span>
  </div>
<?php endif; ?>
```

```hbs title="Handlebars" /control_name/
<div class="option">
  <span class="label">{{control_name.label}}</span>
  <span class="value">{{control_name.value}}</span>
</div>
```

### Post Meta

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<div class="option">
  <?php echo esc_html( get_lzb_meta( 'control_meta_name' ) ); ?>
</div>
```

Use meaningful values in your choices that can be used as CSS classes or for conditional logic.

---

# Select

Source: https://www.lazyblocks.com/docs/blocks-controls/select/

Select control provides a dropdown menu with customizable options. It supports both single and multiple selections with flexible output formats.

## Control Settings

- **Choices** (`choices`) - a `Label` and a `Value` for each option, added with **+ Add Choice**. Empty by default
- **Allow Null** (`allow_null`) - off by default. On, a `-- Select --` option with an empty value is put at the top of the list, and a required Select accepts that empty value
- **Multiple** (`multiple`) - off by default. On, the dropdown accepts several options and the control stores an array
- **Output Format** (`output_format`) - `Value` by default:
  - `Value` - Returns option value
  - `Label` - Returns option label
  - `Both (Array)` - Returns both value and label

To add options, fill the Choices setting:

## Usage Examples

### Single Selection

```php title="PHP" /$attributes['control_name']/
<div class="layout-<?php echo esc_attr( $attributes['control_name'] ); ?>">
  Content
</div>
```

```hbs title="Handlebars" /{{control_name}}/
<div class="layout-{{control_name}}">
  Content
</div>
```

### Multiple Selection

```php title="PHP" /$attributes['control_name']/
<?php if ( $attributes['control_name'] ) : ?>
  <ul class="features">
    <?php foreach( $attributes['control_name'] as $value ): ?>
      <li class="feature-<?php echo esc_attr( $value ); ?>">
        <?php echo esc_html( $value ); ?>
      </li>
    <?php endforeach; ?>
  </ul>
<?php endif; ?>
```

```hbs title="Handlebars" /control_name/
{{#if control_name}}
  <ul class="features">
    {{#each control_name}}
      <li class="feature-{{this}}">{{this}}</li>
    {{/each}}
  </ul>
{{/if}}
```

### Array Output Format

```php title="PHP" /$attributes['control_name']/
<?php if ( $attributes['control_name'] ) : ?>
  <div class="option-<?php echo esc_attr( $attributes['control_name']['value'] ); ?>">
    <?php echo esc_html( $attributes['control_name']['label'] ); ?>
  </div>
<?php endif; ?>
```

```hbs title="Handlebars" /control_name/
{{#if control_name}}
  <div class="option-{{control_name.value}}">
    {{control_name.label}}
  </div>
{{/if}}
```

### Post Meta

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<?php
$value = get_lzb_meta( 'control_meta_name' );
if ( $value ) {
    echo '<div class="option-' . esc_attr( $value ) . '">';
    echo esc_html( $value );
    echo '</div>';
}
?>
```

Use meaningful values that can work as CSS classes or conditional identifiers. For example: 'grid-layout', 'list-layout'.

---

# Token Field

Source: https://www.lazyblocks.com/docs/blocks-controls/token-field/

Token Field control provides a tag-style input for selecting multiple values from predefined choices. Users can type to search and select options, which appear as removable tokens/tags.

## Control Settings

- **Choices** (`choices`) - a `Label` and a `Value` for each option, added with **+ Add Choice**. Empty by default
- **Allow Custom Values** (`allow_custom`) - off by default. On, a value typed into the field is kept even when no choice matches it
- **Multiple** (`multiple`) - on by default. Allows selecting more than one value
- **Output Format** (`output_format`) - `Value` by default:
  - `Value` - Returns option value
  - `Label` - Returns option label
  - `Both (Array)` - Returns object with both value and label

To add options, fill the Choices setting the same way as Select or Radio controls:

## Usage Examples

### Multiple Selection (Default)

```php title="PHP" /$attributes['control_name']/
<?php if ( $attributes['control_name'] ) : ?>
    <ul class="tags-list">
        <?php foreach ( $attributes['control_name'] as $value ) : ?>
            <li class="tag tag-<?php echo esc_attr( $value ); ?>">
                <?php echo esc_html( $value ); ?>
            </li>
        <?php endforeach; ?>
    </ul>
<?php endif; ?>
```

```hbs title="Handlebars" /control_name/
{{#if control_name}}
  <ul class="tags-list">
    {{#each control_name}}
      <li class="tag tag-{{this}}">{{this}}</li>
    {{/each}}
  </ul>
{{/if}}
```

### Single Selection

When Multiple is disabled, the control returns a single value:

```php title="PHP" /$attributes['control_name']/
<?php if ( $attributes['control_name'] ) : ?>
    <span class="selected-tag">
        <?php echo esc_html( $attributes['control_name'] ); ?>
    </span>
<?php endif; ?>
```

```hbs title="Handlebars" /control_name/
{{#if control_name}}
  <span class="selected-tag">{{control_name}}</span>
{{/if}}
```

### Label Output Format

```php title="PHP" /$attributes['control_name']/
<?php if ( $attributes['control_name'] ) : ?>
    <div class="selected-labels">
        <?php foreach ( $attributes['control_name'] as $label ) : ?>
            <span class="label"><?php echo esc_html( $label ); ?></span>
        <?php endforeach; ?>
    </div>
<?php endif; ?>
```

### Array Output Format

When using "Both (Array)" format, each item contains both value and label:

```php title="PHP" /$attributes['control_name']/
<?php if ( $attributes['control_name'] ) : ?>
    <ul class="features-list">
        <?php foreach ( $attributes['control_name'] as $item ) : ?>
            <li class="feature-<?php echo esc_attr( $item['value'] ); ?>">
                <?php echo esc_html( $item['label'] ); ?>
            </li>
        <?php endforeach; ?>
    </ul>
<?php endif; ?>
```

```hbs title="Handlebars" /control_name/
{{#if control_name}}
  <ul class="features-list">
    {{#each control_name}}
      <li class="feature-{{this.value}}">
        {{this.label}}
      </li>
    {{/each}}
  </ul>
{{/if}}
```

### Post Meta

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<?php
$values = get_lzb_meta( 'control_meta_name' );
if ( $values && is_array( $values ) ) {
    echo '<div class="meta-tags">';
    foreach ( $values as $value ) {
        printf(
            '<span class="meta-tag">%s</span>',
            esc_html( $value )
        );
    }
    echo '</div>';
}
?>
```

---

# Color Picker

Source: https://www.lazyblocks.com/docs/blocks-controls/color-picker/

Color picker control lets users select colors from a predefined palette or choose custom colors with optional opacity.

## Control Settings

- **Alongside Text** (`alongside_text`) - text printed beside the color indicator. Empty by default
- **Alpha Channel** (`alpha`) - off by default. On, the picker adds an opacity slider and stores rgba values
- **Color Palette** (`palette`) - on by default. Shows the theme's own color palette above the picker. Off, the picker offers no swatches
- **Output Format** (`output_format`) - `Color` by default, which stores the color on its own. `Array (Color + Slug)` stores the color together with the palette slug

## Usage

```php title="PHP" /$attributes['control_name']/
<p style="color: <?php echo esc_attr( $attributes['control_name'] ); ?>">
  Text with custom color using inline css.
</p>
```

```php title="PHP with Output Format as Array" /$attributes['control_name']['color']/ /$attributes['control_name']['slug']/
<p style="color: <?php echo esc_attr( $attributes['control_name']['color'] ); ?>">
  Text with custom color using inline css.
</p>

<p class="color-<?php echo esc_attr( $attributes['control_name']['slug'] ); ?>">
  Text with custom color using classname.
</p>
```

```hbs title="Handlebars" /{{control_name}}/
<p style="color: {{control_name}}">
  {{text}}
</p>
```

```hbs title="Handlebars with Output Format as Array" /{{control_name.color}}/ /{{control_name.slug}}/
<p style="color: {{control_name.color}}">
  {{text}}
</p>
<p class="color-{{control_name.slug}}">
  {{text}}
</p>
```

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<p style="color: <?php echo esc_attr( get_lzb_meta( 'control_meta_name' ) ); ?>">
  Text with custom color.
</p>
```

---

# Date Time Picker

Source: https://www.lazyblocks.com/docs/blocks-controls/date-time-picker/

Date Time Picker control allows users to select date and/or time values. One setting decides whether the control shows a calendar, a clock, or both.

## Control Settings

The control has one setting, `date_time_picker`, a group of three buttons that defaults to `date_time`:

- **Date** (`date`) - a calendar
- **Date & Time** (`date_time`) - a calendar and a clock
- **Time** (`time`) - a clock

While the value is empty the control shows a button reading `Select Date`, `Select Date and Time` or `Select Time`. Once a value is set, the button prints it in the site's own date, time or date and time format. A **Reset** button appears under the picker and clears the value.

The control saves date in `YYYY-MM-DDTHH:ii:ss` format regardless of the display format.

## Usage Examples

### PHP

```php title="PHP" /$attributes['control_name']/
<?php
$date = $attributes['control_name'];

// Date + Time format
echo '<p>' . date_i18n( 'F j, Y H:i', strtotime( $date ) ) . '</p>';

// Date only format
echo '<p>' . date_i18n( 'F j, Y', strtotime( $date ) ) . '</p>';

// Time only format
echo '<p>' . date_i18n( 'H:i', strtotime( $date ) ) . '</p>';
```

### Handlebars

```hbs title="Handlebars" /control_name/
{{! Date + Time format }}
<p>
  {{date_i18n "F j, Y H:i" control_name}}
</p>

{{! Date only format }}
<p>
  {{date_i18n "F j, Y" control_name}}
</p>

{{! Time only format }}
<p>
  {{date_i18n "H:i" control_name}}
</p>
```

### Post Meta

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<?php
$date = get_lzb_meta( 'control_meta_name' );

// Date + Time format
echo '<p>' . date_i18n( 'F j, Y H:i', strtotime( $date ) ) . '</p>';

// Date only format
echo '<p>' . date_i18n( 'F j, Y', strtotime( $date ) ) . '</p>';

// Time only format
echo '<p>' . date_i18n( 'H:i', strtotime( $date ) ) . '</p>';
```

## Common Format Patterns

| Format       | Output              | Description        |
| ------------ | ------------------- | ------------------ |
| `F j, Y H:i` | March 1, 2024 13:45 | Full date and time |
| `F j, Y`     | March 1, 2024       | Full date          |
| `m/d/Y`      | 03/01/2024          | Short date         |
| `H:i`        | 13:45               | 24-hour time       |
| `g:i a`      | 1:45 pm             | 12-hour time       |

Use WordPress `date_i18n()` function to ensure proper date localization in your output.

---

# Posts

Source: https://www.lazyblocks.com/docs/blocks-controls/posts/

Posts control lets you search and select WordPress posts, pages, or custom post types in your blocks.

## Control Settings

- **Filter by Post Type** (`posts_post_type`) - limit the search to specific post types. Empty by default, which searches every type
- **Filter by Post Status** (`posts_post_status`) - limit the search to specific post statuses. Empty by default, which searches every status
- **Filter by Taxonomy** (`posts_taxonomy`) - limit the search to posts in specific taxonomy terms, stored as `taxonomy:term-slug`. Empty by default
- **Output Format** (`posts_output_format`) - `Post ID` by default. `Post Object` hands the block a WP_Post instead
- **Multiple** (`multiple`) - off by default. On, the control accepts several posts and stores an array

## Usage

### Single Post Selection

```php title="PHP with Post ID" /$attributes['control_name']/
<?php
$selected_post = get_post((int) $attributes['control_name']);
if ($selected_post) {
    echo '<h2>' . esc_html($selected_post->post_title) . '</h2>';
}
?>
```

```php title="PHP with Post Object" /$attributes['control_name']/
<?php if ($attributes['control_name']) : ?>
    <h2><?php echo esc_html($attributes['control_name']->post_title); ?></h2>
    <div><?php echo esc_html($attributes['control_name']->post_type); ?></div>
<?php endif; ?>
```

### Multiple Posts Selection

```php title="PHP with Post IDs" /$attributes['control_name']/
<?php
foreach ($attributes['control_name'] as $post_id) {
    $post = get_post((int) $post_id);
    if ($post) {
        echo '<h2>' . esc_html($post->post_title) . '</h2>';
    }
}
?>
```

### Handlebars Usage

Set Output Format to `Post Object` when using Handlebars templates.

```hbs title="Single Post" /{{control_name.post_title}}/
<h2>{{control_name.post_title}}</h2>
```

```hbs title="Multiple Posts" /control_name/
{{#each control_name}}
  <h2>{{this.post_title}}</h2>
{{/each}}
```

### Post Meta

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<?php
$post_id = get_lzb_meta('control_meta_name');
$post = get_post((int) $post_id);
if ($post) {
    echo '<h2>' . esc_html($post->post_title) . '</h2>';
}
?>
```

The block stores post IDs either way. `Post Object` runs the `get_posts()` call for you as the block renders, so your template reaches `post_title` without making the query itself.

---

# Taxonomy

Source: https://www.lazyblocks.com/docs/blocks-controls/taxonomy/

Taxonomy control lets you search and select terms from any WordPress taxonomy (categories, tags, or custom taxonomies).

Only taxonomies registered with `show_in_rest => true` will appear in the control. If your custom taxonomy is not showing up, add this parameter:

```php
register_taxonomy('your_taxonomy', 'post', [
    // ... other parameters
    'show_in_rest' => true,
]);
```

## Control Settings

- **Taxonomy** (`taxonomy`) - where the terms come from, `category` by default. The list holds every taxonomy the REST API exposes
- **Appearance** (`taxonomy_appearance`) - `Select` by default, a searchable dropdown. `Radio` puts one input per term on screen and is labelled `Checkbox` while Multiple is on. `Token Field` takes terms as removable tokens
- **Output Format** (`taxonomy_output_format`) - what the control stores. `Term Slug` by default, or `Term ID`, or `Term Object`, which stores the ID and turns it into a `WP_Term` when the block renders
- **Multiple** (`multiple`) - off by default. Stores an array of terms instead of one

Output Format decides what is written into the block, not how an existing value is read, so blocks saved before you switch from `Term Slug` to `Term ID` keep their slugs until the term is picked again.

## Usage Examples

### Basic Usage (Term Slug)

```php title="PHP" /$attributes['control_name']/
<?php
$term = get_term_by('slug', $attributes['control_name'], 'category');
if ($term && !is_wp_error($term)) {
    echo '<span class="term">' . esc_html($term->name) . '</span>';
}
?>
```

### Multiple Terms

```php title="PHP" /$attributes['control_name']/
<?php if ($attributes['control_name']) : ?>
    <ul class="terms-list">
        <?php foreach($attributes['control_name'] as $term_slug) :
            $term = get_term_by('slug', $term_slug, 'category');
            if ($term && !is_wp_error($term)) : ?>
                <li class="term-<?php echo esc_attr($term->slug); ?>">
                    <?php echo esc_html($term->name); ?>
                </li>
            <?php endif;
        endforeach; ?>
    </ul>
<?php endif; ?>
```

### Using Term Object

```php title="PHP" /$attributes['control_name']/
<?php if ($attributes['control_name']) : ?>
    <div class="term-<?php echo esc_attr($attributes['control_name']->slug); ?>">
        <h4><?php echo esc_html($attributes['control_name']->name); ?></h4>
        <p><?php echo esc_html($attributes['control_name']->description); ?></p>
    </div>
<?php endif; ?>
```

### Handlebars Usage

Set Output Format to `Term Object` when using Handlebars templates.

```hbs title="Single Term" /control_name/
<div class="term-{{control_name.slug}}">
  {{control_name.name}}
</div>
```

```hbs title="Multiple Terms" /control_name/
<ul class="terms-list">
  {{#each control_name}}
    <li class="term-{{this.slug}}">
      {{this.name}}
    </li>
  {{/each}}
</ul>
```

### Post Meta

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<?php
$term_slug = get_lzb_meta('control_meta_name');
if ($term_slug) {
    $term = get_term_by('slug', $term_slug, 'category');
    if ($term && !is_wp_error($term)) {
        echo '<span class="term">' . esc_html($term->name) . '</span>';
    }
}
?>
```

Use Term Object format to access all term data without additional database queries.

---

# Units

Source: https://www.lazyblocks.com/docs/blocks-controls/units/

Units control combines a numeric input with unit selection (px, %, em, etc.), perfect for spacing, sizes, and other CSS measurements.

## Control Settings

- **Units** (`units`) - the units offered in the control's dropdown. The default list is `px`, `%`, `em`, `rem`, `vw` and `vh`

The field is a tag input. Type a unit and press Enter to add it. Whatever tags the field holds replace the default list outright rather than adding to it, and emptying the field leaves the control with no units at all.

## Usage Examples

### CSS Inline Styles

```php title="PHP" /$attributes['control_name']/
<div style="padding: <?php echo esc_attr( $attributes['control_name'] ); ?>">
    Content with custom padding
</div>
```

```hbs title="Handlebars" /{{control_name}}/
<div style="padding: {{control_name}}">
  Content with custom padding
</div>
```

### Dynamic Margins

```php title="PHP" /$attributes['control_name']/
<div style="margin-top: <?php echo esc_attr( $attributes['control_name'] ); ?>">
    Content with custom top margin
</div>
```

### Post Meta

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<?php
$spacing = get_lzb_meta( 'control_meta_name' );
if ( $spacing ) {
    echo '<div style="gap: ' . esc_attr( $spacing ) . '">';
    echo '    Content with custom gap';
    echo '</div>';
}
?>
```

Common uses for Units control:
- Padding and margins
- Width and height
- Font sizes
- Border widths
- Gap spacing

---

# Users

Source: https://www.lazyblocks.com/docs/blocks-controls/users/

Users control lets you search and select WordPress users by role. Perfect for displaying team members, authors, or any user-related content.

## Control Settings

- **Filter by Role** (`users_role`) - limit the search to specific user roles. Empty by default, which searches every role
- **Output Format** (`users_output_format`) - `User ID` by default:
  - `User ID` - Returns user ID number
  - `User Object` - Hands the block a full WP_User object
- **Multiple** (`multiple`) - off by default. On, the control accepts several users and stores an array

## Usage Examples

### Single User Selection

```php title="PHP with User ID" /$attributes['control_name']/
<?php
$user_id = (int) $attributes['control_name'];
$user = get_user_by('id', $user_id);

if ($user) : ?>
    <div class="user-card">
        <?php echo get_avatar($user->ID, 64); ?>
        <h3><?php echo esc_html($user->display_name); ?></h3>
        <p><?php echo esc_html($user->description); ?></p>
    </div>
<?php endif; ?>
```

### Multiple Users

```php title="PHP with User IDs" /$attributes['control_name']/
<?php if ($attributes['control_name']) : ?>
    <div class="team-members">
        <?php foreach($attributes['control_name'] as $user_id) :
            $user = get_user_by('id', (int) $user_id);
            if ($user) : ?>
                <div class="member">
                    <?php echo get_avatar($user->ID, 96); ?>
                    <h4><?php echo esc_html($user->display_name); ?></h4>
                    <?php if ($user->user_url) : ?>
                        <a href="<?php echo esc_url($user->user_url); ?>">
                            Website
                        </a>
                    <?php endif; ?>
                </div>
            <?php endif;
        endforeach; ?>
    </div>
<?php endif; ?>
```

### Using User Object

```php title="PHP with User Object" /$attributes['control_name']/
<?php if ($attributes['control_name']) : ?>
    <div class="author-box">
        <?php
        $user = $attributes['control_name'];
        echo get_avatar($user->ID, 120);
        ?>
        <h3><?php echo esc_html($user->display_name); ?></h3>
        <?php if ($user->description) : ?>
            <div class="bio">
                <?php echo wp_kses_post($user->description); ?>
            </div>
        <?php endif; ?>
    </div>
<?php endif; ?>
```

### Handlebars Usage

Set Output Format to `User Object` when using Handlebars templates.

```hbs title="Single User" /control_name/
<div class="author-box">
  <h3>{{control_name.display_name}}</h3>
  <div class="bio">
    {{control_name.description}}
  </div>
</div>
```

```hbs title="Multiple Users" /control_name/
<div class="team-members">
  {{#each control_name}}
    <div class="member">
      <h4>{{this.display_name}}</h4>
      {{#if this.description}}
        <p>{{this.description}}</p>
      {{/if}}
    </div>
  {{/each}}
</div>
```

### Post Meta

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<?php
$user_id = get_lzb_meta('control_meta_name');
if ($user_id) {
    $user = get_user_by('id', (int) $user_id);
    if ($user) {
        echo '<div class="user-info">';
        echo get_avatar($user->ID, 64);
        echo '<h3>' . esc_html($user->display_name) . '</h3>';
        echo '</div>';
    }
}
?>
```

The block stores user IDs either way. `User Object` runs the `get_users()` call for you as the block renders, so your template reaches `display_name` without making the query itself.

---

# Link

Source: https://www.lazyblocks.com/docs/blocks-controls/link/

Link control is a link input with title, target, nofollow and CSS class options. The URL control stores a plain URL string, while this one stores the whole set as an object.

## Control Settings

### Link Fields

All four are on by default, and each one hides a row of the link popover. The saved object keeps all five properties either way, so a hidden field leaves its property empty rather than dropping it.

- **Show Title Field** (`show_title_field`) - the Text field that fills `title`
- **Show "Open in new tab" Toggle** (`show_target_field`) - the **Open in new tab** checkbox
- **Show "Mark as nofollow" Toggle** (`show_nofollow_field`) - the **Mark as nofollow** checkbox
- **Show CSS Classes Field** (`show_classes_field`) - the **Additional CSS class(es)** checkbox and the input it reveals, which turns commas into spaces and collapses repeated spaces

### Link Suggestions

- **Link Suggestions** (`link_suggestions`) - `Automatic` by default, which searches every viewable post type. `Disable suggestions` turns the search off, and picking one post type limits the search to it
- **Show Initial Suggestions** (`show_initial_link_suggestions`) - off by default. Lists suggestions before anything is typed, and the row is hidden while Link Suggestions is `Disable suggestions`
- **Rich Preview** (`rich_preview`) - off by default. Shows the target's site title and image inside the field

## Output Format

The Link control returns an object with the following properties:

| Property | Type | Description |
| --- | --- | --- |
| `url` | string | The link URL |
| `title` | string | Custom link title/text |
| `opensInNewTab` | boolean | Whether to open in new tab |
| `nofollow` | boolean | Whether to add nofollow attribute |
| `cssClasses` | string | Custom CSS classes |

## Usage Examples

### Basic Link Output

```php title="PHP" /$attributes['control_name']/
<?php
$link = $attributes['control_name'];
if ( $link && $link['url'] ) :
    $target = $link['opensInNewTab'] ? ' target="_blank"' : '';
    $rel_parts = [];
    if ( $link['opensInNewTab'] ) {
        $rel_parts[] = 'noopener';
        $rel_parts[] = 'noreferrer';
    }
    if ( $link['nofollow'] ) {
        $rel_parts[] = 'nofollow';
    }
    $rel = $rel_parts ? ' rel="' . implode( ' ', $rel_parts ) . '"' : '';
    $classes = $link['cssClasses'] ? ' class="' . esc_attr( $link['cssClasses'] ) . '"' : '';
    $title = $link['title'] ?: __( 'Click here', 'your-text-domain' );
?>
    <a href="<?php echo esc_url( $link['url'] ); ?>"<?php echo $target . $rel . $classes; ?>>
        <?php echo esc_html( $title ); ?>
    </a>
<?php endif; ?>
```

### Button with Link

```php title="PHP" /$attributes['control_name']/
<?php
$link = $attributes['control_name'];
if ( $link && $link['url'] ) :
    $attrs = [
        'href'  => esc_url( $link['url'] ),
        'class' => 'button ' . esc_attr( $link['cssClasses'] ?? '' ),
    ];

    if ( $link['opensInNewTab'] ) {
        $attrs['target'] = '_blank';
        $attrs['rel'] = 'noopener noreferrer';
    }

    if ( $link['nofollow'] ) {
        $attrs['rel'] = ( $attrs['rel'] ?? '' ) . ' nofollow';
    }

    $attr_string = '';
    foreach ( $attrs as $key => $value ) {
        $attr_string .= sprintf( ' %s="%s"', $key, trim( $value ) );
    }
?>
    <a<?php echo $attr_string; ?>>
        <?php echo esc_html( $link['title'] ?: __( 'Learn More', 'your-text-domain' ) ); ?>
    </a>
<?php endif; ?>
```

### Handlebars Usage

```hbs title="Basic Link" /control_name/
{{#if control_name.url}}
  <a href="{{control_name.url}}"
     {{#if control_name.opensInNewTab}}target="_blank" rel="noopener noreferrer"{{/if}}
     {{#if control_name.cssClasses}}class="{{control_name.cssClasses}}"{{/if}}>
    {{#if control_name.title}}
      {{control_name.title}}
    {{else}}
      Click here
    {{/if}}
  </a>
{{/if}}
```

### Post Meta

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<?php
$link = get_lzb_meta( 'control_meta_name' );
if ( $link && ! empty( $link['url'] ) ) {
    $target = ! empty( $link['opensInNewTab'] ) ? '_blank' : '_self';
    $rel = [];

    if ( ! empty( $link['opensInNewTab'] ) ) {
        $rel[] = 'noopener';
        $rel[] = 'noreferrer';
    }
    if ( ! empty( $link['nofollow'] ) ) {
        $rel[] = 'nofollow';
    }

    printf(
        '<a href="%1$s" target="%2$s"%3$s%4$s>%5$s</a>',
        esc_url( $link['url'] ),
        esc_attr( $target ),
        $rel ? ' rel="' . esc_attr( implode( ' ', $rel ) ) . '"' : '',
        ! empty( $link['cssClasses'] ) ? ' class="' . esc_attr( $link['cssClasses'] ) . '"' : '',
        esc_html( $link['title'] ?: __( 'Read More', 'your-text-domain' ) )
    );
}
?>
```

- Always use `esc_url()` when outputting URLs to prevent XSS attacks.
- When `opensInNewTab` is true, always include `rel="noopener noreferrer"` for security.
- The Link control stores data as an object, so access properties using array syntax in PHP.

---

# Divider

Source: https://www.lazyblocks.com/docs/blocks-controls/divider/

Divider control helps you organize block settings by adding visual separators between controls.

## Control Settings

The control adds no settings of its own, and it stores no value. It exists to break a long inspector into readable sections, so it has no **Name** and nothing reaches your block code.

Divider is a layout control and doesn't output any value in your block's content.

---

# Message

Source: https://www.lazyblocks.com/docs/blocks-controls/message/

Message control lets you add helpful text and instructions between other controls in your block settings.

## Control Settings

- **Message** (`message_text`) - the text to display in block settings. Empty by default
- **New Lines** (`message_new_lines`) - how line breaks in that text are rendered:
  - `Automatically add paragraphs` runs the text through `wpautop`, and is the default
  - `Automatically add <br>` runs it through `nl2br`
  - `No formatting` prints the text as it was typed

Message is a layout control used only in the block editor and doesn't output any value in your block's content.

---

# Panel

Source: https://www.lazyblocks.com/docs/blocks-controls/panel/

Panel control helps you organize block settings by grouping related controls together in collapsible sections.

## Control Settings

- **Endpoint** (`endpoint`) - off by default. Turning it on ends the panel before it, and the controls that follow render in a panel with no title that is always open
- **Initial Open** (`initial_open`) - whether the panel starts expanded. On by default
- **Icon** (`icon`) - an icon drawn beside the panel title. Empty by default

Initial Open and Icon disappear from the control settings while Endpoint is on, because an endpoint panel has neither a title to sit beside nor a state to remember.

- Panel is a layout control used to organize other controls and doesn't output any value in your block's content.
- Use panels to group related controls together, such as "Typography", "Colors", or "Layout" settings.

---

# Repeater

Source: https://www.lazyblocks.com/docs/blocks-controls/repeater/

Repeater control lets you create dynamic groups of controls that users can add multiple times. Perfect for creating lists, slides, or any repeatable content structure.

  All controls except Inner Blocks can be used inside a repeater. This lets you
  create flexible and complex data structures.

## Control Settings

- **Row Label** (`rows_label`) - text on each row header, `Row {{#}}` when left empty. Supports dynamic values:
  - `{{#}}` - the row number, counting from 1
  - `{{control_name}}` - the value of an inner control
  - `{{control_name.url}}` - one key of an object value, such as an Image control. `alt`, `url`, `title`, `caption`, `description`, `id` and `link` are replaced
- **Add Button Label** (`rows_add_button_label`) - text on the add button, `+ Add Row` when left empty
- **Minimum Rows** (`rows_min`) - rows the control creates by itself. The remove button disappears once the count is down to this number
- **Maximum Rows** (`rows_max`) - the count at which the add button is disabled
- **Collapsible Rows** (`rows_collapsible`) - collapse rows into their headers, on by default
- **Collapsed by Default** (`rows_collapsed`) - start with every row collapsed, on by default. This setting only appears while Collapsible Rows is on

With Collapsible Rows on, opening a row closes the one that was open, so a single row is expanded at a time. Turning Collapsed by Default off opens every row until the first header is clicked.

## Usage Examples

### Basic List

```php title="PHP" /$attributes['control_name']/
<ul class="items-list">
  <?php foreach( $attributes['control_name'] as $item ): ?>
    <li>
      <?php echo esc_html( $item['title'] ); ?>
      <p><?php echo esc_html( $item['description'] ); ?></p>
    </li>
  <?php endforeach; ?>
</ul>
```

```hbs title="Handlebars" /control_name/
<ul class="items-list">
  {{#each control_name}}
    <li>
      {{title}}
      <p>{{description}}</p>
    </li>
  {{/each}}
</ul>
```

### Post Meta

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<?php
$items = get_lzb_meta( 'control_meta_name' );

if ( $items ) : ?>
  <ul class="items-list">
    <?php foreach ( $items as $item ) : ?>
      <li>
        <?php echo esc_html( $item['title'] ); ?>
        <p><?php echo esc_html( $item['description'] ); ?></p>
      </li>
    <?php endforeach; ?>
  </ul>
<?php endif; ?>
```

## Nested Repeaters

  Nested repeaters (repeater inside repeater) are not supported and may cause
  unexpected behavior. This is a technical limitation that we're aware of.

Instead of nested repeaters, consider these alternatives:

- Use separate repeaters
- Split content into multiple blocks
- Use custom controls for specific use cases

Use meaningful row labels with dynamic values to help users identify content: `Slide {{#}}: {{title}}`

---

# Migrating Off the Inner Blocks Control

Source: https://www.lazyblocks.com/docs/blocks-controls/inner-blocks/

Inner Blocks control is **deprecated** since v3.4.0. You need to migrate to the **&lt;InnerBlocks />** component as this control will be removed in future updates.

## Migration Guide

Follow these steps to migrate from the deprecated control to the &lt;InnerBlocks /> component:

1. Add the &lt;InnerBlocks /> component to your block output code (both Frontend and Editor):
   

2. Remove the Inner Blocks control:
   

3. Learn more about &lt;InnerBlocks /> component features in our [documentation](https://www.lazyblocks.com/docs/blocks-code/inner-blocks/).

The new &lt;InnerBlocks /> component provides better performance and more features than the deprecated control.

---

## Deprecated Control Documentation

This documentation is for the deprecated control. We strongly recommend migrating to the new &lt;InnerBlocks /> component.

Inner Blocks control creates a nested blocks area in your block. You can only use one Inner Blocks control per block.

### Usage

```php title="PHP" /$attributes['control_name']/
<div>
  <?php echo $attributes['control_name']; ?>
</div>
```

```hbs title="Handlebars" /{{{control_name}}}/
<div>
  {{{control_name}}}
</div>
```

When using Handlebars, use triple curly brackets to output HTML: `{{{` and `}}}`

Inner Blocks cannot be used as Meta fields.

---

# Block Code & Assets

Source: https://www.lazyblocks.com/docs/blocks-code/overview/

Every block needs code to display its content on the frontend and in the editor. Lazy Blocks provides multiple methods to handle block output, plus the ability to add custom styles and scripts, giving you complete control over your block's appearance and functionality.

## Available Methods

### [HTML + Handlebars](https://www.lazyblocks.com/docs/blocks-code/handlebars/)

Use HTML with Handlebars syntax for simple static content. Great for frontend developers who prefer template-based approaches.

### [PHP](https://www.lazyblocks.com/docs/blocks-code/php/)

Write PHP code directly in the block builder. Best for dynamic content and complex logic with WordPress integration.

### [Theme Template](https://www.lazyblocks.com/docs/blocks-code/theme-template/)

Create template files in your theme. Perfect for version control and team development workflows.

## Block Assets

### [Styles & Scripts](https://www.lazyblocks.com/docs/blocks-code/styles-scripts/)

Add custom CSS and JavaScript to your blocks. Control styling and add interactive functionality directly in the block builder interface using the **block.css** and **view.js** tabs.

### [Relationships](https://www.lazyblocks.com/docs/blocks-code/relationships/)

Create interconnected blocks that share context data and enforce hierarchical rules. Perfect for building complex block systems like API dashboards, form sections, and data-driven interfaces.

## Block Components

### [useBlockProps](https://www.lazyblocks.com/docs/blocks-code/use-block-props/)

Essential component for applying WordPress block wrapper attributes and ensuring proper block functionality.

### [Inner Blocks](https://www.lazyblocks.com/docs/blocks-code/inner-blocks/)

Create nested block areas where users can add and manage other blocks inside your custom block.

### [PHP Callback](https://www.lazyblocks.com/docs/blocks-code/php-callback/)

Register custom PHP callback functions for advanced customization and reusable code patterns.

Choose your output method based on:
- Development workflow
- Code complexity
- Team expertise
- Maintenance requirements

---

# Handlebars

Source: https://www.lazyblocks.com/docs/blocks-code/handlebars/

The Handlebars output method builds a block's HTML from a template with the control values written into it, and the conditionals and loops of the Handlebars syntax around them.

## Basic usage

```hbs title="Handlebars Example"
{{#if control_name}}
  <div class="message">
    {{control_name}}
  </div>
{{/if}}
```

## Available helpers

In addition to [default Handlebars helpers](https://handlebarsjs.com/guide/builtin-helpers.html), Lazy Blocks provides custom helpers for WordPress-specific functionality.

Every helper except `truncate` returns a plain string, which Handlebars escapes. Write `{{helper ...}}` for text and `{{{helper ...}}}` when the helper produces markup you want rendered.

### truncate

Truncates text to a specified length.

```hbs title="Truncate Example"
{{truncate control_name 100 "true"}}
```

| Parameter | Description                |
| --------- | -------------------------- |
| String    | Text to truncate           |
| Limit     | Character limit            |
| Dots      | Show ellipsis (true/false) |

The cut walks back to the last space before the limit, so a word is kept whole. A run of characters with no space in it is cut at the limit itself. A string already shorter than the limit comes back untouched. This is the one helper whose output is left unescaped, and only when it truncates, so a cut string is printed as markup while an untouched one is escaped.

### compare

Compares values for conditional rendering.

```hbs title="Compare Example"
{{#compare price ">" 100}}
  <span class="premium">Premium Item</span>
{{/compare}}
```

| Parameter    | Description                                                            |
| ------------ | ---------------------------------------------------------------------- |
| First Value  | Left side value                                                        |
| Operator     | `==`, `===`, `!=`, `!==`, `<`, `>`, `<=`, `>=`, `&&`, `\|\|`, `typeof` |
| Second Value | Right side value                                                       |

`typeof` compares PHP's type name of the first value with the second, as in `{{#compare control_name "typeof" "array"}}`. Dropping the operator is allowed, and `{{#compare a b}}` compares with `===`. An operator outside the list makes the comparison false, so the `{{else}}` branch runs.

### math

Performs mathematical operations.

```hbs title="Math Example"
<div class="price">
  ${{math price "*" quantity}}
</div>
```

| Parameter    | Description             |
| ------------ | ----------------------- |
| First Value  | Left side value         |
| Operator     | `+`, `-`, `*`, `/`, `%` |
| Second Value | Right side value        |

Any other operator prints nothing, so a typo in the operator leaves an empty spot rather than an error.

### date_i18n

Formats dates using WordPress localization.

```hbs title="Date Example"
<time datetime="{{control_date}}">
  {{date_i18n "F j, Y" control_date}}
</time>
```

| Parameter | Description                      |
| --------- | -------------------------------- |
| Format    | Date format (e.g., `F j, Y H:i`) |
| Date      | Date string                      |

### do_shortcode

Processes WordPress shortcodes.

```hbs title="Shortcode Example"
{{{do_shortcode "my_shortcode" this}}}
```

| Parameter  | Description                         |
| ---------- | ----------------------------------- |
| Name       | Shortcode name                      |
| Attributes | Use `this` for all block attributes |

A `content` key in the passed object becomes the shortcode's inner content. The block's own code fields, `data` and `hash` are dropped, and an array value is encoded as JSON before it reaches the shortcode attribute.

### wp_get_attachment_image

Outputs WordPress image with proper srcset.

```hbs title="Image Example"
{{{wp_get_attachment_image image_control "large"}}}
```

| Parameter | Description                          |
| --------- | ------------------------------------ |
| Image     | Image control value                  |
| Size      | Image size name (default: thumbnail) |

The first argument takes an Image control value or a bare attachment ID. An image added by URL has no `id`, and the helper falls back to a plain `<img>` tag built from its `url`.

### var_dump

Dumps a value while you are building the block.

```hbs title="Debug Example"
{{{var_dump control_name}}}
```

| Parameter | Description                 |
| --------- | --------------------------- |
| Value     | Any value from the template |

The helper returns PHP's `var_dump()` output as a plain string, so `{{var_dump control_name}}` shows it escaped and `{{{var_dump control_name}}}` renders it as markup. Nothing gates it, not `WP_DEBUG` and not a capability, so a block published with it dumps the value to logged-out visitors on the front end. Take it out before the block goes live.

## Adding custom helpers

Create your own Handlebars helpers:

```php title="PHP"
function my_custom_handlebars_helper($handlebars) {
    $handlebars->registerHelper('format_price', function($price) {
        return '$' . number_format($price, 2);
    });
}
add_action('lzb/handlebars/object', 'my_custom_handlebars_helper');
```

Usage:

```hbs
<div class="price">
  {{format_price product_price}}
</div>
```

See [lzb/handlebars/object](https://www.lazyblocks.com/docs/php-actions/lzb-handlebars-object/) for the object the action passes and for when it fires.

  Use Handlebars when you need simple templates with basic logic. For complex
  dynamic content, consider using PHP output instead.

---

# PHP

Source: https://www.lazyblocks.com/docs/blocks-code/php/

PHP output method gives you full access to WordPress functions and PHP features while rendering your block content.

## Basic Usage

Access block controls through the `$attributes` array:

```php title="Simple Example"
<?php if ($attributes['show_title']) : ?>
    <h2><?php echo esc_html($attributes['title']); ?></h2>
<?php endif; ?>
```

## Block Context

The `$context` variable holds the [block context](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-context/) the block receives, or `null` when it receives none. A block receives only the context keys it lists in `uses_context`, so a block placed inside a Query Loop gets the loop's `postId` and `postType` only after it asks for them.

The block builder has no field for `uses_context`. Add it with the [lzb/register_block_type_data](https://www.lazyblocks.com/docs/php-filters/lzb-register_block_type_data/) filter:

```php title="functions.php"
add_filter( 'lzb/register_block_type_data', function ( $data, $block ) {
    if ( 'lazyblock/post-card' === $block['slug'] ) {
        $data['uses_context'] = array( 'postId', 'postType' );
    }

    return $data;
}, 10, 2 );
```

Then read the keys in the block code. Inside a Query Loop, `postId` is the post of the current loop item. The editor preview can render without the context, so give each key a fallback:

```php title="Block Context"
<?php $post_id = $context['postId'] ?? get_the_ID(); ?>
<h3><?php echo esc_html( get_the_title( $post_id ) ); ?></h3>
```

With Lazy Blocks Pro, [Relationships](https://www.lazyblocks.com/docs/blocks-code/relationships/) pass a parent block's values to its inner blocks through the same `$context` variable.

## Common Examples

### Working with Images

```php title="Image Control"
<?php
if (isset($attributes['image']['url'])) :
    $image_url = esc_url($attributes['image']['url']);
    $image_alt = esc_attr($attributes['image']['alt']);
    ?>
    <img src="<?php echo $image_url; ?>"
         alt="<?php echo $image_alt; ?>"
         class="featured-image">
<?php endif; ?>
```

### Repeater Fields

```php title="Repeater Control"
<?php if (isset($attributes['items']) && is_array($attributes['items'])) : ?>
    <ul class="items-list">
        <?php foreach ($attributes['items'] as $item) : ?>
            <li class="item">
                <?php echo esc_html($item['title']); ?>
                <p><?php echo wp_kses_post($item['description']); ?></p>
            </li>
        <?php endforeach; ?>
    </ul>
<?php endif; ?>
```

### Using WordPress Functions

```php title="WordPress Integration"
<?php
// Get related posts
$related = get_posts([
    'category__in' => wp_get_post_categories(get_the_ID()),
    'numberposts'  => $attributes['posts_count'],
    'post__not_in' => [get_the_ID()]
]);

if ($related) : ?>
    <div class="related-posts">
        <h3><?php esc_html_e('Related Posts', 'your-textdomain'); ?></h3>
        <ul>
            <?php foreach ($related as $post) : ?>
                <li>
                    <a href="<?php echo esc_url(get_permalink($post->ID)); ?>">
                        <?php echo esc_html($post->post_title); ?>
                    </a>
                </li>
            <?php endforeach; ?>
        </ul>
    </div>
<?php endif; ?>
```

Always use proper escaping functions:
- `esc_html()` for text content
- `esc_attr()` for HTML attributes
- `esc_url()` for URLs
- `wp_kses_post()` for HTML content

---

# Theme Template

Source: https://www.lazyblocks.com/docs/blocks-code/theme-template/

Theme Template output method lets you store block code in separate PHP files within your theme directory. This approach is perfect for version control and team development.

## Template Structure

Place your block templates in the `/blocks/` directory of your theme:

```bash
/wp-content/themes/your-theme/
├── blocks/
│   └── lazyblock-testimonial/
│       ├── block.php                # Frontend & Editor template (required)
│       │                            # This file is always used for block render
│       │
│       ├── editor.php               # Editor-only template (optional)
│       │                            # Loaded only in the editor, alongside block.php
│       │
│       ├── block.css                # Frontend & Editor styles (optional)
│       │                            # Automatically enqueued if present
│       │                            # Available in Pro version only
│       │
│       ├── editor.css               # Editor-only styles (optional)
│       │                            # Automatically enqueued in editor only
│       │                            # Available in Pro version only
│       │
│       └── view.js                  # Frontend-only JavaScript (optional)
│                                    # Automatically enqueued on the frontend
│                                    # Available in Pro version only
```

Template files are first checked in the child theme, then in the parent theme.

## Template Files

### block.php (Required)
The main template file used for both frontend and editor rendering. This file receives block attributes and should output the block's HTML structure.

**Available Variables:**
- `$attributes` - Array of block attributes
- `$context` - Array of context data available to the block from parent blocks
- `$block` - Block data object
- `$render_location` - Render block preview location (`editor` or `frontend`)

### editor.php (Optional)
An editor-specific template that displays only in the WordPress block editor alongside `block.php`. Use this for enhanced editor previews or when you need different display logic for the editor.

## Styles & Scripts

Theme templates automatically support CSS and JavaScript files when using the Pro version. For detailed information about adding styles and scripts to your blocks, see the [Styles & Scripts documentation](https://www.lazyblocks.com/docs/blocks-code/styles-scripts/).

## File Naming

Block templates should match your block slug:

| Block Slug              | Template Path                             |
| ----------------------- | ----------------------------------------- |
| `lazyblock/testimonial` | `/blocks/lazyblock-testimonial/block.php` |
| `lazyblock/team-member` | `/blocks/lazyblock-team-member/block.php` |
| `lazyblock/pricing`     | `/blocks/lazyblock-pricing/block.php`     |

**Benefits of Theme Templates:**
- Version control compatibility
- Team collaboration friendly
- Better code organization
- Easy sharing between projects
- Automatic asset enqueuing (Pro)

---

# Styles & Scripts

Source: https://www.lazyblocks.com/docs/blocks-code/styles-scripts/

Add custom CSS styles and JavaScript to your Lazy Blocks. Assets can be added through the block builder interface or as separate files when using [Theme Templates](https://www.lazyblocks.com/docs/blocks-code/theme-template/).

## Asset Types

| File Type | Description | Loaded |
|-----------|-------------|--------|
| `block.css` | Shared styles for editor and frontend | Editor: Always / Frontend: When block is present |
| `editor.css` | Editor-specific styles | Editor: Always |
| `view.js` | Interactive functionality | Frontend: When block is present |

## Adding Assets

### Block Builder Interface
Use the dedicated tabs in the block builder:
- **block.css** - Shared styles (editor + frontend)
- **editor.css** - Editor-only styles
- **view.js** - Frontend JavaScript

### Theme Template Files
When using [Theme Templates](https://www.lazyblocks.com/docs/blocks-code/theme-template/), assets are automatically detected if files exist in your block directory:

```bash
/blocks/lazyblock-your-block/
├── block.php        # Required template
├── block.css        # Shared styles
├── editor.css       # Editor styles
└── view.js          # Frontend JavaScript
```

Assets are checked in child theme first, then parent theme.

## Performance & Loading

- **Editor**: Styles (`block.css` and `editor.css`) are always loaded in the WordPress block editor
- **Frontend**: Assets are only loaded when your block is present on the current page, ensuring optimal performance

---

# Relationships

Source: https://www.lazyblocks.com/docs/blocks-code/relationships/

A block can hand its own values to the blocks nested inside it, and can say which blocks may contain it and which blocks it may contain. The settings are in the block builder's **Condition** panel, under **Relationships**.

## Relationship settings

### Provide Context to Blocks

The blocks that receive every attribute of this one as context data. A block listed here reads the values instead of carrying its own copy of them.

### Context Custom Slug (Optional)

The namespace the context keys are built from. The block's own slug is used when this is empty, so a key looks like `lazyblock/my-custom-block/control-name`.

### Ancestor

Which blocks may contain this one. The block cannot be inserted anywhere else.

### Allowed Blocks

Which blocks may be inserted into this block's `` area.

## Reading the context

In PHP access context data using the `$context` array:

```php title="PHP"
$value = $context['parent-block-slug/control-name'] ?? 'default';
```

In Handlebars use square bracket notation for context variables:

```hbs title="Handlebars"
{{[parent-block-slug/control-name]}}
```

  Square brackets are required in Handlebars when the context name contains a
  slash: <code>{`{{[parent-slug/control-name]}}`}</code>

## Example: an API dashboard

A parent block holds the API settings once, and several child blocks show different views of the same source without a second copy of those settings.

### Step 1: the parent block

Create a new block `lazyblock/api-dashboard`:

1. Add these controls:
   - `api-endpoint` (URL control)
   - `refresh-interval` (Number control)
   - `api-key` (Text control)
   - `data-format` (Select control: JSON, XML, CSV)

2. In Relationships panel:
   - **Provide Context to Blocks**: Select `lazyblock/data-table`, `lazyblock/data-chart`, `lazyblock/data-summary`
   - **Allowed Blocks**: Add `core/paragraph`, `core/heading`, `lazyblock/data-table`, `lazyblock/data-chart`, `lazyblock/data-summary`

**Block Code:**

```php title="PHP"
<div useBlockProps>
  <div class="dashboard-header">
    <h2>Data Dashboard</h2>
    <p>Source: <?php echo esc_url($attributes['api-endpoint']); ?></p>
    <p>Updates every <?php echo esc_html($attributes['refresh-interval']); ?> seconds</p>
  </div>

  <InnerBlocks
    template="[
      [ 'core/heading', { content: 'Key Metrics', level: 3 } ],
      [ 'lazyblock/data-summary' ],
      [ 'core/heading', { content: 'Detailed View', level: 3 } ],
      [ 'lazyblock/data-table' ],
      [ 'lazyblock/data-chart' ]
    ]"
  />
</div>
```

### Step 2: the child blocks

Create data display blocks that inherit API configuration:

#### Data Table Block (`lazyblock/data-table`)

1. In Relationships panel:
   - **Ancestor**: Select `lazyblock/api-dashboard`

**Block Code:**

```php title="PHP"
<?php

$api_endpoint = $context['api-dashboard/api-endpoint'] ?? '';
$api_key = $context['api-dashboard/api-key'] ?? '';
$data_format = $context['api-dashboard/data-format'] ?? 'json';

?>

<div useBlockProps>
  <?php if ($api_endpoint): ?>
    <div class="data-table">
      <table>
        <thead>
          <tr><th>Data Table</th><th>Format: <?php echo esc_html($data_format); ?></th></tr>
        </thead>
        <tbody>
          <tr>
            <td>API Source:</td>
            <td><?php echo esc_url($api_endpoint); ?></td>
          </tr>
          <!-- Table data would be populated via JavaScript/AJAX using the context values -->
        </tbody>
      </table>
    </div>
  <?php else: ?>
    <p>Configure API endpoint in the parent Dashboard block...</p>
  <?php endif; ?>
</div>
```

#### Data Chart Block (`lazyblock/data-chart`)

Similar structure but displays data as charts:

**Block Code:**

```php title="PHP"
<?php

$api_endpoint = $context['api-dashboard/api-endpoint'] ?? '';
$refresh_interval = $context['api-dashboard/refresh-interval'] ?? 30;

?>

<div useBlockProps>
  <?php if ($api_endpoint): ?>
    <div class="data-chart"
         data-endpoint="<?php echo esc_attr($api_endpoint); ?>"
         data-refresh="<?php echo esc_attr($refresh_interval); ?>">
      <canvas id="dashboard-chart"></canvas>
      <p>Auto-refresh: <?php echo esc_html($refresh_interval); ?>s</p>
    </div>
  <?php else: ?>
    <p>Configure API settings in the parent Dashboard block...</p>
  <?php endif; ?>
</div>
```

**Using Handlebars:**

```hbs title="Handlebars"
<div useBlockProps>
  {{#if [api-dashboard/api-endpoint]}}
    <div class="data-chart"
         data-endpoint="{{[api-dashboard/api-endpoint]}}"
         data-refresh="{{[api-dashboard/refresh-interval]}}">
      <canvas id="dashboard-chart"></canvas>
      <p>Auto-refresh: {{[api-dashboard/refresh-interval]}}s</p>
    </div>
  {{else}}
    <p>Configure API settings in the parent Dashboard block...</p>
  {{/if}}
</div>
```

## Third-party blocks

**Provide Context to Blocks** is a creatable multi-select. The dropdown lists the other Lazy Blocks on the site, and anything you type is accepted as well, so `core/paragraph` or a slug from another plugin can be added by hand.

Nothing has to be declared on the consumer's side. A `core/paragraph` placed inside the provider reads the value in its `edit` function:

```js title="JS"
const heading = props.context["lazyblock/my-card/heading"];
```

A block rendered on the server reads the same key from the `WP_Block` instance:

```php title="PHP"
$heading = $block->context['lazyblock/my-card/heading'] ?? '';
```

### Keys a provider hands out

One key per control, `{context_slug}/{control_name}`, plus three fixed keys: `{context_slug}/blockId`, `{context_slug}/className` and `{context_slug}/anchor`. The `{context_slug}` part is the **Context Custom Slug** when it is filled in, and the provider's full block slug otherwise.

The child controls of a repeater are listed among the keys with no parent prefix and no filtering, while the repeater stores its rows as a single value. Read the repeater's own key instead of a child's.

Two things keep context from arriving:

- The consumer must be a descendant of the provider in the block tree. That is a WordPress rule rather than a Lazy Blocks one, so a block sitting next to the provider receives nothing.
- A provider with no controls contributes no keys at all, the three fixed ones included.

---

# useBlockProps

Source: https://www.lazyblocks.com/docs/blocks-code/use-block-props/

The `useBlockProps` attribute is a special attribute that automatically generates proper block wrapper attributes including block classes, block ID, and other WordPress-specific attributes. This attribute works both in the editor and on the frontend, ensuring consistent block behavior.

If you landed here before building your first block, start with [WordPress custom blocks](https://www.lazyblocks.com/wordpress-custom-blocks/).

## Basic Usage

Add the `useBlockProps` attribute to your block wrapper element:

```html
<div useBlockProps>
  {{control_name}}
</div>
```

When rendered, this automatically becomes:

```html
<div class="wp-block-lazyblock-your-block-name" id="block-123abc">
  <!-- Your block content -->
</div>
```

## Custom Classes and Attributes

You can add your own classes and attributes alongside `useBlockProps`:

```html
<div useBlockProps class="custom-class another-class" data-hello="world">
  {{control_name}}
</div>
```

This will merge your custom attributes with the WordPress block attributes:

```html
<div class="wp-block-lazyblock-your-block-name custom-class another-class" id="block-123abc" data-hello="world">
  <!-- Your block content -->
</div>
```

Every attribute you write next to `useBlockProps` stays as you wrote it: unquoted values, boolean attributes such as `hidden`, JSON in a `data-` attribute, and Interactivity API directives such as `data-wp-interactive`. The element can be a custom element too, such as `<my-card useBlockProps>`.

## Automatic Wrapper

If you don't include `useBlockProps` in your block code, Lazy Blocks will automatically wrap your entire block output:

**Your code:**
```html
<h2>{{title}}</h2>
<p>{{content}}</p>
```

**Automatically becomes:**
```html
<div useBlockProps>
  <h2>{{title}}</h2>
  <p>{{content}}</p>
</div>
```

## Why Use useBlockProps?

### WordPress Compatibility
- Ensures proper block identification in WordPress
- Maintains consistency with core WordPress blocks
- Supports block themes and Full Site Editing

### Editor Integration
- Provides proper block selection and highlighting
- Enables block toolbar positioning
- Supports block spacing and alignment controls

### Theme Support
- Allows theme styles to target your blocks correctly
- Supports WordPress block spacing (gap, margin, padding)
- Enables proper block alignment classes

---

# InnerBlocks: Nested Blocks Inside a Custom Block

Source: https://www.lazyblocks.com/docs/blocks-code/inner-blocks/

The `` component is a special Lazy Blocks component that creates a nested block area where users can add and manage other blocks inside your custom block. This component gets processed and replaced with proper WordPress InnerBlocks functionality during block rendering.

You can use only one &lt;InnerBlocks /> component per block.

## Basic Usage

Add the `` component anywhere in your block code:

```php
<div useBlockProps>
  <h2>Inner block here:</h2>
  <InnerBlocks />
</div>
```

## Advanced Examples

### Locked Template

Create a block with predefined content that users can't move or remove:

```php
<InnerBlocks
  template="[
    [ 'core/heading', {
        content: 'Welcome Section',
        level: 2
    } ],
    [ 'core/paragraph', {
        content: 'This paragraph is locked',
        className: 'intro-text',
        lock: {
          remove: true,
          move: true
        }
    } ],
    [ 'core/paragraph', {
        content: 'This one can be removed'
    } ]
  ]"
/>
```

### Limited Block Types

Restrict available blocks and create a predefined column layout:

```php
<div class="custom-layout">
  <h3>Content Section</h3>

  <InnerBlocks
    allowedBlocks="[
      'core/paragraph',
      'core/image',
      'core/columns',
      'core/column'
    ]"
    template="[
      [ 'core/columns', {}, [
        [ 'core/column', {}, [
          [ 'core/image' ]
        ] ],
        [ 'core/column', {}, [
          [ 'core/paragraph', {
            placeholder: 'Add content here...'
          } ]
        ] ]
      ] ]
    ]"
  />
</div>
```

## Component Attributes

### Essential Attributes

- **className** - Custom wrapper class (default: `lazyblock-inner-blocks`)
- **allowedBlocks** - Array of allowed block types
- **template** - Predefined blocks structure

For advanced block control and context sharing, check out [Relationships](https://www.lazyblocks.com/docs/blocks-code/relationships/) which includes an "Allowed Blocks" setting and enables parent-child data sharing.

### Lock Options

- **templateLock**:
  - `contentOnly` - Prevents all operations
  - `all` - Prevents inserting, moving, and removing blocks
  - `insert` - Prevents adding/removing blocks, allows moving
  - `false` - Disables locking

### Additional Attributes

- **prioritizedInserterBlocks** - Block types to prioritize in the inserter

## Custom Wrapper

By default, Lazy Blocks adds a wrapper around Inner Blocks. Disable it using:

```php
add_filter(
    'lazyblock/your-block-slug/allow_inner_blocks_wrapper',
    '__return_false'
);
```

## Best Practices

- Use templates to create structured layouts and maintain content consistency
- Consider user experience when setting lock options
- For detailed template options, see the [WordPress Block Templates documentation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-templates/).

---

# Rich Text

Source: https://www.lazyblocks.com/docs/blocks-code/rich-text/

The `` component makes a control's value editable straight on the canvas, the way a caption on a core block is. The same value stays editable from the inspector, so the two are two views of one attribute. A `name` that matches no control works as well, and then the component registers and owns the attribute by itself.

## Basic usage

Add the component to your block code and point it at a control by name:

```html
<div useBlockProps>
  <RichText name="title" tagName="h2" placeholder="Add title…" />
</div>
```

The control named `title` now takes its text from the canvas. On the front end the component renders as the tag you gave it:

```html
<div class="wp-block-lazyblock-your-block-name">
  <h2>Your typed title</h2>
</div>
```

## Attributes

| Name                           | Type        | Description                                                                    |
| ------------------------------ | ----------- | ------------------------------------------------------------------------------ |
| `name`                         | **String**  | control or standalone attribute to bind to. Letters, numbers, `-` and `_` only |
| `tagName`                      | **String**  | tag to render, `p` by default. `none` renders the text with no tag around it   |
| `placeholder`                  | **String**  | text shown while the value is empty                                            |
| `allowedFormats`               | **String**  | formats to offer, comma-separated or a JSON array. Everything, by default      |
| `inlineToolbar`                | **Boolean** | show the formatting toolbar inline, `true` by default                          |
| `withoutInteractiveFormatting` | **Boolean** | drop formats that produce clickable elements, `false` by default               |
| `disableLineBreaks`            | **Boolean** | stop <kbd>Enter</kbd> from inserting a line break, `false` by default          |
| `default`                      | **String**  | value a freshly inserted block starts with                                     |
| `translate`                    | **String**  | `translate="false"` keeps the value out of WPML                                |
| `format`                       | **String**  | accepted and ignored                                                           |
| `identifier`                   | **String**  | accepted and ignored                                                           |
| `multiline`                    | **String**  | accepted and ignored                                                           |

`default` seeds the block attribute the component registers, so a new block arrives with text in place instead of the placeholder. When the same name appears on more than one tag, the first tag that carries a `default` wins. The value is never printed on the rendered tag.

`translate="false"` on any tag takes that name out of the WPML config for the whole block. A name that belongs to a control follows the control's own **WPML Translation** setting instead. See [Multilingual](https://www.lazyblocks.com/docs/multilingual/).

`format`, `identifier` and `multiline` are accepted and then stripped from the rendered tag. Nothing reads them. A single-line field is `disableLineBreaks`, not `multiline`.

Any other attribute is passed through to the rendered element, so `class`, `id` and `data-*` work as they do on a plain tag.

```html
<div useBlockProps>
  <RichText
    name="intro"
    tagName="p"
    class="my-intro"
    allowedFormats="core/bold,core/italic"
    placeholder="Add an intro…"
  />
</div>
```

## Links

Give the component `tagName="a"` and it edits the link text on the canvas while rendering a real anchor on the front end, the same way the core Button block behaves. The link is not followable while you are editing it.

```html
<div useBlockProps>
  <RichText
    name="label"
    tagName="a"
    href="https://example.com"
    placeholder="Add label…"
  />
</div>
```

`href`, `target`, `rel` and `download` are all passed through to the anchor.

## Which controls it can bind to

The component works with the controls that store text:

| Control                  | Formatting kept | Line breaks |
| ------------------------ | --------------- | ----------- |
| Rich Text (WYSIWYG)      | yes             | yes         |
| Classic Editor (WYSIWYG) | yes             | yes         |
| Textarea                 | no              | yes         |
| Code Editor              | no              | yes         |
| Text                     | no              | no          |
| URL                      | no              | no          |
| Email                    | no              | no          |

The component never stores more than the control behind it can hold. The same value is still edited by the control in the inspector, so putting HTML or a second line into a plain Text control would destroy it there. For those controls the component turns formatting and line breaks off by itself, whatever you passed in `allowedFormats` or `disableLineBreaks`.

Controls that store JSON rather than text, Image, Gallery and Repeater, cannot be bound, and neither can a control living inside a Repeater. Naming one warns in the browser console and leaves the value alone.

An empty value is offered for editing only while the block is selected, the same as a caption on a core block, and prints nothing on the front end.

## A name with no control

`name` does not have to match a control. When no control carries that name, the component registers the block attribute itself, `type: string` with the tag's `default` or an empty string, and owns the value outright. Such a value is edited on the canvas only, because there is no inspector control mirroring it.

Two kinds of name are skipped even so, one the block already uses as an attribute of its own, and one belonging to a control with **Save in Meta** turned on, whose value lives in post meta rather than in the block attributes.

Escaping follows the same split. With no control behind the name the component owns the markup and keeps it through `wp_kses_post()`. A name bound to a control that is neither Rich Text nor Classic Editor is printed with `esc_html()`, so a tag typed into a plain Text control shows as text on the front end.

## Notes

- The control keeps appearing wherever its **Placement** setting puts it. Content places it in the canvas beside the component, Inspector puts it in the sidebar.
- The component warns in the browser console when `name` is missing, names an attribute the block already has, names a Repeater child, or names a control that does not hold text.

---

# PHP Callback

Source: https://www.lazyblocks.com/docs/blocks-code/php-callback/

PHP callbacks let you handle block rendering with custom PHP functions instead of using the block builder's code editor. This approach is perfect for placing block logic in your theme or plugin files.

## Basic Usage

Replace `my-block` with your block slug and `render_my_block` with your unique function name:

```php title="functions.php"
// Frontend output callback
add_filter('lazyblock/my-block/frontend_callback', 'render_my_block', 10, 2);

// Editor preview callback
add_filter('lazyblock/my-block/editor_callback', 'render_my_block', 10, 2);

if (!function_exists('render_my_block')) :
    /**
     * Block render callback
     *
     * @param string $output     Default block output
     * @param array  $attributes Block attributes
     */
    function render_my_block($output, $attributes) {
        ob_start();
        ?>
        <div class="my-block">
            <?php if (isset($attributes['title'])) : ?>
                <h2><?php echo esc_html($attributes['title']); ?></h2>
            <?php endif; ?>

            <?php if (isset($attributes['content'])) : ?>
                <div class="content">
                    <?php echo wp_kses_post($attributes['content']); ?>
                </div>
            <?php endif; ?>
        </div>
        <?php
        return ob_get_clean();
    }
endif;
```

## Custom Wrappers

### Block Wrapper

By default, Lazy Blocks adds a wrapper to your block output. Disable it with:

```php
add_filter('lazyblock/my-block/frontend_allow_wrapper', '__return_false');
```

### Inner Blocks Wrapper

For blocks using Inner Blocks, disable the default wrapper:

```php
add_filter('lazyblock/my-block/allow_inner_blocks_wrapper', '__return_false');
```

## Advanced Example

```php
add_filter('lazyblock/team-member/frontend_callback', 'render_team_member', 10, 2);

function render_team_member($output, $attributes) {
    // Ensure required data exists
    if (!isset($attributes['name']) || !isset($attributes['role'])) {
        return '';
    }

    // Prepare data
    $name = esc_html($attributes['name']);
    $role = esc_html($attributes['role']);
    $image = isset($attributes['image']['url']) ? $attributes['image']['url'] : '';
    $bio = isset($attributes['bio']) ? wp_kses_post($attributes['bio']) : '';

    ob_start();
    ?>
    <div class="team-member">
        <?php if ($image) : ?>
            <div class="photo">
                <img src="<?php echo esc_url($image); ?>"
                     alt="<?php echo esc_attr($name); ?>">
            </div>
        <?php endif; ?>

        <div class="info">
            <h3 class="name"><?php echo $name; ?></h3>
            <div class="role"><?php echo $role; ?></div>
            <?php if ($bio) : ?>
                <div class="bio"><?php echo $bio; ?></div>
            <?php endif; ?>
        </div>
    </div>
    <?php
    return ob_get_clean();
}
```

Use PHP callbacks when you need:
- Complex dynamic content
- Integration with other WordPress functions
- Custom database queries
- Advanced data processing

---

# Blocks Screen

Source: https://www.lazyblocks.com/docs/managing-blocks/blocks-screen/

**WordPress Admin → Lazy Blocks → Blocks** lists every block on the site. Its columns are Icon, Title, Slug, Category and Description, there is no Quick Edit on a row, and **Add Block** opens the [block builder](https://www.lazyblocks.com/docs/create-block/).

## Active and inactive

A block has two usable states. `publish` means active, `draft` means inactive, and every other status is reset back to `draft` when the post is saved, so Pending, Private and Scheduled never apply to a block.

The view links above the table read **Active** and **Inactive** rather than Published and Draft, and an inactive block carries an `Inactive` label after its title.

Each row carries one link for the switch, **Deactivate** while the block is active and **Activate** otherwise. It takes the `edit_lazyblock` capability for that block. Both are bulk actions as well, so a whole selection flips at once, minus any block the user cannot edit.

After the redirect the screen prints a notice. A single block gives `Block "Pricing Table" activated successfully.`, a selection gives `Activated 3 blocks`.

## What an inactive block stops doing

Deactivating is not a soft switch. An inactive block is never registered at all, in the admin as well as on the front end.

Three things follow:

- The block is missing from the editor inserter.
- Posts that already use it hold a block name that is no longer registered, so the editor cannot render it.
- On the front end those posts print the block's inner blocks and nothing else, because a lazy block saves no markup of its own.

A block you saved but never published is inactive, which is the usual answer to a block that will not show up in the inserter.

## Duplicate

**Duplicate** is a row action with no bulk equivalent. It takes the `edit_lazyblocks` capability, plus the right to edit the block being copied (`edit_lazyblock`, and `edit_other_lazyblocks` for a block another user created). It reports `Added new block 'Pricing Table (Copy)'.`

The copy takes the original's post fields, every taxonomy term and its post meta. Three things change:

- `post_author` becomes the user who clicked, not the original author.
- The title gains a ` (Copy)` postfix, and only when it does not already contain one. Duplicating a copy therefore leaves two blocks under the same title.
- The copy gets a slug of its own, so the two blocks never register under one name.

A copy of `lazyblock/my-block` registers as `lazyblock/my-block-2` and arrives **Inactive**. With Pro the prefix can be something other than `lazyblock`, which [Collections & Namespaces](https://www.lazyblocks.com/docs/managing-blocks/collections/) covers.

## Export

**Export** on a row downloads that one block as JSON, and it is a bulk action too. Both need `edit_lazyblocks`. The full [Export / Import](https://www.lazyblocks.com/docs/export-blocks/) screen under the same menu is gated separately on `manage_options`, so a user who can build blocks may still be unable to open it.

## Clear Cache

**Clear Cache** sits with the view links above the table and empties the blocks cache. It needs `manage_options`. Saving a block clears the same cache on its own, so this link is for the cases where something else changed. [Performance](https://www.lazyblocks.com/docs/performance/) lists them.

## Who can build blocks

The `lazyblocks` post type declares its own capabilities instead of reusing the ones for posts:

| Capability                | Standard capability  | Needed for                                           |
| ------------------------- | -------------------- | ---------------------------------------------------- |
| `edit_lazyblocks`         | `edit_posts`         | the Blocks menu, the list screen, and adding a block |
| `edit_lazyblock`          | `edit_post`          | opening one block in the builder, and the row switch |
| `publish_lazyblocks`      | `publish_posts`      | publishing a block from the builder                  |
| `edit_other_lazyblocks`   | `edit_others_posts`  | blocks another user created                          |
| `read_lazyblock`          | `read_post`          | reading one block                                    |
| `read_private_lazyblocks` | `read_private_posts` | reading private blocks                               |
| `delete_lazyblocks`       | `delete_posts`       | deleting blocks                                      |
| `delete_lazyblock`        | `delete_post`        | deleting one block                                   |

The plugin hands these out on activation:

| Capability                | Administrator | Editor | Author | Contributor | Subscriber |
| ------------------------- | ------------- | ------ | ------ | ----------- | ---------- |
| `edit_lazyblocks`         | yes           | -      | -      | -           | -          |
| `edit_lazyblock`          | yes           | -      | -      | -           | -          |
| `edit_other_lazyblocks`   | yes           | -      | -      | -           | -          |
| `publish_lazyblocks`      | yes           | -      | -      | -           | -          |
| `read_lazyblock`          | yes           | yes    | yes    | yes         | -          |
| `read_private_lazyblocks` | yes           | yes    | yes    | yes         | -          |
| `delete_lazyblocks`       | yes           | -      | -      | -           | -          |
| `delete_lazyblock`        | yes           | -      | -      | -           | -          |

Only the Administrator can build a block out of the box. Editor, Author and Contributor get the two read capabilities and nothing else, and Subscriber gets none. There is no screen for changing this, and the plugin only ever adds capabilities, so anything you take away stays away.

Grant the rest in code. `add_cap()` writes to the database, so guard it rather than running it on every request:

```php title="PHP"
function my_lzb_grant_editor_caps() {
  if ( get_option( 'my_lzb_editor_caps_done' ) ) {
    return;
  }

  $role = get_role( 'editor' );

  if ( ! $role ) {
    return;
  }

  // Enough to open the Blocks screen, add a block, save it and publish it.
  $role->add_cap( 'edit_lazyblocks' );
  $role->add_cap( 'edit_lazyblock' );
  $role->add_cap( 'publish_lazyblocks' );

  update_option( 'my_lzb_editor_caps_done', 1 );
}

add_action( 'init', 'my_lzb_grant_editor_caps' );
```

Add `edit_other_lazyblocks` when the user should work on blocks somebody else built, and `delete_lazyblocks` with `delete_lazyblock` when they should be able to remove blocks. The `lazyblocks_templates` post type declares the same eight capabilities, so the Templates screen follows the Blocks screen with no extra grants.

Leave `publish_lazyblocks` out and the builder offers no Publish button, so a new block stays inactive. The row **Activate** link takes `edit_lazyblock` alone and still switches the block on.

---

# Collections & Namespaces

Source: https://www.lazyblocks.com/docs/managing-blocks/collections/

Every block in WordPress has one global name, and Lazy Blocks builds yours as `lazyblock/` plus the slug. A collection replaces that prefix, so a block registers as `acme/pricing-table` and, if you ask for it, gets its own group in the inserter.

## How a slug becomes a block name

The rule is one character. A slug holding a `/` becomes the registered block name exactly as it stands. A slug without one gets the `lazyblock/` prefix.

The slug is cleaned up when the block is saved. Each part keeps only letters, numbers and hyphens and is lowercased, and a slug with more than one `/` loses everything after its first part. So `a/b/c` is saved as `a`, and the block registers as `lazyblock/a`. There is no warning. Keep a slug to one namespace and one name.

| Typed in the Slug field  | Stored slug          | Registered block name     |
| ------------------------ | -------------------- | ------------------------- |
| `pricing-table`          | `pricing-table`      | `lazyblock/pricing-table` |
| `acme/pricing-table`     | `acme/pricing-table` | `acme/pricing-table`      |
| `acme/pro/pricing-table` | `acme`               | `lazyblock/acme`          |

## Picking a collection in the block builder

Pro replaces the plain **Slug** field in the block builder's inspector with a `{namespace}/` prefix button next to the text input. The button opens a dropdown headed **Collections & namespaces** holding a radio list of every known collection plus a **Custom** row with a free-text namespace field.

Picking the built-in **Lazy Blocks** collection stores the bare slug with no prefix at all, which is what makes `lazyblock/` the fallback rather than a stored value. Typing a namespace into the Custom row and pressing **Save for reuse** adds it to the list for the next block.

An editable row exposes **Label**, **Namespace**, a **Register collection** checkbox and **Save**, **Cancel** and **Delete**. The checkbox is what gives the collection its own group heading in the inserter. Nothing is stored when you press **Save** in that dropdown. The list is written when the block itself is saved.

## Registering a collection from PHP

`lazyblocks()->add_collection()` puts a collection in the list without an admin visit, which is how you ship one with a theme or a plugin. The method exists in the free plugin too, where it fires [lzb/add_collection](https://www.lazyblocks.com/docs/php-actions/lzb-add_collection/) and nothing else. Pro is what acts on it.

| Key         | Type        | Description                                                           |
| ----------- | ----------- | --------------------------------------------------------------------- |
| `namespace` | **String**  | the prefix, required                                                  |
| `label`     | **String**  | the name shown in the dropdown and in the inserter group, required    |
| `register`  | **Boolean** | give the collection its own group in the inserter, `false` by default |

```php title="PHP"
function my_lzb_collections() {
  lazyblocks()->add_collection(
    array(
      'namespace' => 'acme',
      'label'     => 'Acme Blocks',
      'register'  => true,
    )
  );
}

add_action( 'init', 'my_lzb_collections' );
```

`init` is early enough, and so is [lzb/init](https://www.lazyblocks.com/docs/php-actions/lzb-init/). An `isDefault` key is accepted and carried through, but nothing in 4.4.1 reads it, so setting it changes nothing.

## A collection from PHP cannot be edited in the admin

A collection you registered from PHP shows in the dropdown with no Edit control, and cannot be deleted there either. Change it in your code instead.

A namespace registered from PHP also takes over one of the same name saved from the admin, and replaces it in the list.

## Renaming a namespace breaks saved content

  Renaming a namespace changes the registered block name on the next request.
  Nothing rewrites the content that already uses the old name.

Lazy Blocks registers no alias and no deprecation for a previous block name. A post saved with `acme/pricing-table` in it keeps that name in its markup, and once the block registers as `acme-inc/pricing-table` the old name is not registered by anything, so the editor cannot resolve it and the front end has only the block's inner blocks left to print. Fixing it means a search and replace across post content, so pick a namespace before you build on it.

Editing a collection also rewrites the slug of the block that is open in the builder at the time, and only that one. Every other block that used the namespace keeps the old value until you open and save it.

Deactivating Pro changes the registered name too. The `/` rule goes with it, so a stored `acme/pricing-table` becomes `lazyblock/acme/pricing-table`. WordPress rejects a block name with two slashes, and those blocks are then not registered at all. See the [Blocks Screen](https://www.lazyblocks.com/docs/managing-blocks/blocks-screen/) for what an unregistered block does to a page, and [Create Block](https://www.lazyblocks.com/docs/create-block/) for the rest of the builder's General settings.

---

# Export / Import

Source: https://www.lazyblocks.com/docs/export-blocks/

Blocks and templates leave the site as a JSON file for another WordPress install, or as PHP code to keep in a theme or a plugin.

The screen is **Admin Menu → Lazy Blocks → Export / Import** and opening it takes the `manage_options` capability. Blocks and templates are exported apart from each other, each to its own file.

## Export options

### JSON export

**Export JSON** downloads the selection as one file, named after what it holds and the day it was made, `lzb-export-blocks-2026-09-09.json` for blocks and `lzb-export-templates-2026-09-09.json` for templates. This is the file the Import box takes, so JSON is the format for moving blocks to another site.

### PHP export

**Generate PHP** gives you code to keep in a theme or a plugin, and under version control with it.

  The Lazy Blocks plugin must be active for exported PHP code to work.

The code is a single `add_action( 'lzb/init', ... )` wrapper with one call inside it per selected item:

```php title="PHP"
add_action( 'lzb/init', function() {
    lazyblocks()->add_block( array(
        'title'    => 'Testimonial',
        'slug'     => 'lazyblock/testimonial',
        'icon'     => '<svg xmlns="http://www.w3.org/2000/svg" ...></svg>',
        'category' => 'text',
        'controls' => array(
            array(
                'type'      => 'text',
                'name'      => 'author',
                'label'     => 'Author',
                'placement' => 'inspector',
            ),
        ),
        // The rest of the block settings follow here.
    ) );
} );
```

Templates use the same wrapper and `add_template()` instead:

```php title="PHP"
add_action( 'lzb/init', function() {
    lazyblocks()->add_template( array(
        'title'         => 'Product Page',
        'post_types'    => array( 'product' ),
        'template_lock' => 'insert',
        'blocks'        => array(
            array( 'lazyblock/testimonial' ),
        ),
    ) );
} );
```

## Export methods

### Single block export

Export individual blocks directly from the blocks list:

That row link only takes `edit_lazyblocks`, so somebody who cannot open the Export / Import screen can still export one block from the [blocks screen](https://www.lazyblocks.com/docs/managing-blocks/blocks-screen/).

### Bulk export

Export multiple blocks at once using bulk selection:

### Template export

The **Export Templates** box is only rendered when the site has at least one [template](https://www.lazyblocks.com/docs/templates/). It carries the same **Export JSON** and **Generate PHP** buttons as the blocks box and writes a separate file.

## Import

The Import box takes one `.json` file, and the extension is the only thing checked before the file is read. A file that does not decode to an array is reported as `Import file empty`. A file that decodes but holds nothing Lazy Blocks recognises imports nothing and reports nothing.

- Imported blocks arrive published, which is **Active** on the blocks screen.
- Blocks are not deduplicated. Importing the same file twice gives you two copies of every block in it.
- A template is refused when an existing template already covers one of its post types, with the notice `Template for these post types 'product' already exists.`

To change the data on its way in, filter the decoded file with [lzb/import_json](https://www.lazyblocks.com/docs/php-filters/lzb-import_json/), or act on each new block with [lzb/import/block](https://www.lazyblocks.com/docs/php-actions/lzb-import-block/).

## Try demo blocks

Download our demo blocks package containing examples of all available controls:

  Download Demo Blocks

  After downloading, unzip the file before importing into WordPress.

---

# Deprecated Templates

Source: https://www.lazyblocks.com/docs/templates/

Templates are **deprecated** since v4.0.0. You need to migrate to the WordPress FSE theme and use Template editor natively. Learn more -> [https://wordpress.org/documentation/article/template-editor/](https://wordpress.org/documentation/article/template-editor/).<br />Our implementation will still work for existing sites, but it is deprecated for future use.

Templates let you define a default set of blocks for specific post types. This ensures consistency across your content and speeds up the content creation process.

## Creating Templates

1. Navigate to **WordPress Admin → Lazy Blocks → Templates**
2. Click **Add New**

   

3. Configure template settings:

   - Template Name
   - Add blocks
   - Select Post Types
   - Choose Template Lock option

   

## Template Lock Options

- **None** - Users can freely modify blocks
- **Prevent all operations** - Users cannot add, delete, or move blocks
- **Prevent inserting new blocks** - Users can move existing blocks but cannot add new ones

## Working with Templates

When you create a new post of the selected type, it automatically includes the template blocks:

  <figcaption>New post with pre-populated template blocks</figcaption>

## Adding Flexible Content Areas

Use the **Free Content** block to create editable areas within locked templates:

Common template uses:
- Standard page layouts
- Product descriptions
- Team member profiles
- Case study format

Template locks help maintain consistency while still allowing necessary content flexibility.

---

# Multilingual

Source: https://www.lazyblocks.com/docs/multilingual/

WPML translates the values of a block's text controls along with the rest of the post, once translation is turned on for each control.

## Setting up translation

### 1. Enable translation on a control

Each control needs translation enabled manually:

1. Edit your block
2. Find the control you want to translate
3. Enable the `WPML Translation` toggle

The toggle is offered on eight control types: Classic Editor, Code Editor, Date Time, Email, Rich Text, Text, Textarea and URL. Every other type hides the setting, and its value never reaches WPML.

### 2. Translate content

Once your blocks are translation-ready:

1. Open the page with your block
2. Find the `Language` settings in the `Page` panel

  <figcaption>Access page translation options</figcaption>

### 3. Manage translations

Use WPML's interface to translate your block content:

  <figcaption>Translate block content in WPML</figcaption>

### 4. View results

Your translated block will appear in the selected language:

  <figcaption>Block content displayed in different language</figcaption>

## Repeaters

A repeater has no WPML Translation toggle of its own, and the plugin never reads one. Turn translation on for any control inside it and the whole repeater goes to WPML, every row of it, so four rows and forty rows behave the same. A repeater nested in another repeater is walked to any depth.

## The RichText component

A name owned by the [`` component](https://www.lazyblocks.com/docs/blocks-code/rich-text/) works the other way round. It is translatable by default, and the tag opts out:

```html
<RichText name="internal-note" tagName="p" translate="false" />
```

Opting out on one tag applies to that name everywhere in the block. A name that is backed by a control is left alone and keeps the control's own setting.

For a block attribute that is neither a control nor a `` name, add it with [lzb/wpml/translated_attributes](https://www.lazyblocks.com/docs/php-filters/lzb-wpml-translated_attributes/).

## Requirements

WPML has to be set up for Gutenberg blocks before any of this works. Until it is, Lazy Blocks writes nothing into WPML and a block's controls stay untranslated whatever their toggles say.

  Translation is off by default on every control, so turn it on for each control
  you want WPML to pick up. Repeaters and `` names are the two
  exceptions.

---

# SEO Plugins

Source: https://www.lazyblocks.com/docs/integrations/seo-plugins/

Yoast SEO and Rank Math score a page by reading the post content in the editor. A page built out of lazy blocks holds almost no readable text there, so without this integration it scores as though it had none.

## Why the analysis needs help

A lazy block stores its values, not its output. Every heading, paragraph and image the block prints is produced when the block renders, so what sits in the post content is a comment holding the block's settings. No readability or keyword check can do anything with that.

With Pro active the two plugins are given the block's real rendered HTML instead. Headings count as headings, links and images are found, and the word count matches the published page.

## Turning it on

There is nothing to turn on. Pro adds this by itself when Yoast SEO or Rank Math is active, and does nothing when neither is.

It works whatever your blocks are written in. The HTML the analysis reads comes from a real render on the server, so a block built from a PHP callback or a theme template is covered exactly like one written in HTML.

## What it does not do

- **Position is not preserved.** The rendered HTML is added to the end of the content the analysis reads, not in the place the block sits. A check that cares about where something appears, such as the keyword in the first paragraph, will read the wrong paragraph.
- **Block editor only.** The classic editor gets none of this.
- **Inner blocks come along with their parent.** A block nested inside another is covered as far as the parent's own output includes it, and not separately.

## Relation to preloading

The integration reuses whatever [editor block preloading](https://www.lazyblocks.com/docs/performance/) has already rendered, so the two work best together. Turning preloading off does not break it:

```php title="PHP"
add_filter( 'lzb_pro/preload_blocks', '__return_false' );
```

Each block is then fetched when the editor loads it, which leaves the analysis a moment behind your edits.

Nothing here changes what is saved or what visitors see. The extra HTML exists only inside the text the two plugins read.

---

# Abilities API

Source: https://www.lazyblocks.com/docs/integrations/abilities-api/

On WordPress 6.9 and later, Lazy Blocks registers four [abilities](https://developer.wordpress.org/apis/abilities-api/). An AI agent or any other client that speaks the Abilities API can list your blocks, read one, create one and update one, without opening the block builder. On older WordPress versions the abilities are not registered and nothing changes.

The abilities belong to the `lazy-blocks` category and are shown in the REST API, so a client reaches them through the `wp-abilities/v1` routes or through an MCP adapter that exposes WordPress abilities.

## Abilities

| Ability                     | What it does                                                                                       | Who can run it                                                       |
| --------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `lazy-blocks/list-blocks`   | Returns every block with its ID, title, status and slug                                            | users with `edit_lazyblocks`                                         |
| `lazy-blocks/get-block`     | Returns one block by ID with all its builder data: controls, code, supports, styles and condition | users with `edit_lazyblocks`                                         |
| `lazy-blocks/create-block`  | Creates a block from a title and optional builder data, and publishes it                           | users with `edit_lazyblocks` and `publish_lazyblocks`                |
| `lazy-blocks/update-block`  | Changes the title or builder data of a block by ID                                                 | users with `edit_lazyblocks` who can edit that block                 |

Out of the box only the Administrator has these capabilities. [Blocks Screen](https://www.lazyblocks.com/docs/managing-blocks/blocks-screen/) shows how to grant them to another role.

## Block data

`get-block` returns the block in the format the block builder saves: `id`, `title`, `status` and a `data` object. `create-block` and `update-block` take the same `data` object. The keys an agent uses most are:

| Key                  | Holds                                                     |
| -------------------- | --------------------------------------------------------- |
| `slug`               | the block name after the namespace, such as `pricing-table` |
| `icon`               | the block icon                                            |
| `description`        | the description shown in the block inspector              |
| `keywords`           | search keywords, separated by commas                      |
| `category`           | the inserter category                                     |
| `controls`           | the block controls, keyed by control ID                   |
| `code_output_method` | `html`, `php` or `template`                               |
| `code_frontend_html` | the frontend code                                         |
| `code_editor_html`   | the editor code                                           |
| `code_single_output` | `true` when one code is used for the editor and the frontend |
| `style_block`        | the block CSS                                             |
| `style_editor`       | the editor CSS                                            |
| `script_view`        | the frontend JavaScript                                   |

Every other key the builder stores is accepted as well. The ability's own input schema lists all of them.

## Creating and updating blocks

A new block takes the builder defaults for every key the agent leaves out. Without a `slug`, the slug is built from the title, as the builder does.

An update changes only the top-level keys it is given, and replaces each of them whole. To add one control, an agent reads the block with `get-block`, adds the control to `controls` and sends the full `controls` object back. Sending only the new control removes the others.

A slug must use lowercase letters, numbers and dashes, and start with a letter. A slug another block already uses is refused, so two blocks never register under one name.

  A block whose `code_output_method` is `php` runs its code as PHP on your site. Let an agent create or update blocks only on a site where you would let the same user write PHP in the block builder.

---

# Performance

Source: https://www.lazyblocks.com/docs/performance/

Lazy Blocks caches in two places, and each answers a different complaint. Editor preloading is why block previews can appear with the page instead of one request per block. The blocks cache is why a change to a block can keep showing the old output.

## Editor block preloading 

Without it, every lazy block on the page asks the server for its preview when the editor opens. A post holding twenty of them opens with twenty requests, which is the cause behind [Receive a 504 and 429 error Too Many Requests](https://www.lazyblocks.com/docs/troubleshooting/receive-a-504-and-429-error-too-many-requests/).

With Pro active the previews are rendered once while the edit screen loads and handed to the editor with the page, so the first draw of every block costs no request at all. Editing a block afterwards fetches its preview as usual.

Inner blocks are the exception. A block using an [Inner Blocks](https://www.lazyblocks.com/docs/blocks-code/inner-blocks/) area is preloaded without its children, because preloaded child markup and the live preview fight each other and the live one has to win.

The feature is on by default. Turn it off when you are debugging a preview that will not refresh:

```php title="PHP"
add_filter( 'lzb_pro/preload_blocks', '__return_false' );
```

Previews then load one request at a time again, and the [Yoast and Rank Math integration](https://www.lazyblocks.com/docs/integrations/seo-plugins/), which reuses the same rendered HTML, falls back to fetching its own. See [lzb_pro/preload_blocks](https://www.lazyblocks.com/docs/php-filters/lzb_pro-preload_blocks/).

## The blocks cache

Building the list of blocks means reading every block you have made and turning it into block data and controls. That result is cached for a day, so the work happens once rather than on every request.

[lzb/cache_expiration](https://www.lazyblocks.com/docs/php-filters/lzb-cache_expiration/) changes how long it lasts. Return `0` and the list is rebuilt every request, which is worth doing while developing and not worth doing in production.

Blocks registered from PHP with `lazyblocks()->add_block()` are never cached. They are rebuilt on every request, so they cannot go stale.

The cache clears itself when:

- a block is saved
- a block is deleted, trashed or untrashed
- any plugin is activated or deactivated
- the theme is switched
- any plugin or theme is upgraded

You can also clear it from **Clear Cache** on the [Blocks screen](https://www.lazyblocks.com/docs/managing-blocks/blocks-screen/), or from your own code:

```php title="PHP"
lazyblocks()->blocks()->clear_blocks_cache();
```

[lzb/cache_cleared](https://www.lazyblocks.com/docs/php-actions/lzb-cache_cleared/) fires afterwards, for anything of yours that caches on top.

Saving a block in the builder clears the cache, so a block that still shows its old output was almost certainly changed some other way. Writing block meta directly with `update_post_meta()` is the usual culprit: it triggers none of the events above, and the old list stands until the day is out.

---

# lzb/block_data

Source: https://www.lazyblocks.com/docs/php-filters/lzb-block_data/

Adds a key to a block after Lazy Blocks has assembled it from post meta, which is how a custom setting saved on the block builder screen reaches the rest of the plugin.

It fires once per block inside `marshal_block_data_with_controls()`, for blocks created in the builder and for blocks registered from PHP alike. Everything downstream reads the array this filter returns, so a key added here is visible to the render callback, to `register_block_type()` and to the editor. Lazy Blocks Pro uses it for exactly this. The Relationships feature adds `provide_context_to_blocks`, `custom_context_slug`, `allowed_blocks` and `ancestor` at priority 12, and the custom slug namespace feature rewrites `slug` at priority 10.

## Attributes

| Name              | Type         | Description                                     |
| ----------------- | ------------ | ----------------------------------------------- |
| `$block_data`     | **Array**    | assembled block, see the keys below             |
| `$get_meta_value` | **Callable** | reads one raw meta value for this block by name |

| Key              | Type            | Description                                                                                                                                                              |
| ---------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`             | **Int \| null** | post ID, `null` for a block registered from PHP                                                                                                                          |
| `title`          | **String**      | block name in the inserter                                                                                                                                               |
| `icon`           | **String**      | SVG markup or a Dashicons name                                                                                                                                           |
| `keywords`       | **Array**       | extra inserter search terms                                                                                                                                              |
| `slug`           | **String**      | full block name, for example `lazyblock/alert-block`                                                                                                                     |
| `description`    | **String**      | text under the block name in the inspector                                                                                                                               |
| `category`       | **String**      | sanitised category slug                                                                                                                                                  |
| `category_label` | **String**      | category name as typed in the builder                                                                                                                                    |
| `supports`       | **Array**       | `customClassName`, `anchor`, `html`, `multiple`, `inserter`, `reusable`, `color`, `layout`, `shadow`, `spacing`, `dimensions`, `typography`, `lock`, `align`, `ghostkit` |
| `controls`       | **Array**       | controls keyed by control ID, already merged with their type defaults                                                                                                    |
| `code`           | **Array**       | `output_method`, `editor_html`, `editor_callback`, `frontend_html`, `frontend_callback`, `show_preview`, `single_output`                                                 |
| `style`          | **Array**       | `block` and `editor` CSS strings                                                                                                                                         |
| `script`         | **Array**       | `view` JavaScript string                                                                                                                                                 |
| `styles`         | **Array**       | block style variations                                                                                                                                                   |
| `condition`      | **Array**       | post types the block is limited to                                                                                                                                       |
| `edit_url`       | **String**      | block builder link for this block                                                                                                                                        |

`$get_meta_value` takes one raw meta name and returns its value with the block defaults already applied, so `$get_meta_value( 'lazyblocks_slug' )` gives the slug without the namespace.

## Usage

```php title="PHP"
function my_lzb_block_data( $block_data, $get_meta_value ) {
  // Surface a meta field added by a custom block builder panel, so the
  // render callback and register_block_type() can both see it.
  $block_data['my_wrapper_tag'] = $get_meta_value( 'lazyblocks_my_wrapper_tag' );

  if ( ! $block_data['my_wrapper_tag'] ) {
    $block_data['my_wrapper_tag'] = 'div';
  }

  return $block_data;
}

add_filter( 'lzb/block_data', 'my_lzb_block_data', 10, 2 );
```

`get_blocks()` caches its result in a transient for a day. The cache key is a hash that counts the priorities registered on this filter, so adding a handler at a priority nothing else uses invalidates the cache on its own, while a second handler at priority 10 lands in an existing bucket and keeps serving stale data until [lzb/cache_expiration](https://www.lazyblocks.com/docs/php-filters/lzb-cache_expiration/) runs out or a block is saved. Dropping the `slug` key removes the block from the editor entirely, because `register_block()` filters out blocks whose slug has no name after the namespace.

The neighbouring stages are [lzb/block_defaults](https://www.lazyblocks.com/docs/php-filters/lzb-block_defaults/) for the fallback values, [lzb/prepare_block_attribute](https://www.lazyblocks.com/docs/php-filters/lzb-prepare_block_attribute/) for one control's attribute, and [lzb/register_block_type_data](https://www.lazyblocks.com/docs/php-filters/lzb-register_block_type_data/) for the registration array.

---

# lzb/block_defaults

Source: https://www.lazyblocks.com/docs/php-filters/lzb-block_defaults/

Changes the value a block setting falls back to when the block builder never saved one, which is how a site sets its own house style for every new block at once.

This is the earliest of the four filters that shape a block. It runs inside `get_block_defaults()`, before any meta is read, so its result is only consulted when the stored meta is an empty string. Turning on `lazyblocks_supports_anchor` here gives an anchor field to every block that has never had the setting touched, and stops affecting a block the moment somebody saves that setting in the builder.

## Attributes

| Name              | Type      | Description                                               |
| ----------------- | --------- | --------------------------------------------------------- |
| `$block_defaults` | **Array** | fallback values, keyed by the raw `lazyblocks_` meta name |

The keys are meta names, not the block data keys. `lazyblocks_slug`, `lazyblocks_icon`, `lazyblocks_description`, `lazyblocks_keywords`, `lazyblocks_category`, `lazyblocks_controls`, `lazyblocks_styles`, `lazyblocks_condition_post_types`, the `lazyblocks_code_*` group (`show_preview`, `single_output`, `output_method`, `editor_html`, `editor_callback`, `frontend_html`, `frontend_callback`), the `lazyblocks_style_*` and `lazyblocks_script_*` pair, and one `lazyblocks_supports_*` entry per block support.

Booleans are stored as the strings `'true'` and `'false'`, and `get_meta_value()` converts them afterwards. `lazyblocks_supports_align` is the exception, an array holding `wide` and `full` by default.

## Usage

```php title="PHP"
function my_lzb_block_defaults( $block_defaults ) {
  // Every block that has never had these settings saved gets an anchor
  // field and no wide alignments.
  $block_defaults['lazyblocks_supports_anchor'] = 'true';
  $block_defaults['lazyblocks_supports_align']  = array();

  return $block_defaults;
}

add_filter( 'lzb/block_defaults', 'my_lzb_block_defaults' );
```

A boolean default written as a real `true` rather than the string `'true'` never survives the round trip, because `get_meta_value()` only maps the strings. Removing a key altogether means the setting has no default at all and stays an empty string.

The assembled block list is cached in a transient, and its key counts the priorities registered on this filter. A handler at a priority nothing else uses invalidates that cache by itself. A second handler at priority 10 does not, so clear the cache or wait out [lzb/cache_expiration](https://www.lazyblocks.com/docs/php-filters/lzb-cache_expiration/) before the change shows up.

The three later stages are [lzb/block_data](https://www.lazyblocks.com/docs/php-filters/lzb-block_data/), which sees the assembled block, [lzb/prepare_block_attribute](https://www.lazyblocks.com/docs/php-filters/lzb-prepare_block_attribute/), which sees one control at a time, and [lzb/register_block_type_data](https://www.lazyblocks.com/docs/php-filters/lzb-register_block_type_data/), which sees what goes to `register_block_type()`.

---

# lzb/add_user_block

Source: https://www.lazyblocks.com/docs/php-filters/lzb-add_user_block/

Filters the array handed to `lazyblocks()->add_block()`, before Lazy Blocks stores it.

A theme that registers a dozen blocks from PHP repeats the same `category` and `supports` in every array. Use this filter to set them in one place, or to change a block another plugin registers without touching its source.

## Attributes

| Name    | Type      | Description                            |
| ------- | --------- | -------------------------------------- |
| `$data` | **Array** | block data, as passed to `add_block()` |

The returned array is merged over the block defaults inside `get_blocks()`, so any key you leave out keeps its default value. These are the keys Lazy Blocks reads:

| Name             | Type            | Description                                                                                                                                                              |
| ---------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`             | **Int \| null** | post ID, always `null` for a block registered from PHP                                                                                                                   |
| `title`          | **String**      | block name shown in the inserter                                                                                                                                         |
| `icon`           | **String**      | SVG markup or a Dashicons name                                                                                                                                           |
| `keywords`       | **Array**       | extra inserter search terms                                                                                                                                              |
| `slug`           | **String**      | full block name, for example `lazyblock/alert-block`                                                                                                                     |
| `description`    | **String**      | text under the block name in the inspector                                                                                                                               |
| `category`       | **String**      | block category slug                                                                                                                                                      |
| `category_label` | **String**      | category name shown in the inserter                                                                                                                                      |
| `supports`       | **Array**       | `customClassName`, `anchor`, `html`, `multiple`, `inserter`, `reusable`, `color`, `layout`, `shadow`, `spacing`, `dimensions`, `typography`, `lock`, `align`, `ghostkit` |
| `controls`       | **Array**       | controls, keyed by control ID                                                                                                                                            |
| `code`           | **Array**       | block output, see below                                                                                                                                                  |
| `style`          | **Array**       | `block` and `editor` CSS strings                                                                                                                                         |
| `script`         | **Array**       | `view` JavaScript string                                                                                                                                                 |
| `styles`         | **Array**       | block style variations                                                                                                                                                   |
| `condition`      | **Array**       | post types the block is restricted to                                                                                                                                    |
| `edit_url`       | **String**      | block builder link, empty for a block registered from PHP                                                                                                                |

`code` takes these keys:

| Name                | Type         | Description                                              |
| ------------------- | ------------ | -------------------------------------------------------- |
| `output_method`     | **String**   | `html`, `php` or `template`                              |
| `editor_html`       | **String**   | markup used in the editor preview                        |
| `editor_callback`   | **Callable** | function printing the editor preview                     |
| `frontend_html`     | **String**   | markup used on the front end                             |
| `frontend_callback` | **Callable** | function printing the front end output                   |
| `show_preview`      | **Boolean**  | render the preview in the editor instead of the controls |
| `single_output`     | **Boolean**  | use `frontend_html` in the editor as well                |

## Usage

```php title="PHP"
function my_lzb_add_user_block( $data ) {
  // Put every block registered from PHP in one category and give it the
  // same alignments, without repeating this in each add_block() call.
  $data['category']       = 'theme-blocks';
  $data['category_label'] = 'Theme Blocks';

  if ( ! isset( $data['supports']['align'] ) ) {
    $data['supports']['align'] = array( 'wide', 'full' );
  }

  return $data;
}

add_filter( 'lzb/add_user_block', 'my_lzb_add_user_block' );
```

The filter runs inside `add_block()`, so blocks created in the block builder never reach it. Those go through [lzb/block_data](https://www.lazyblocks.com/docs/php-filters/lzb-block_data/) instead. Returning anything but an array raises a `TypeError` at the `array_merge()` in `get_blocks()`. Lazy Blocks keeps its own callback here at priority 10, converting the pre-2.1.0 `code.use_php` boolean into `code.output_method`, so a handler registered at a lower priority still sees `use_php`.

Registering blocks from PHP is covered in [Include Lazy Blocks within theme or plugin](https://www.lazyblocks.com/docs/examples/include-lazy-blocks-within-theme-or-plugin/).

---

# lzb/add_user_template

Source: https://www.lazyblocks.com/docs/php-filters/lzb-add_user_template/

Filters the array handed to `lazyblocks()->add_template()`, before Lazy Blocks stores it.

A template registered from a theme is fixed in code, so a child theme or a plugin cannot widen its post types or change its lock. This filter is the place to do that.

## Attributes

| Name    | Type      | Description                                  |
| ------- | --------- | -------------------------------------------- |
| `$data` | **Array** | template data, as passed to `add_template()` |

`$data` takes the same keys a template read from the database has:

| Name            | Type       | Description                                                                       |
| --------------- | ---------- | --------------------------------------------------------------------------------- |
| `id`            | **Int**    | post ID, absent for a template registered from PHP                                |
| `title`         | **String** | template name shown on the Templates screen                                       |
| `post_types`    | **Array**  | post type slugs the template applies to                                           |
| `template_lock` | **String** | `all`, `insert`, or an empty string for no lock                                   |
| `blocks`        | **Array**  | block template array, each entry `array( 'core/heading', array( 'level' => 2 ) )` |

## Usage

```php title="PHP"
function my_lzb_add_user_template( $data ) {
  if ( ! isset( $data['title'] ) || 'Landing Page' !== $data['title'] ) {
    return $data;
  }

  // Reuse the landing page template on the `page` post type as well,
  // and stop editors from inserting blocks that are not in it.
  $data['post_types'][]   = 'page';
  $data['template_lock'] = 'insert';

  return $data;
}

add_filter( 'lzb/add_user_template', 'my_lzb_add_user_template' );
```

`register_post_type_args()` reads `post_types`, `blocks` and `template_lock` for every post type WordPress registers, not only for the Lazy Blocks ones, so dropping one of those keys throws an undefined-index warning on every `register_post_type()` call on the site. Lazy Blocks keeps its own callback here at priority 10, converting the pre-2.5.0 `data` sub-array: `data.post_type` becomes the `post_types` array, `data.template_lock` becomes `template_lock`, and each `array( 'name' => 'core/paragraph' )` entry becomes `array( 'core/paragraph' )`.

Templates are deprecated since v4.0.0, see [Templates](https://www.lazyblocks.com/docs/templates/).

---

# lzb/register_blocks

Source: https://www.lazyblocks.com/docs/php-filters/lzb-register_blocks/

Changes the block list the editor registers from, which is where a key has to be added for a JavaScript handler to read it back.

The result is localised as `window.lazyblocksGutenberg.blocks` and the editor loops over it calling `registerBlockType()`. It is the browser-side twin of [lzb/register_block_type_data](https://www.lazyblocks.com/docs/php-filters/lzb-register_block_type_data/), which shapes the same blocks for PHP. Only some keys are read directly. `title`, `description`, `icon`, `category`, `keywords`, `supports`, `condition` and `slug` build the registration arguments, and the whole item is handed to the block's edit component, so a key nothing in the editor knows about is still readable from the block data there.

## Attributes

| Name      | Type      | Description                                                                                      |
| --------- | --------- | ------------------------------------------------------------------------------------------------ |
| `$blocks` | **Array** | list of blocks, each one shaped like [lzb/block_data](https://www.lazyblocks.com/docs/php-filters/lzb-block_data/) returns |

`slug` is the full block name including the namespace and is what `registerBlockType()` is called with. `id` is the post ID, an integer, so match on `slug` rather than on `id` when picking one block out of the list. Lazy Blocks Pro adds `provides_context`, `uses_context`, `allowed_blocks` and `ancestor` here through its Relationships feature, and the JavaScript filter `lzb.registerBlockType.args` copies them onto the registration arguments.

## Usage

```php title="PHP"
function my_lzb_register_blocks( $blocks ) {
  // Let one block sit only inside a Group, and only take paragraphs.
  foreach ( $blocks as $key => $block ) {
    if ( 'lazyblock/faq-item' !== $block['slug'] ) {
      continue;
    }

    $blocks[ $key ]['ancestor']       = array( 'core/group' );
    $blocks[ $key ]['allowed_blocks'] = array( 'core/paragraph', 'core/heading' );
  }

  return $blocks;
}

add_filter( 'lzb/register_blocks', 'my_lzb_register_blocks' );
```

`ancestor` and `allowed_blocks` are read by the Pro Relationships script, so they do nothing without Pro. The list is JSON encoded for the browser, which turns a gapped array into an object and leaves the editor with no blocks at all, so reindex with `array_values()` after removing an item. Removing a block here hides it from the inserter but leaves it registered in PHP, so existing posts still render it.

The JavaScript side of the same registration is [lzb.registerBlockType.args](https://www.lazyblocks.com/docs/js-filters/lzb-registerblocktype-args/).

---

# lzb/register_block_type_data

Source: https://www.lazyblocks.com/docs/php-filters/lzb-register_block_type_data/

Adds a `register_block_type()` argument that the block builder has no field for, such as a stylesheet handle, a view script or a replacement render callback.

This is the last of the four block filters and the only one whose result reaches WordPress directly. `register_block_render()` builds the array, fires this filter, then calls `register_block_type( $block['slug'], $data )`. Lazy Blocks Pro hooks it twice, once to attach the CSS and JS handles built from a block's template folder, and once to swap in a render callback that forwards block context when the block uses Relationships.

## Attributes

| Name     | Type      | Description                                                                            |
| -------- | --------- | -------------------------------------------------------------------------------------- |
| `$data`  | **Array** | arguments about to be passed to `register_block_type()`                                |
| `$block` | **Array** | block data, the same array [lzb/block_data](https://www.lazyblocks.com/docs/php-filters/lzb-block_data/) returns |

`$data` holds these keys before any handler runs:

| Key               | Type         | Description                                                                                                                                                                                                     |
| ----------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api_version`     | **Int**      | always `3`                                                                                                                                                                                                      |
| `attributes`      | **Array**    | one entry per control, built by [lzb/prepare_block_attribute](https://www.lazyblocks.com/docs/php-filters/lzb-prepare_block_attribute/) plus the reserved `lazyblock`, `className`, `anchor`, `blockId` and `blockUniqueClass` attributes |
| `supports`        | **Array**    | the block's `supports` array                                                                                                                                                                                    |
| `render_callback` | **Callable** | closure calling `render_callback()` with the render location and the block context, limited to the keys listed in `uses_context`                                                                               |
| `example`         | **Array**    | empty, so the inserter preview renders with defaults                                                                                                                                                            |
| `styles`          | **Array**    | block style variations                                                                                                                                                                                          |
| `editor_script`   | **Array**    | `lazyblocks-editor`                                                                                                                                                                                             |
| `editor_style`    | **Array**    | `lazyblocks-editor`                                                                                                                                                                                             |

## Usage

```php title="PHP"
function my_lzb_register_block_type_data( $data, $block ) {
  // Attach a theme stylesheet to one block, so it loads only on pages
  // where the block is actually used.
  if ( 'lazyblock/pricing-table' !== $block['slug'] ) {
    return $data;
  }

  wp_register_style(
    'my-theme-pricing-table',
    get_stylesheet_directory_uri() . '/css/pricing-table.css',
    array(),
    '1.0.0'
  );

  $data['style'] = array( 'my-theme-pricing-table' );

  return $data;
}

add_filter( 'lzb/register_block_type_data', 'my_lzb_register_block_type_data', 10, 2 );
```

`style`, `editor_style` and `view_script` take handles that are already registered, not URLs, and Lazy Blocks Pro appends to those keys rather than replacing them, so read the existing value before overwriting one. Replacing `render_callback` with something that is not callable makes `register_block_type()` fail for that block and it never appears in the inserter. Removing `attributes` leaves the block unable to read any of its own control values.

This filter shapes the server side only. The array the editor registers blocks from goes through [lzb/register_blocks](https://www.lazyblocks.com/docs/php-filters/lzb-register_blocks/).

---

# lzb/prepare_block_attribute

Source: https://www.lazyblocks.com/docs/php-filters/lzb-prepare_block_attribute/

Sets the storage type and default of the Gutenberg attribute behind one control, which a custom control needs when its value is not a plain string.

It runs once per control while the attribute list for `register_block_type()` is built, after [lzb/block_data](https://www.lazyblocks.com/docs/php-filters/lzb-block_data/) has assembled the block and before [lzb/register_block_type_data](https://www.lazyblocks.com/docs/php-filters/lzb-register_block_type_data/) sees the finished registration array. Two loops fire it. `prepare_block_attributes()` handles the controls stored in the block markup, and `prepare_block_meta_attributes()` handles the ones with **Save in Meta** on, whose `$attribute_data` carries the extra `source` and `meta` keys.

## Attributes

| Name              | Type       | Description                                                                            |
| ----------------- | ---------- | -------------------------------------------------------------------------------------- |
| `$attribute_data` | **Array**  | `type` and `default`, plus `source` and `meta` for a meta control                      |
| `$control`        | **Array**  | this control, merged with its type's defaults                                          |
| `$controls`       | **Array**  | every control on the block, keyed by control ID                                        |
| `$k`              | **String** | control ID of `$control` inside `$controls`                                            |
| `$block`          | **Array**  | block data, the same array [lzb/block_data](https://www.lazyblocks.com/docs/php-filters/lzb-block_data/) returns |

`$attribute_data['type']` comes from the control type's own `type` property and is one of `string`, `number`, `boolean`, `array` or `object`. `$attribute_data['default']` is the control's `default` value, cast to a float when the type is `number` and the default is not an empty string.

`$control` always has `type`, `name`, `default`, `label`, `help`, `child_of`, `placement`, `group`, `width`, `hide_if_not_selected`, `required`, `translate`, `save_in_meta` and `save_in_meta_name`, because the type's defaults are merged in first. Controls are visited only when their `child_of` matches the level being built, so a Repeater's inner controls arrive on their own pass.

## Usage

```php title="PHP"
function my_lzb_prepare_block_attribute( $attribute_data, $control, $controls, $k, $block ) {
  // A custom control stores JSON, so register it as an object rather than
  // the string its control class declares.
  if ( 'my-json-control' !== $control['type'] ) {
    return $attribute_data;
  }

  $attribute_data['type']    = 'object';
  $attribute_data['default'] = array( 'mode' => 'compact' );

  return $attribute_data;
}

add_filter( 'lzb/prepare_block_attribute', 'my_lzb_prepare_block_attribute', 10, 5 );
```

The type declared here is what Gutenberg validates the saved value against, so a mismatch makes the editor report the block as invalid after a reload rather than failing at save time. For a **Save in Meta** control the same array is also handed to `register_meta()`. Setting `type` to `array` without also setting `items` makes Lazy Blocks fall back to `show_in_rest => true`, and WordPress refuses to expose array meta over REST without an items schema. Dropping the `default` key gives the attribute a `null` default, which is different from an empty string and shows up in Handlebars as nothing at all.

To change the value at render time instead of the type at registration time, use [lzb/control_value](https://www.lazyblocks.com/docs/php-filters/lzb-control_value/).

---

# lzb/sanitize_block_data

Source: https://www.lazyblocks.com/docs/php-filters/lzb-sanitize_block_data/

Lists the block-level keys Lazy Blocks runs through `wp_kses_post()` before anything reads the block list.

A block field you add through [lzb/block_data](https://www.lazyblocks.com/docs/php-filters/lzb-block_data/) is stored and printed as it was typed. Add its key here and it gets the same escaping the built-in fields get.

## Attributes

| Name                   | Type      | Description                                                                                |
| ---------------------- | --------- | ------------------------------------------------------------------------------------------ |
| `$sanitize_block_data` | **Array** | block keys to sanitize, `title`, `description`, `category` and `category_label` by default |

The list is a flat array of top-level block keys. `sanitize_block_configs()` walks every block and replaces `$block[ $key ]` with `wp_kses_post( $block[ $key ] )` for each key in the list, skipping the ones that are empty. Control-level keys are handled by the separate [lzb/sanitize_block_control_data](https://www.lazyblocks.com/docs/php-filters/lzb-sanitize_block_control_data/) list.

## Usage

```php title="PHP"
function my_lzb_sanitize_block_data( $names ) {
  // A field added to every block through lzb/block_data, printed in the
  // inspector as markup, so it needs the same escaping the label gets.
  $names[] = 'documentation_note';

  return $names;
}

add_filter( 'lzb/sanitize_block_data', 'my_lzb_sanitize_block_data' );
```

`sanitize_block_configs()` is attached to [lzb/get_blocks](https://www.lazyblocks.com/docs/php-filters/lzb-get_blocks/) at priority 100, so it runs after every other handler on that filter and there is no way to add a key back afterwards. Removing a key from the list turns the escaping off for that field on every block. Returning anything but an array raises a `TypeError` at the `foreach` that follows.

---

# lzb/sanitize_block_control_data

Source: https://www.lazyblocks.com/docs/php-filters/lzb-sanitize_block_control_data/

Lists the control keys Lazy Blocks runs through `wp_kses_post()` before anything reads the block list.

A custom control that stores a text setting of its own gets no escaping until its key is on this list. The Message control in Lazy Blocks Pro adds `message_text` here, which is the pattern to copy.

## Attributes

| Name                     | Type      | Description                                                                                                   |
| ------------------------ | --------- | ------------------------------------------------------------------------------------------------------------- |
| `$sanitize_control_data` | **Array** | control keys to sanitize, `label`, `help`, `rows_label`, `rows_add_button_label` and `placeholder` by default |

`sanitize_block_configs()` walks every control of every block and replaces `$control[ $key ]` with `wp_kses_post( $control[ $key ] )` for each key in the list, skipping the ones that are empty. Top-level block keys are handled by the separate [lzb/sanitize_block_data](https://www.lazyblocks.com/docs/php-filters/lzb-sanitize_block_data/) list.

## Usage

```php title="PHP"
function my_lzb_sanitize_block_control_data( $names ) {
  if ( in_array( 'notice_text', $names, true ) ) {
    return $names;
  }

  // Setting of a custom control, printed as markup next to the field.
  $names[] = 'notice_text';

  return $names;
}

add_filter( 'lzb/sanitize_block_control_data', 'my_lzb_sanitize_block_control_data' );
```

`sanitize_block_configs()` is attached to [lzb/get_blocks](https://www.lazyblocks.com/docs/php-filters/lzb-get_blocks/) at priority 100, so it runs after every other handler on that filter. The escaping reaches child controls of a Repeater as well, because the control list is flat and a nested control carries a `child_of` key rather than living inside its parent. Returning anything but an array raises a `TypeError` at the `foreach` that follows.

Writing a control with settings of its own is covered in [Create Custom Control](https://www.lazyblocks.com/docs/examples/create-custom-control/).

---

# lzb/get_blocks

Source: https://www.lazyblocks.com/docs/php-filters/lzb-get_blocks/

Adds or removes whole blocks from the list every other part of the plugin works from, which is how a plugin ships blocks without writing them into the database.

`get_blocks()` fires it at two places. Once on a request-level cache hit, where it returns early with the list it already built, and once at the end after the database blocks, the blocks added through `lazyblocks()->add_block()` and the duplicate slug pass have all been folded together. A handler therefore runs on both paths and has to be safe to run more than once per request.

## Attributes

| Name      | Type      | Description                                                                                      |
| --------- | --------- | ------------------------------------------------------------------------------------------------ |
| `$blocks` | **Array** | list of blocks, each one shaped like [lzb/block_data](https://www.lazyblocks.com/docs/php-filters/lzb-block_data/) returns |

The list is a plain indexed array. Each item has `id`, `title`, `icon`, `keywords`, `slug`, `description`, `category`, `category_label`, `supports`, `controls`, `code`, `style`, `script`, `styles`, `condition` and `edit_url`. `slug` is the full block name including the namespace, so it reads `lazyblock/pricing-table` rather than `pricing-table`. `id` is the post ID and is `null` for a block registered from PHP.

## Usage

```php title="PHP"
function my_lzb_get_blocks( $blocks ) {
  // Hide the blocks tagged "internal" from editors, without deleting them.
  if ( current_user_can( 'manage_options' ) ) {
    return $blocks;
  }

  return array_values(
    array_filter(
      $blocks,
      function ( $block ) {
        return ! in_array( 'internal', (array) $block['keywords'], true );
      }
    )
  );
}

add_filter( 'lzb/get_blocks', 'my_lzb_get_blocks' );
```

Reindex after filtering, as above. Several consumers walk the list with `foreach` and are fine with gaps, but the array is also passed to the editor as JSON, where a gapped array is serialised as an object and the editor registers nothing. A block added here is registered like any other, so it needs a `slug` with a namespace and a `controls` array whose `type` values are real control types.

`get_blocks()` also writes the database blocks into a transient before this filter runs, which means additions made here are never cached. [lzb/cache_expiration](https://www.lazyblocks.com/docs/php-filters/lzb-cache_expiration/) sets the transient lifetime and [lzb/cache_cleared](https://www.lazyblocks.com/docs/php-actions/lzb-cache_cleared/) fires when it is flushed. To register a block rather than post-process the list, call `lazyblocks()->add_block()` on [lzb/init](https://www.lazyblocks.com/docs/php-actions/lzb-init/).

---

# lzb/cache_expiration

Source: https://www.lazyblocks.com/docs/php-filters/lzb-cache_expiration/

Sets how long the prepared block list stays in a transient, or turns that transient off.

Lazy Blocks reads every `lazyblocks` post on each request, prepares its controls and stores the result under the `lzb_blocks_cache_` transient for a day. Shorten that while you are debugging a `lzb/block_data` handler, or return `0` on a site whose object cache already keeps transients in memory.

## Attributes

| Name                | Type    | Description                                                |
| ------------------- | ------- | ---------------------------------------------------------- |
| `$cache_expiration` | **Int** | transient lifetime in seconds, `DAY_IN_SECONDS` by default |

## Usage

```php title="PHP"
function my_lzb_cache_expiration( $cache_expiration ) {
  // No transient while a developer is editing block code, one hour otherwise.
  if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
    return 0;
  }

  return HOUR_IN_SECONDS;
}

add_filter( 'lzb/cache_expiration', 'my_lzb_cache_expiration' );
```

The value is compared with `> 0` and then passed straight to `set_transient()`, so `0` and any negative number skip the write and every request rebuilds the list from the database. Only blocks stored in the database go into the transient. Blocks registered from PHP with `lazyblocks()->add_block()` are appended after the cached list is read, so their data is rebuilt on every request regardless of this value.

The transient key is `lzb_blocks_cache_` followed by an MD5 of the registered control types and the number of callbacks on `lzb/block_data` and `lzb/block_defaults`, so activating a plugin that adds a control or a filter produces a new key rather than a stale list. [lzb/cache_cleared](https://www.lazyblocks.com/docs/php-actions/lzb-cache_cleared/) fires whenever the plugin deletes those transients.

---

# lzb/get_meta

Source: https://www.lazyblocks.com/docs/php-filters/lzb-get_meta/

Changes what `get_lzb_meta()` hands back to a theme file, which is where a fallback value or a formatted version belongs when the same meta is read from a dozen templates.

It fires on the way out of `get_lzb_meta()`, after the value has been read from post meta and after [lzb/control_value](https://www.lazyblocks.com/docs/php-filters/lzb-control_value/) has converted it for its control type. Inside the block editor preview the value comes from the block being previewed rather than from the database, and this filter still runs, so a fallback added here shows up in the preview too.

## Attributes

| Name            | Type              | Description                                                       |
| --------------- | ----------------- | ----------------------------------------------------------------- |
| `$result`       | **Mixed**         | value returned by `get_lzb_meta()`                                |
| `$name`         | **String**        | meta name asked for                                               |
| `$id`           | **Int \| null**   | post ID, `null` when no ID was passed and there is no global post |
| `$control_data` | **Array \| null** | the control that saves this meta, `null` when no control does     |

`$control_data` is found by walking every block's controls for one whose **Save in Meta** is on and whose meta name matches. A meta name that no control owns still reaches this filter, with `$control_data` as `null` and `$result` straight from `get_post_meta()`.

## Usage

```php title="PHP"
function my_lzb_get_meta( $result, $name, $id, $control_data ) {
  // Fall back to the site name for the page subtitle, so templates do not
  // each need their own empty check.
  if ( 'page-subtitle' !== $name || ! empty( $result ) ) {
    return $result;
  }

  return get_bloginfo( 'name' );
}

add_filter( 'lzb/get_meta', 'my_lzb_get_meta', 10, 4 );
```

Guard on `$name`, as above. The filter fires for every meta name Lazy Blocks is asked for, so a handler that changes `$result` unconditionally rewrites unrelated fields. Return the type the control saves. A Repeater's value is an array and a template that iterates it breaks on a string.

To change the value for every use rather than only for `get_lzb_meta()`, hook [lzb/control_value](https://www.lazyblocks.com/docs/php-filters/lzb-control_value/) instead. Reading meta from templates is covered in [Display custom fields meta](https://www.lazyblocks.com/docs/examples/display-custom-fields-meta/).

---

# lzb/control_value

Source: https://www.lazyblocks.com/docs/php-filters/lzb-control_value/

Converts what a control stored into what a template should see, which is how the Posts control turns saved IDs into post objects and how a custom control expands its own stored shape.

Three places call it, so a handler covers all of them at once. The block render callback runs it over every top-level control, `get_lzb_meta()` runs it over the control behind a meta name, and the Repeater control runs it over each inner control of each row. Every built-in control already hooks it at priority 5 through the base control class, matching on its own type, which means a handler at the default priority 10 sees the converted value rather than the raw stored one.

## Attributes

| Name            | Type       | Description                                                                                                                                                       |
| --------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$value`        | **Mixed**  | control value, already converted by the control's own handler                                                                                                     |
| `$control_data` | **Array**  | this control, with `type`, `name`, `label`, `default`, `child_of`, `placement`, `group`, `width`, `required`, `translate`, `save_in_meta` and `save_in_meta_name` |
| `$block_data`   | **Array**  | block data, the same array [lzb/block_data](https://www.lazyblocks.com/docs/php-filters/lzb-block_data/) returns                                                                            |
| `$context`      | **String** | `editor` or `frontend`                                                                                                                                            |

The whole chain is skipped when `$control_data` is empty, which happens in `get_lzb_meta()` for a meta name no control saves.

## Additional Filters

| Name                                          | Description                                    |
| --------------------------------------------- | ---------------------------------------------- |
| `lzb/control_value/control_type=CONTROL_TYPE` | filter value of specific control type          |
| `lzb/control_value/control_name=CONTROL_NAME` | filter value of specific control name          |
| `lzb/control_value/block_slug=BLOCK_SLUG`     | filter value of all controls of specific block |

`CONTROL_TYPE` is the type slug, so `lzb/control_value/control_type=image`. `CONTROL_NAME` is the control's `name`, the same string the template reads. `BLOCK_SLUG` is the full slug including the namespace, so `lzb/control_value/block_slug=lazyblock/recipe`. All three take the same four arguments as the main filter and run after it, in the order listed.

## Usage

```php title="PHP"
function my_lzb_control_value( $value, $control_data, $block_data, $context ) {
  // Show a placeholder image in the editor when the image control is empty,
  // so the preview does not collapse.
  if ( 'editor' !== $context || ! empty( $value ) ) {
    return $value;
  }

  return array(
    'id'  => 0,
    'url' => get_stylesheet_directory_uri() . '/img/placeholder.png',
    'alt' => '',
  );
}

add_filter( 'lzb/control_value/control_type=image', 'my_lzb_control_value', 10, 4 );
```

Return the shape the template expects. An Image control's value is an array with `id`, `url` and `alt`, and a template doing `{{image.url}}` prints nothing when it receives a bare string. Because the filter also runs inside `get_lzb_meta()`, a change made here shows up in every theme file that reads the meta, not only in the block.

To change the attribute's registered type rather than its value, use [lzb/prepare_block_attribute](https://www.lazyblocks.com/docs/php-filters/lzb-prepare_block_attribute/). To change the output of `get_lzb_meta()` after this filter has run, use [lzb/get_meta](https://www.lazyblocks.com/docs/php-filters/lzb-get_meta/).

---

# lzb/controls/all

Source: https://www.lazyblocks.com/docs/php-filters/lzb-controls-all/

Registers a control type, or changes one that already exists, which is the single place the block builder's control list comes from.

The default value is an empty array. Every built-in control adds itself here from its own class, keyed by its type slug, on `lzb/init` at priority 5. Nothing else builds the list, so a handler that returns something other than the array it was given removes every control from the block builder and drops every control from every block, because `prepare_block_controls()` silently discards a control whose `type` it cannot find.

## Attributes

| Name        | Type      | Description                                     |
| ----------- | --------- | ----------------------------------------------- |
| `$controls` | **Array** | control definitions, keyed by control type slug |

Each entry holds these keys:

| Key            | Type       | Description                                                                                               |
| -------------- | ---------- | --------------------------------------------------------------------------------------------------------- |
| `name`         | **String** | type slug, the same as the array key                                                                      |
| `icon`         | **String** | SVG markup shown in the control picker                                                                    |
| `type`         | **String** | attribute type, one of `string`, `number`, `boolean`, `array`, `object`                                   |
| `label`        | **String** | control name shown in the block builder                                                                   |
| `category`     | **String** | grouping in the control picker, see [lzb/controls/categories](https://www.lazyblocks.com/docs/php-filters/lzb-controls-categories/) |
| `restrictions` | **Array**  | which settings the block builder offers for this control                                                  |
| `attributes`   | **Array**  | defaults merged into every control of this type                                                           |

## Usage

```php title="PHP"
function my_lzb_controls_all( $controls ) {
  // Keep the Code Editor control out of the block builder for everyone
  // who cannot edit files, and move Number next to Text.
  if ( ! current_user_can( 'edit_themes' ) ) {
    unset( $controls['code_editor'] );
  }

  if ( isset( $controls['number'] ) ) {
    $controls['number']['category'] = 'basic';
  }

  return $controls;
}

add_filter( 'lzb/controls/all', 'my_lzb_controls_all', 11 );
```

Use priority 11 or later. The built-in controls register at the default priority 10, so a handler at 10 or below sees a list that is still being filled. Removing a type that blocks already use makes those controls vanish from the blocks as well, not only from the picker, and the attributes behind them stop being registered.

Adding a control type of your own is covered in [Create Custom Control](https://www.lazyblocks.com/docs/examples/create-custom-control/), which subclasses `LazyBlocks_Control` and lets the base class hook this filter for you.

---

# lzb/controls/categories

Source: https://www.lazyblocks.com/docs/php-filters/lzb-controls-categories/

Adds a section to the control type picker in the block builder, which a custom control needs before it can be grouped anywhere but under an existing heading.

The default is six categories in this order.

| Slug         | Label      |
| ------------ | ---------- |
| `basic`      | Basic      |
| `content`    | Content    |
| `choice`     | Choice     |
| `advanced`   | Advanced   |
| `layout`     | Layout     |
| `deprecated` | Deprecated |

The result is localised as `lazyblocksBlockBuilderData.controls_categories` on the block builder screen only, and the type dropdown walks it in array order. That order is the order the sections appear in. A section with no controls in it is skipped, and a control whose `category` is not a key here never appears in the dropdown at all.

## Attributes

| Name          | Type      | Description                             |
| ------------- | --------- | --------------------------------------- |
| `$categories` | **Array** | category labels, keyed by category slug |

Labels are shown to the user, so run new ones through a translation function.

## Usage

```php title="PHP"
function my_lzb_controls_categories( $categories ) {
  // Put a section for the theme's own controls above Basic, and move the
  // deprecated ones out of sight.
  unset( $categories['deprecated'] );

  return array_merge(
    array( 'theme' => __( 'Theme Controls', 'my-theme' ) ),
    $categories,
    array( 'deprecated' => __( 'Deprecated', 'lazy-blocks' ) )
  );
}

add_filter( 'lzb/controls/categories', 'my_lzb_controls_categories' );
```

Removing a category that controls still point at hides those controls from the picker without removing the controls themselves, so blocks already using them keep working and nobody can add another. Assign the new slug to a control through its `category` key in [lzb/controls/all](https://www.lazyblocks.com/docs/php-filters/lzb-controls-all/), or through the `$category` property when you subclass `LazyBlocks_Control`.

Building a control of your own is covered in [Create Custom Control](https://www.lazyblocks.com/docs/examples/create-custom-control/).

---

# lzb/block_render/attributes

Source: https://www.lazyblocks.com/docs/php-filters/lzb-block_render-attributes/

Supplies a value the template needs but no control stores, such as the current post's terms or a price pulled from another table.

It is the first filter in the render pipeline. Every control value has already been resolved and passed through [lzb/control_value](https://www.lazyblocks.com/docs/php-filters/lzb-control_value/) by this point, and nothing has been rendered yet, so an attribute added here is visible to the PHP template, to the Handlebars template and to the theme template file alike.

## Attributes

| Name               | Type               | Description                                                                                                                  |
| ------------------ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `$attributes`      | **Array**          | control values keyed by control name, plus the reserved `lazyblock`, `className`, `anchor`, `blockId` and `blockUniqueClass` |
| `$content`         | **String \| null** | inner blocks markup, `null` when the block has none                                                                          |
| `$block`           | **Array**          | block data, the same array [lzb/block_data](https://www.lazyblocks.com/docs/php-filters/lzb-block_data/) returns                                       |
| `$render_location` | **String**         | `editor` or `frontend`                                                                                                       |
| `$context`         | **Array \| null**  | block context from parent blocks                                                                                             |

`$context` is `null` for an ordinary render. It only carries values when the block declares `uses_context` through the Pro Relationships feature, or when the render comes from the editor preview REST route.

## Additional Filters

| Name                                       | Arguments                                                   | Description                         |
| ------------------------------------------ | ----------------------------------------------------------- | ----------------------------------- |
| `lazyblock/BLOCK_SLUG/frontend_attributes` | `$attributes, $content, $block, $context`                   | specific block in the frontend only |
| `lazyblock/BLOCK_SLUG/editor_attributes`   | `$attributes, $content, $block, $context`                   | specific block in the editor only   |
| `lazyblock/BLOCK_SLUG/attributes`          | `$attributes, $content, $block, $render_location, $context` | specific block only                 |

The per-location variants take four arguments, not five. They already know the render location from their own name, so `$context` moves into the fourth position.

## Usage

```php title="PHP"
function my_lzb_block_render_attributes( $attributes, $content, $block, $render_location, $context ) {
  // Give the recipe block the current post's cuisine terms, which no
  // control stores.
  if ( 'lazyblock/recipe' !== $block['slug'] ) {
    return $attributes;
  }

  $attributes['cuisines'] = wp_get_post_terms( get_the_ID(), 'cuisine', array( 'fields' => 'names' ) );

  return $attributes;
}

add_filter( 'lzb/block_render/attributes', 'my_lzb_block_render_attributes', 10, 5 );
```

The return value has to be an array, because the render callback indexes into it straight afterwards. An attribute added here exists only during the render. It is not registered with `register_block_type()`, so the editor never saves it and Gutenberg never validates it. Removing a key that a control declared leaves the template reading an undefined index instead of an empty string.

To change the finished markup rather than its inputs, use [lzb/block_render/output](https://www.lazyblocks.com/docs/php-filters/lzb-block_render-output/).

---

# lzb/block_render/callback

Source: https://www.lazyblocks.com/docs/php-filters/lzb-block_render-callback/

Takes over the whole block output from PHP, which is what a block whose markup is too involved for Handlebars or the block builder's code editor needs.

`$result` arrives as `null`. Return anything else and Lazy Blocks skips the block's own code entirely, the theme template, the PHP output and the Handlebars template all included, and carries your string on to the wrapper handling. Return `null` and the block renders normally, which makes this the place to override one block without disturbing the rest. The check is `is_block_content_exists()`, so an empty string counts as no output and the block's own code still runs.

## Attributes

| Name               | Type               | Description                                                                                                   |
| ------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------- |
| `$result`          | **String \| null** | block output, `null` before any handler runs                                                                  |
| `$attributes`      | **Array**          | control values, already through [lzb/block_render/attributes](https://www.lazyblocks.com/docs/php-filters/lzb-block_render-attributes/) |
| `$render_location` | **String**         | `editor` or `frontend`                                                                                        |
| `$context`         | **Array \| null**  | block context from parent blocks                                                                              |

## Additional Filters

| Name                                     | Arguments                                          | Description                         |
| ---------------------------------------- | -------------------------------------------------- | ----------------------------------- |
| `lazyblock/BLOCK_SLUG/frontend_callback` | `$result, $attributes`                             | specific block in the frontend only |
| `lazyblock/BLOCK_SLUG/editor_callback`   | `$result, $attributes`                             | specific block in the editor only   |
| `lazyblock/BLOCK_SLUG/callback`          | `$result, $attributes, $render_location, $context` | specific block only                 |

The per-location variants take two arguments only.

## Usage

```php title="PHP"
function my_lzb_block_render_callback( $result, $attributes, $render_location, $context ) {
  // Render the latest posts block from PHP, and show a placeholder in the
  // editor instead of running the query on every keystroke.
  if ( 'lazyblock/latest-posts' !== $attributes['lazyblock']['slug'] ) {
    return $result;
  }

  if ( 'editor' === $render_location ) {
    return '<div useBlockProps>Latest posts render on the front end.</div>';
  }

  $posts = get_posts( array( 'numberposts' => (int) $attributes['count'] ) );
  $items = '';

  foreach ( $posts as $post ) {
    $items .= '<li><a href="' . esc_url( get_permalink( $post ) ) . '">' . esc_html( $post->post_title ) . '</a></li>';
  }

  return '<ul useBlockProps>' . $items . '</ul>';
}

add_filter( 'lzb/block_render/callback', 'my_lzb_block_render_callback', 10, 4 );
```

The string is not escaped for you, so escape every value you interpolate. Include a `useBlockProps` attribute on your outer tag, as above. Without one, Lazy Blocks wraps the output in a `<div useBlockProps>` of its own, and that div, rather than your element, is what carries the block's classes, anchor and alignment on the front end. On the front end a block that returns nothing here and has no code of its own renders as nothing at all, and WordPress emits no wrapper for it.

Returning markup from the block builder instead is covered in [PHP Callback](https://www.lazyblocks.com/docs/blocks-code/php-callback/).

---

# lzb/block_render/allow_wrapper

Source: https://www.lazyblocks.com/docs/php-filters/lzb-block_render-allow_wrapper/

Stops Lazy Blocks adding its own outer `<div>` to a block whose template already opens with the element it wants.

  This filter is **deprecated** since v4.0.0. It still runs, and WordPress logs
  a deprecation notice when it does. Add the wrapper attributes with
  [useBlockProps](https://www.lazyblocks.com/docs/blocks-code/use-block-props/) instead.

Returning `false` only skips the automatic `<div useBlockProps>`. It has no effect at all on a template that already carries a `useBlockProps` attribute on one of its own tags, because Lazy Blocks adds the wrapper only when it cannot find one. Marking your own outer tag with `useBlockProps` does the same job without the deprecation notice, and keeps the block's classes, anchor and alignment on an element you control. The filter runs on the front end only.

## Attributes

| Name               | Type        | Description                              |
| ------------------ | ----------- | ---------------------------------------- |
| `$allow_wrapper`   | **Boolean** | render the wrapper, `true` by default    |
| `$attributes`      | **Array**   | control values, as the template saw them |
| `$render_location` | **String**  | always `frontend`                        |

## Additional Filters

| Name                                          | Arguments                                       | Description                         |
| --------------------------------------------- | ----------------------------------------------- | ----------------------------------- |
| `lazyblock/BLOCK_SLUG/frontend_allow_wrapper` | `$allow_wrapper, $attributes`                   | specific block in the frontend only |
| `lazyblock/BLOCK_SLUG/allow_wrapper`          | `$allow_wrapper, $attributes, $render_location` | specific block only                 |

Both variants are deprecated on the same terms as the main filter, and each logs its own notice.

## Usage

```php title="PHP"
function my_lzb_block_render_allow_wrapper( $allow_wrapper, $attributes, $render_location ) {
  // The table block renders a <table> and cannot sit inside a div.
  if ( 'lazyblock/data-table' === $attributes['lazyblock']['slug'] ) {
    return false;
  }

  return $allow_wrapper;
}

add_filter( 'lzb/block_render/allow_wrapper', 'my_lzb_block_render_allow_wrapper', 10, 3 );
```

```php title="PHP"
// Drop the wrapper for one block on the front end.
add_filter( 'lazyblock/data-table/frontend_allow_wrapper', '__return_false' );
```

Dropping the wrapper without marking a tag `useBlockProps` also drops the block's generated classes, its anchor ID and its alignment class, because those are only applied to the `useBlockProps` element. That is the reason the replacement exists.

See [Block Wrapper](https://www.lazyblocks.com/docs/blocks-code/php-callback/#block-wrapper) for what the wrapper contains.

---

# lzb/block_render/allow_inner_blocks_wrapper

Source: https://www.lazyblocks.com/docs/php-filters/lzb-block_render-allow_inner_blocks_wrapper/

Drops the `<div>` Lazy Blocks puts around inner blocks, which a block whose children have to be direct descendants of a grid or a flex container needs.

The default is `true`. With the wrapper on, the inner content is placed inside a `<div>` whose class is taken from a `class` or `className` attribute on the `` tag in your template, falling back to `lazyblock-inner-blocks`. With it off, the inner content replaces `` exactly where it stands and no element is added. The filter runs on the front end only, so the editor keeps its own wrapper and the two views differ until you account for that in your CSS.

## Attributes

| Name                          | Type              | Description                              |
| ----------------------------- | ----------------- | ---------------------------------------- |
| `$allow_inner_blocks_wrapper` | **Boolean**       | render the wrapper, `true` by default    |
| `$attributes`                 | **Array**         | control values, as the template saw them |
| `$context`                    | **Array \| null** | block context from parent blocks         |

The block itself is not passed. Read its slug from `$attributes['lazyblock']['slug']`, or use the per-block variant below.

## Additional Filters

| Name                                              | Arguments                                            | Description    |
| ------------------------------------------------- | ---------------------------------------------------- | -------------- |
| `lazyblock/BLOCK_SLUG/allow_inner_blocks_wrapper` | `$allow_inner_blocks_wrapper, $attributes, $context` | specific block |

## Usage

```php title="PHP"
function my_lzb_allow_inner_blocks_wrapper( $allow, $attributes, $context ) {
  // The columns block is a CSS grid, so its children have to be direct
  // descendants and the extra div would break the layout.
  if ( 'lazyblock/columns' === $attributes['lazyblock']['slug'] ) {
    return false;
  }

  return $allow;
}

add_filter( 'lzb/block_render/allow_inner_blocks_wrapper', 'my_lzb_allow_inner_blocks_wrapper', 10, 3 );
```

```php title="PHP"
// Drop the wrapper for one block, without a callback.
add_filter( 'lazyblock/columns/allow_inner_blocks_wrapper', '__return_false' );
```

The return value is used as a boolean, so anything truthy keeps the wrapper. Turning it off for a block that has no inner content leaves `` replaced with an empty string rather than an empty `<div>`, which changes what a `:empty` or `:first-child` selector matches.

See [Inner Blocks Wrapper](https://www.lazyblocks.com/docs/blocks-code/php-callback/#inner-blocks-wrapper) for how the wrapper class is picked up from the template.

---

# lzb/block_render/output

Source: https://www.lazyblocks.com/docs/php-filters/lzb-block_render-output/

Wraps or rewrites finished block markup, which is what adding a schema script, a lazy-loading attribute or an analytics hook to every block takes.

It is the last filter in the render pipeline. The template has run, `` has been replaced with the real inner content, and the `useBlockProps` tag has already become a real wrapper carrying the block's classes, ID and alignment. What you receive is the exact string WordPress is about to print. Lazy Blocks Pro hooks this at priority 199 to collect styles for the block builder preview, and at priority 200 to cache editor renders for preloading, so a handler at the default priority 10 runs before both.

## Attributes

| Name               | Type               | Description                                                                            |
| ------------------ | ------------------ | -------------------------------------------------------------------------------------- |
| `$result`          | **String**         | finished block markup                                                                  |
| `$attributes`      | **Array**          | control values, as the template saw them                                               |
| `$render_location` | **String**         | `editor` or `frontend`                                                                 |
| `$block`           | **Array**          | block data, the same array [lzb/block_data](https://www.lazyblocks.com/docs/php-filters/lzb-block_data/) returns |
| `$context`         | **Array \| null**  | block context from parent blocks                                                       |
| `$content`         | **String \| null** | inner blocks markup before it was substituted                                          |

## Additional Filters

| Name                                   | Arguments                                                            | Description                         |
| -------------------------------------- | -------------------------------------------------------------------- | ----------------------------------- |
| `lazyblock/BLOCK_SLUG/frontend_output` | `$result, $attributes, $block, $context, $content`                   | specific block in the frontend only |
| `lazyblock/BLOCK_SLUG/editor_output`   | `$result, $attributes, $block, $context, $content`                   | specific block in the editor only   |
| `lazyblock/BLOCK_SLUG/output`          | `$result, $attributes, $render_location, $block, $context, $content` | specific block only                 |

The per-location variants take five arguments, with `$render_location` left out.

## Usage

```php title="PHP"
function my_lzb_block_render_output( $result, $attributes, $render_location, $block, $context, $content ) {
  // Append FAQ schema to the FAQ block on the front end only.
  if ( 'frontend' !== $render_location || 'lazyblock/faq' !== $block['slug'] ) {
    return $result;
  }

  $schema = array(
    '@context'   => 'https://schema.org',
    '@type'      => 'Question',
    'name'       => $attributes['question'],
    'acceptedAnswer' => array(
      '@type' => 'Answer',
      'text'  => wp_strip_all_tags( $attributes['answer'] ),
    ),
  );

  return $result . '<script type="application/ld+json">' . wp_json_encode( $schema ) . '</script>';
}

add_filter( 'lzb/block_render/output', 'my_lzb_block_render_output', 10, 6 );
```

Return a string. Returning `null` makes WordPress print nothing for the block, and returning an array raises a `TypeError` when the block content is concatenated. Because this runs after the wrapper is built, replacing the whole string throws away the block's generated classes, so keep the outer tag and modify around it.

To change the block's inputs instead of its output, use [lzb/block_render/attributes](https://www.lazyblocks.com/docs/php-filters/lzb-block_render-attributes/). To replace the render entirely, use [lzb/block_render/callback](https://www.lazyblocks.com/docs/php-filters/lzb-block_render-callback/).

---

# lzb/block_render/include_template

Source: https://www.lazyblocks.com/docs/php-filters/lzb-block_render-include_template/

Chooses which file is loaded for a block whose **Output Method** is **Theme Template**, which is how a plugin ships block templates that no theme carries.

`include_template()` resolves the name with `locate_template()`, fires this filter, and includes the result when `file_exists()` passes. It runs after [lzb/block_render/template_exists](https://www.lazyblocks.com/docs/php-filters/lzb-block_render-template_exists/) has already decided that a template is there, and the two resolve the path independently. Point one somewhere new without the other and Lazy Blocks finds a template it then declines to load, or the reverse.

The two are not symmetrical. `template_exists` receives `$template_name`, this one does not. Its second argument is the attributes array, and the file name is only recoverable from the block slug in `$block['slug']`.

## Attributes

| Name               | Type              | Description                                                                            |
| ------------------ | ----------------- | -------------------------------------------------------------------------------------- |
| `$template`        | **String**        | path found by `locate_template()`, empty when the theme has no such file               |
| `$attributes`      | **Array**         | control values, as the template will see them                                          |
| `$block`           | **Array**         | block data, the same array [lzb/block_data](https://www.lazyblocks.com/docs/php-filters/lzb-block_data/) returns |
| `$render_location` | **String**        | `editor` or `frontend`                                                                 |
| `$context`         | **Array \| null** | block context from parent blocks                                                       |

The included file gets `$attributes`, `$block`, `$render_location` and `$context` as local variables, because `include_template()` runs `extract()` on the same array before resolving the path.

## Additional Filters

| Name                                             | Arguments                                                    | Description                         |
| ------------------------------------------------ | ------------------------------------------------------------ | ----------------------------------- |
| `lazyblock/BLOCK_SLUG/frontend_include_template` | `$template, $attributes, $block, $context`                   | specific block in the frontend only |
| `lazyblock/BLOCK_SLUG/editor_include_template`   | `$template, $attributes, $block, $context`                   | specific block in the editor only   |
| `lazyblock/BLOCK_SLUG/include_template`          | `$template, $attributes, $block, $render_location, $context` | specific block only                 |

A shorter filter named `lzb/include_template` is still in the code for compatibility. It takes `( $template, $template_name, $args )`, where `$args` is the whole array holding `attributes`, `block`, `render_location` and `context` rather than those four unpacked. It fires after every filter in the table above, so whatever it returns wins. New code should use the `block_render` name. See [lzb/include_template](https://www.lazyblocks.com/docs/php-filters/lzb-include_template/).

## Usage

```php title="PHP"
function my_lzb_block_render_include_template( $template, $attributes, $block, $render_location, $context ) {
  // Load block templates from the plugin when the theme has none.
  if ( $template ) {
    return $template;
  }

  $slug     = str_replace( '/', '-', $block['slug'] );
  $file     = 'editor' === $render_location ? 'editor.php' : 'block.php';
  $fallback = plugin_dir_path( __FILE__ ) . 'blocks/' . $slug . '/' . $file;

  return file_exists( $fallback ) ? $fallback : $template;
}

add_filter( 'lzb/block_render/include_template', 'my_lzb_block_render_include_template', 10, 5 );
```

This filter also fires for the plugin's own `templates/template-not-found.php`, which is what gets included when no template was found, so a handler that returns a path unconditionally replaces the not-found notice as well. A path that does not exist means nothing is included and the block renders as an empty string, which on the front end makes WordPress print no wrapper for it either.

Register the matching path on [lzb/block_render/template_exists](https://www.lazyblocks.com/docs/php-filters/lzb-block_render-template_exists/). Theme templates are covered in [Theme Template](https://www.lazyblocks.com/docs/blocks-code/theme-template/).

---

# lzb/block_render/template_exists

Source: https://www.lazyblocks.com/docs/php-filters/lzb-block_render-template_exists/

Tells Lazy Blocks that a block template lives somewhere the theme lookup will never reach, such as inside a plugin that ships blocks of its own.

A block whose **Output Method** is **Theme Template** is rendered from `/blocks/BLOCK-SLUG/block.php` in the active theme, or `/blocks/BLOCK-SLUG/editor.php` in the editor. `template_exists()` resolves that name with `locate_template()`, fires this filter, then returns `file_exists()` on the result. So the filter decides whether the template is considered to be there at all, and its partner [lzb/block_render/include_template](https://www.lazyblocks.com/docs/php-filters/lzb-block_render-include_template/) decides which file is actually loaded. Filter one without the other and Lazy Blocks reports a template it then fails to include.

## Attributes

| Name               | Type              | Description                                                                            |
| ------------------ | ----------------- | -------------------------------------------------------------------------------------- |
| `$template`        | **String**        | path found by `locate_template()`, empty when the theme has no such file               |
| `$template_name`   | **String**        | name being looked up, for example `/blocks/lazyblock-recipe/block.php`                 |
| `$attributes`      | **Array**         | control values, as the template will see them                                          |
| `$block`           | **Array**         | block data, the same array [lzb/block_data](https://www.lazyblocks.com/docs/php-filters/lzb-block_data/) returns |
| `$render_location` | **String**        | `editor` or `frontend`                                                                 |
| `$context`         | **Array \| null** | block context from parent blocks                                                       |

## Additional Filters

| Name                                            | Arguments                                                                    | Description                         |
| ----------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------- |
| `lazyblock/BLOCK_SLUG/frontend_template_exists` | `$template, $template_name, $attributes, $block, $context`                   | specific block in the frontend only |
| `lazyblock/BLOCK_SLUG/editor_template_exists`   | `$template, $template_name, $attributes, $block, $context`                   | specific block in the editor only   |
| `lazyblock/BLOCK_SLUG/template_exists`          | `$template, $template_name, $attributes, $block, $render_location, $context` | specific block only                 |

A shorter filter named `lzb/template_exists` is still in the code for compatibility. It takes `( $template, $template_name, $args )`, where `$args` is the whole array holding `attributes`, `block`, `render_location` and `context` rather than those four unpacked. It fires after every filter in the table above, so whatever it returns wins. New code should use the `block_render` name. See [lzb/template_exists](https://www.lazyblocks.com/docs/php-filters/lzb-template_exists/).

## Usage

```php title="PHP"
function my_lzb_block_render_template_exists( $template, $template_name, $attributes, $block, $render_location, $context ) {
  // Serve block templates from the plugin when the theme has none, so a
  // theme switch does not take the blocks down with it.
  if ( $template ) {
    return $template;
  }

  $fallback = plugin_dir_path( __FILE__ ) . ltrim( $template_name, '/' );

  return file_exists( $fallback ) ? $fallback : $template;
}

add_filter( 'lzb/block_render/template_exists', 'my_lzb_block_render_template_exists', 10, 6 );
```

Return a path, not a boolean. The name reads like a yes or no question, but Lazy Blocks calls `file_exists()` on your return value, so `true` becomes the string `1` and the check fails. Returning an empty string sends the block to `templates/template-not-found.php` inside the plugin, which prints a "Template file not found" notice where the block should have been.

Register the same fallback on [lzb/block_render/include_template](https://www.lazyblocks.com/docs/php-filters/lzb-block_render-include_template/), or the file is found and never loaded. Theme templates are covered in [Theme Template](https://www.lazyblocks.com/docs/blocks-code/theme-template/).

---

# lzb/include_template

Source: https://www.lazyblocks.com/docs/php-filters/lzb-include_template/

Filters the theme template file a block is about to include, and is the last filter to run on that path.

Source marks this one `DEPRECATED`. It is not an alias of [lzb/block_render/include_template](https://www.lazyblocks.com/docs/php-filters/lzb-block_render-include_template/): it takes three arguments where that one takes five, and it fires after it. Write new code against the longer name and reach for this one only to read what an existing handler does.

The two names do not line up argument by argument either. `lzb/block_render/include_template` never receives `$template_name`, its second argument is the block attributes, so a callback cannot be moved between the two filters unchanged.

## Attributes

| Name             | Type       | Description                                                                 |
| ---------------- | ---------- | --------------------------------------------------------------------------- |
| `$template`      | **String** | absolute path resolved so far, empty when `locate_template()` found nothing |
| `$template_name` | **String** | theme relative path being looked up, `/blocks/lazyblock-my-block/block.php` |
| `$args`          | **Array**  | render arguments, see below                                                 |

`$args` has exactly four keys:

| Name              | Type                 | Description                             |
| ----------------- | -------------------- | --------------------------------------- |
| `attributes`      | **Array**            | block attributes                        |
| `block`           | **Array**            | block data                              |
| `render_location` | **String**           | `editor` or `frontend`                  |
| `context`         | **WP_Block \| null** | block context provided by parent blocks |

The editor asks for `/blocks/BLOCK_SLUG/editor.php` first and falls back to `/blocks/BLOCK_SLUG/block.php`, with the slash in the slug replaced by a dash. Both file names arrive here as `$template_name`.

## Usage

```php title="PHP"
function my_lzb_include_template( $template, $template_name, $args ) {
  // Keep the block templates of a plugin in the plugin, not in the theme.
  if ( 0 !== strpos( $args['block']['slug'], 'lazyblock/acme-' ) ) {
    return $template;
  }

  $plugin_template = plugin_dir_path( __FILE__ ) . 'templates' . $template_name;

  return file_exists( $plugin_template ) ? $plugin_template : $template;
}

add_filter( 'lzb/include_template', 'my_lzb_include_template', 10, 3 );
```

This filter runs after `lzb/block_render/include_template` and after both per-slug variants, so whatever it returns is the path that gets included. The include only happens when `file_exists()` passes, so returning a path that is not there renders the block as an empty string rather than raising a warning. Pair it with [lzb/template_exists](https://www.lazyblocks.com/docs/php-filters/lzb-template_exists/), which decides whether the file is looked for at all.

`$args` is also expanded into `$attributes`, `$block`, `$render_location` and `$context` variables inside the included template, which is how the [Theme Template](https://www.lazyblocks.com/docs/blocks-code/theme-template/) output method reads block values.

---

# lzb/template_exists

Source: https://www.lazyblocks.com/docs/php-filters/lzb-template_exists/

Filters the path Lazy Blocks tests with `file_exists()` when deciding whether a block has a theme template at all.

Source marks this one `DEPRECATED`. It is not an alias of [lzb/block_render/template_exists](https://www.lazyblocks.com/docs/php-filters/lzb-block_render-template_exists/): it takes three arguments where that one takes six, and it fires after it. Write new code against the longer name and reach for this one only to read what an existing handler does.

## Attributes

| Name             | Type       | Description                                                                 |
| ---------------- | ---------- | --------------------------------------------------------------------------- |
| `$template`      | **String** | absolute path resolved so far, empty when `locate_template()` found nothing |
| `$template_name` | **String** | theme relative path being looked up, `/blocks/lazyblock-my-block/block.php` |
| `$args`          | **Array**  | render arguments, see below                                                 |

`$args` has exactly four keys:

| Name              | Type                 | Description                             |
| ----------------- | -------------------- | --------------------------------------- |
| `attributes`      | **Array**            | block attributes                        |
| `block`           | **Array**            | block data                              |
| `render_location` | **String**           | `editor` or `frontend`                  |
| `context`         | **WP_Block \| null** | block context provided by parent blocks |

## Usage

```php title="PHP"
function my_lzb_template_exists( $template, $template_name, $args ) {
  // Let the block builder preview fall back to the frontend template
  // instead of showing "template not found" while editor.php is missing.
  if ( 'editor' !== $args['render_location'] ) {
    return $template;
  }

  if ( $template && file_exists( $template ) ) {
    return $template;
  }

  return locate_template( array( str_replace( '/editor.php', '/block.php', $template_name ) ) );
}

add_filter( 'lzb/template_exists', 'my_lzb_template_exists', 10, 3 );
```

The return value is passed straight to `file_exists()`, so an empty string or a path that is not on disk sends the block to the `template-not-found.php` fallback. A handler here that returns a path must be matched by one on [lzb/include_template](https://www.lazyblocks.com/docs/php-filters/lzb-include_template/) returning the same path, otherwise Lazy Blocks confirms the template exists and then includes a different file.

Both filters run last in their function, after `lzb/block_render/template_exists` and after both per-slug variants, so they overrule anything those returned. The output method they belong to is [Theme Template](https://www.lazyblocks.com/docs/blocks-code/theme-template/).

---

# lzb/plugin_path

Source: https://www.lazyblocks.com/docs/php-filters/lzb-plugin_path/

Points Lazy Blocks at a different copy of its own files, which is what a symlinked checkout or a plugin bundled outside `wp-content/plugins` needs.

The default is `plugin_dir_path()` of the core plugin file, ending in a slash. Four things read it. The `require_once` calls that load every class, the `.asset.php` build manifests that supply script dependencies and versions, the `languages` folder handed to `wp_set_script_translations()`, and the `templates/template-not-found.php` fallback rendered when a theme template is missing. A wrong string here is a fatal error on the `require_once`, not a missing asset.

Those `require_once` calls run while the plugin file is still loading, because `lazyblocks()` is called at the bottom of `core-plugin/lazy-blocks.php`. A filter added from a theme's `functions.php`, or from a plugin that loads later in the alphabet, is registered too late to affect them. Only an mu-plugin runs early enough. Added later, the filter still reaches the asset manifests, the translations folder and the template fallback.

## Attributes

| Name           | Type       | Description                               |
| -------------- | ---------- | ----------------------------------------- |
| `$plugin_path` | **String** | plugin folder path, with a trailing slash |

## Usage

```php title="PHP"
function my_lzb_plugin_path( $plugin_path ) {
  // The plugin directory is a symlink, so resolve it to the real path
  // before anything opens a file relative to it.
  $real = realpath( $plugin_path );

  return $real ? trailingslashit( $real ) : $plugin_path;
}

add_filter( 'lzb/plugin_path', 'my_lzb_plugin_path' );
```

The path has to exist and end in a directory separator. `realpath()` strips the trailing slash and returns `false` for a path that is not there, so guard both, as above. Returning a URL instead of a filesystem path makes every `require_once` fail.

The Pro plugin resolves its own directory through [lzb_pro/plugin_path](https://www.lazyblocks.com/docs/php-filters/lzb_pro-plugin_path/), so a bundled install has to filter both.

---

# lzb/plugin_url

Source: https://www.lazyblocks.com/docs/php-filters/lzb-plugin_url/

Moves the URL Lazy Blocks builds its own script and style tags from, which is what serving the plugin's assets from a CDN needs.

The default is `plugin_dir_url()` of the core plugin file, ending in a slash. `LazyBlocks_Assets::register_script()` and `register_style()` append a build path and an extension to it, so `build/editor.js` and `build/editor.css` are resolved against whatever this filter returns. The file contents are never read through this value. That is [lzb/plugin_path](https://www.lazyblocks.com/docs/php-filters/lzb-plugin_path/), which is why a wrong URL here costs a 404 on the editor bundle rather than a fatal error.

## Attributes

| Name          | Type       | Description                              |
| ------------- | ---------- | ---------------------------------------- |
| `$plugin_url` | **String** | plugin folder URL, with a trailing slash |

## Usage

```php title="PHP"
function my_lzb_plugin_url( $plugin_url ) {
  // Serve the plugin's built CSS and JS from a CDN mirror of wp-content.
  return str_replace( content_url(), 'https://cdn.example.com/wp-content', $plugin_url );
}

add_filter( 'lzb/plugin_url', 'my_lzb_plugin_url' );
```

A return value without the trailing slash produces URLs like `.../lazy-blocksbuild/editor.js`, so keep it or add it back with `trailingslashit()`. Asset version strings still come from the `.asset.php` files on disk, read through `lzb/plugin_path`, which means a CDN copy has to match the installed build or the browser caches the wrong file against the right version.

The Pro plugin has its own directory and its own filter, [lzb_pro/plugin_url](https://www.lazyblocks.com/docs/php-filters/lzb_pro-plugin_url/). Filtering one leaves the other alone.

---

# lzb/plugin_basename

Source: https://www.lazyblocks.com/docs/php-filters/lzb-plugin_basename/

Filters the `folder/file.php` identifier WordPress knows the plugin by.

The plugin uses this string to find its own `languages` directory and to attach the Plugins screen action link. A site that ships Lazy Blocks inside a theme or a parent plugin, where the directory name differs from the one WordPress recorded, corrects it here.

## Attributes

| Name               | Type       | Description                                                                                                |
| ------------------ | ---------- | ---------------------------------------------------------------------------------------------------------- |
| `$plugin_basename` | **String** | `plugin_basename( __FILE__ )` of the core plugin file, `lazy-blocks/lazy-blocks.php` in a standard install |

Two places read it:

| Where                              | What it uses the value for                                                      |
| ---------------------------------- | ------------------------------------------------------------------------------- |
| `load_plugin_textdomain()`         | `dirname()` of the value plus `/languages/`, the folder scanned for `.mo` files |
| `plugin_action_links_` filter name | the Plugins screen row the Go Pro link is attached to                           |

## Usage

```php title="PHP"
function my_lzb_plugin_basename( $plugin_basename ) {
  // Lazy Blocks lives in a subfolder of this plugin, so the basename
  // WordPress recorded points at the wrong directory.
  return 'acme-blocks/vendor/lazy-blocks/lazy-blocks.php';
}

add_filter( 'lzb/plugin_basename', 'my_lzb_plugin_basename' );
```

Nothing validates the returned string. A wrong value makes `load_plugin_textdomain()` look in a directory that does not exist, and every Lazy Blocks string falls back to English with no error anywhere. The Go Pro link on the Plugins screen disappears at the same time, which is the fastest way to spot it.

The two consumers read the value at different times. `load_plugin_textdomain()` runs on `init` at priority 5, so a filter registered on `plugins_loaded` is early enough for translations. The Plugins screen filter name is built while the plugin file itself is loading, so only a must-use plugin can change that one.

See also [lzb/plugin_path](https://www.lazyblocks.com/docs/php-filters/lzb-plugin_path/) and [lzb/plugin_url](https://www.lazyblocks.com/docs/php-filters/lzb-plugin_url/).

---

# lzb/show_admin_menu

Source: https://www.lazyblocks.com/docs/php-filters/lzb-show_admin_menu/

Takes the Lazy Blocks item out of the admin sidebar, which is what handing a finished site to a client without inviting them to edit its blocks takes.

The default is `true`. Returning `false` calls `remove_menu_page( 'edit.php?post_type=lazyblocks' )` on `admin_menu` at priority 12. That hides the link and nothing else. The screens stay reachable by URL and the `edit_lazyblocks` capability still governs who may open them, so this is tidiness rather than a permission boundary.

## Attributes

| Name    | Type        | Description                                 |
| ------- | ----------- | ------------------------------------------- |
| `$show` | **Boolean** | show the admin menu item, `true` by default |

## Usage

```php title="PHP"
function my_lzb_show_admin_menu( $show ) {
  // Only the developer account keeps the menu item.
  return current_user_can( 'manage_options' ) && 'dev@example.com' === wp_get_current_user()->user_email;
}

add_filter( 'lzb/show_admin_menu', 'my_lzb_show_admin_menu' );
```

```php title="PHP"
// Hide it from everyone.
add_filter( 'lzb/show_admin_menu', '__return_false' );
```

Register the filter before `admin_menu` runs at priority 12, which any plugin or `functions.php` load does. Only the administrator role has `edit_lazyblocks` out of the box, so editors, authors and contributors never see the menu item in the first place and this filter is aimed at administrators. To actually keep somebody out of the block builder, remove that capability from their role instead of hiding the link.

---

# lzb/allow_unfiltered_html

Source: https://www.lazyblocks.com/docs/php-filters/lzb-allow_unfiltered_html/

Decides which users may save raw block markup and view scripts, and run PHP in the block builder preview.

On multisite WordPress gives the `unfiltered_html` capability to super admins only, so a site administrator opens the block builder and finds the HTML and Script fields silently refusing to save. This filter is the single switch behind that behaviour.

  A handler that returns a constant truthy value hands arbitrary PHP execution
  and unfiltered meta writes to every logged-in user, subscribers included.
  Always keep a capability or role check in the return value.

## Attributes

| Name                     | Type        | Description                                                  |
| ------------------------ | ----------- | ------------------------------------------------------------ |
| `$allow_unfiltered_html` | **Boolean** | `current_user_can( 'unfiltered_html' )` for the current user |

Four places read the result:

| Where                           | What a `false` result does                                                                                                                                           |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `guard_unfiltered_block_meta()` | blocks direct `add_post_meta()` and `update_post_meta()` writes to the keys from [lzb/unfiltered_block_meta_keys](https://www.lazyblocks.com/docs/php-filters/lzb-unfiltered_block_meta_keys/) |
| `save_meta_boxes()`             | skips saving `lazyblocks_code_editor_html`, `lazyblocks_code_frontend_html` and `lazyblocks_script_view`                                                             |
| `save_meta_boxes()`             | runs every other block field through `wp_kses_post_deep()`                                                                                                           |
| block render                    | returns `WP_Error( 'lazy_block_cannot_execute_php' )` instead of evaluating the PHP output method, in the block builder preview only                                 |

The render gate applies only while the block builder preview endpoint is running. A block already saved renders its PHP for every visitor no matter who is looking at the page.

## Usage

```php title="PHP"
function my_lzb_allow_unfiltered_html( $allowed ) {
  if ( $allowed ) {
    return $allowed;
  }

  // Multisite reserves `unfiltered_html` for super admins. Give block code
  // editing back to the administrators of this one site.
  return is_multisite()
    && current_user_can( 'manage_options' )
    && current_user_can( 'edit_lazyblocks' );
}

add_filter( 'lzb/allow_unfiltered_html', 'my_lzb_allow_unfiltered_html' );
```

The default is `current_user_can( 'unfiltered_html' )`, which is true for administrators on a single site and for super admins on multisite. Returning `false` for everyone leaves the block builder usable, with the HTML, PHP and Script fields dropped on save.

---

# lzb/unfiltered_block_meta_keys

Source: https://www.lazyblocks.com/docs/php-filters/lzb-unfiltered_block_meta_keys/

Lists the block meta keys only a user with `unfiltered_html` may write.

WordPress lets XML-RPC and the custom fields box write post meta straight past the block builder REST endpoint, where these fields are normally checked. Lazy Blocks closes that path with an `add_post_metadata` and `update_post_metadata` guard, and this filter is the list the guard works from.

## Attributes

| Name                | Type      | Description                                                                                                                 |
| ------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------- |
| `$unsafe_meta_keys` | **Array** | protected meta keys, `lazyblocks_code_editor_html`, `lazyblocks_code_frontend_html` and `lazyblocks_script_view` by default |

The three defaults are the fields that end up on the page as markup or as a script tag. A write to any of them on a `lazyblocks` post returns `false` from the guard, which cancels the meta write, unless [lzb/allow_unfiltered_html](https://www.lazyblocks.com/docs/php-filters/lzb-allow_unfiltered_html/) says the current user may save unfiltered HTML.

Posts of other types never reach the check, so adding a key that a plugin also stores on regular posts costs nothing there.

## Usage

```php title="PHP"
function my_lzb_unfiltered_block_meta_keys( $keys ) {
  // Block CSS is written into a <style> tag, so give it the same guard
  // the HTML and script fields have.
  $keys[] = 'lazyblocks_style_block';
  $keys[] = 'lazyblocks_style_editor';

  return $keys;
}

add_filter( 'lzb/unfiltered_block_meta_keys', 'my_lzb_unfiltered_block_meta_keys' );
```

Adding a key narrows who can write it. Removing one of the three defaults reopens the direct meta path for that field to any user who can edit a block, which is what the guard exists to prevent. The filter runs on every `add_post_meta()` and `update_post_meta()` call on the site, so keep the handler free of database queries.

---

# lzb/import_json

Source: https://www.lazyblocks.com/docs/php-filters/lzb-import_json/

Filters the decoded contents of an export file before Lazy Blocks creates any posts from it.

An export file produced on a staging site carries that site's category slugs and post types. Rewrite them here, or drop the items you do not want to land, without editing the JSON by hand before every import.

## Attributes

| Name    | Type      | Description                                             |
| ------- | --------- | ------------------------------------------------------- |
| `$json` | **Array** | decoded export file, a list of block and template items |

Each item needs an `id` key or the import loop skips it. Lazy Blocks decides what an item is by its other keys:

| Item     | Recognised by                                     | Handled by                                                                                          |
| -------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| block    | any of `icon`, `category`, `supports`, `controls` | `import_block()`, which then fires [lzb/import/block](https://www.lazyblocks.com/docs/php-actions/lzb-import-block/)          |
| template | `post_types`                                      | `import_template()`, which then fires [lzb/import/template](https://www.lazyblocks.com/docs/php-actions/lzb-import-template/) |

The filter runs after the nonce, file size, upload error, `.json` extension and non-empty-array checks have all passed, so a handler never sees a rejected upload.

## Usage

```php title="PHP"
function my_lzb_import_json( $json ) {
  foreach ( $json as $k => $data ) {
    // Blocks exported from staging carry its category. Put them in ours.
    if ( isset( $data['controls'] ) && isset( $data['category'] ) ) {
      $json[ $k ]['category']       = 'theme-blocks';
      $json[ $k ]['category_label'] = 'Theme Blocks';
    }
  }

  return $json;
}

add_filter( 'lzb/import_json', 'my_lzb_import_json' );
```

Returning anything but an array raises a `TypeError` at the `foreach` that follows. Returning an empty array imports nothing and shows no notice, because the success notices are built from the list of created post IDs. Lazy Blocks keeps its own callback here at priority 10, converting any pre-2.5.0 template item that still has a `data` sub-array.

The screen this runs behind is [Export / Import](https://www.lazyblocks.com/docs/export-blocks/).

---

# lzb/export_json/die

Source: https://www.lazyblocks.com/docs/php-filters/lzb-export_json-die/

Keeps `export_json()` from calling `die()`, so a test can assert on the exported JSON instead of losing the PHPUnit process.

This exists for the plugin's own test suite. A test that reaches the `die()` takes the whole runner down and PHPUnit reports a crashed process rather than the failed assertion.

## Attributes

| Name   | Type        | Description                                         |
| ------ | ----------- | --------------------------------------------------- |
| `$die` | **Boolean** | whether to terminate the request, `true` by default |

## Usage

```php title="PHP"
// In a PHPUnit test case.
add_filter( 'lzb/export_json/die', '__return_false' );

ob_start();
lazyblocks()->tools()->export_json( array( $block_id ) );
$exported = json_decode( ob_get_clean(), true );

$this->assertSame( 'lazyblock/my-block', $exported[0]['slug'] );

remove_filter( 'lzb/export_json/die', '__return_false' );
```

The filter runs after the `Content-disposition` headers and the JSON body have already been written. Returning a falsy value on a live site therefore does not cancel the download, it lets the admin page continue rendering and appends its HTML to the end of the downloaded `.json` file. Leave the default `true` outside of tests.

---

# lzb/wpml/translated_attributes

Source: https://www.lazyblocks.com/docs/php-filters/lzb-wpml-translated_attributes/

Filters the block attributes handed to WPML for translation.

Lazy Blocks builds this list from the controls whose **Translate** setting is on. Use the filter to add an attribute your own code stores on the block, which has no control behind it and so would never reach WPML on its own.

## Attributes

| Name                   | Type      | Description                             |
| ---------------------- | --------- | --------------------------------------- |
| `$translated_controls` | **Array** | WPML config nodes for this block         |
| `$block`               | **Array** | block data                               |

Each item is a WPML config node rather than a plain attribute name. A single attribute looks like this:

```php title="PHP"
array(
  'value' => '',
  'attr'  => array(
    'name' => 'my-attribute',
  ),
)
```

An attribute holding a JSON array, the shape a Repeater control produces, nests its inner attributes under a `*` key:

```php title="PHP"
array(
  'value' => '',
  'attr'  => array(
    'name'     => 'my-repeater',
    'encoding' => 'json',
  ),
  'key'   => array(
    'value' => '',
    'attr'  => array(
      'name' => '*',
    ),
    'key'   => array(
      array(
        'value' => '',
        'attr'  => array( 'name' => 'inner-attribute' ),
      ),
    ),
  ),
)
```

## Usage

```php title="PHP"
function my_lzb_wpml_translated_attributes( $translated_controls, $block ) {
  if ( 'my-block' !== $block['slug'] ) {
    return $translated_controls;
  }

  $translated_controls[] = array(
    'value' => '',
    'attr'  => array(
      'name' => 'my-attribute',
    ),
  );

  return $translated_controls;
}

add_filter( 'lzb/wpml/translated_attributes', 'my_lzb_wpml_translated_attributes', 10, 2 );
```

Returning an empty array keeps the block out of the generated WPML configuration entirely.

See [Multilingual](https://www.lazyblocks.com/docs/multilingual/) for how Lazy Blocks and WPML work together.

---

# lzb_pro/block_style/template

Source: https://www.lazyblocks.com/docs/php-filters/lzb_pro-block_style-template/

Points a block at a stylesheet the theme does not carry, which is what a plugin shipping its own template blocks needs.

A block whose **Output Method** is **Theme Template** picks up two optional stylesheets next to its template, `blocks/BLOCK-SLUG/block.css` and `blocks/BLOCK-SLUG/editor.css`. `find_style_template()` resolves each name with `locate_template()`, fires this filter, and registers the file when `file_exists()` passes. Blocks using any other output method never reach it, because their CSS comes from the block builder's own style fields.

## Attributes

| Name             | Type       | Description                                                                            |
| ---------------- | ---------- | -------------------------------------------------------------------------------------- |
| `$template`      | **String** | path found by `locate_template()`, empty when the theme has no such file               |
| `$template_name` | **String** | name being looked up, `blocks/BLOCK-SLUG/block.css` or `blocks/BLOCK-SLUG/editor.css`  |
| `$block`         | **Array**  | block data, the same array [lzb/block_data](https://www.lazyblocks.com/docs/php-filters/lzb-block_data/) returns |
| `$context`       | **String** | `block` for the front end stylesheet, `editor` for the editor one                      |

`$context` is not the render location. It names which of the two stylesheets is being resolved, so a handler that only wants to replace the front end file checks for `block`.

## Additional Filters

| Name                                         | Arguments                                     | Description                      |
| -------------------------------------------- | --------------------------------------------- | -------------------------------- |
| `lazyblock/BLOCK_SLUG/block_style_template`  | `$template, $template_name, $block`           | one block's front end stylesheet |
| `lazyblock/BLOCK_SLUG/editor_style_template` | `$template, $template_name, $block`           | one block's editor stylesheet    |
| `lazyblock/BLOCK_SLUG/style_template`        | `$template, $template_name, $block, $context` | one block, both stylesheets      |

## Usage

```php title="PHP"
function my_lzb_pro_block_style_template( $template, $template_name, $block, $context ) {
  // Ship the front end CSS with the plugin, and let the theme override it
  // by placing a file of the same name.
  if ( $template || 'block' !== $context ) {
    return $template;
  }

  $fallback = plugin_dir_path( __FILE__ ) . $template_name;

  return file_exists( $fallback ) ? $fallback : $template;
}

add_filter( 'lzb_pro/block_style/template', 'my_lzb_pro_block_style_template', 10, 4 );
```

Return an absolute filesystem path, not a URL. Lazy Blocks Pro reads the file's modification time to build a cache-busting version and then converts the path to a URL by matching it against the content, theme, child theme and plugin directories in that order. A file outside all of them falls back to matching against `ABSPATH`, and a path that matches nothing produces no stylesheet at all.

The script counterpart is [lzb_pro/block_script/template](https://www.lazyblocks.com/docs/php-filters/lzb_pro-block_script-template/). Where these files live is covered in [Styles and Scripts](https://www.lazyblocks.com/docs/blocks-code/styles-scripts/).

---

# lzb_pro/block_script/template

Source: https://www.lazyblocks.com/docs/php-filters/lzb_pro-block_script-template/

Points a block at a view script the theme does not carry, which is what a plugin shipping its own template blocks needs.

A block whose **Output Method** is **Theme Template** picks up an optional `blocks/BLOCK-SLUG/view.js` next to its template. `find_script_template()` resolves that name with `locate_template()`, fires this filter, and registers the file as the block's `view_script` when `file_exists()` passes, so WordPress loads it only on pages where the block is present. Blocks using any other output method never reach it, because their JavaScript comes from the block builder's own script field.

## Attributes

| Name             | Type       | Description                                                                            |
| ---------------- | ---------- | -------------------------------------------------------------------------------------- |
| `$template`      | **String** | path found by `locate_template()`, empty when the theme has no such file               |
| `$template_name` | **String** | name being looked up, `blocks/BLOCK-SLUG/view.js`                                      |
| `$block`         | **Array**  | block data, the same array [lzb/block_data](https://www.lazyblocks.com/docs/php-filters/lzb-block_data/) returns |
| `$context`       | **String** | always `view`, the only script a block template has                                    |

## Additional Filters

| Name                                        | Arguments                                     | Description                   |
| ------------------------------------------- | --------------------------------------------- | ----------------------------- |
| `lazyblock/BLOCK_SLUG/view_script_template` | `$template, $template_name, $block`           | one block, positional variant |
| `lazyblock/BLOCK_SLUG/script_template`      | `$template, $template_name, $block, $context` | one block                     |

## Usage

```php title="PHP"
function my_lzb_pro_block_script_template( $template, $template_name, $block, $context ) {
  // Serve the minified build in production and the readable file while
  // SCRIPT_DEBUG is on.
  if ( ! $template || ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ) {
    return $template;
  }

  $minified = preg_replace( '/\.js$/', '.min.js', $template );

  return file_exists( $minified ) ? $minified : $template;
}

add_filter( 'lzb_pro/block_script/template', 'my_lzb_pro_block_script_template', 10, 4 );
```

Return an absolute filesystem path, not a URL. Lazy Blocks Pro reads the file's modification time for the version string and then converts the path to a URL by matching it against the content, theme, child theme and plugin directories in that order, falling back to `ABSPATH`. A path outside all of those registers no script and fails silently.

The script is registered in the footer with no dependencies, so a file expecting jQuery or `wp.data` has to wait for them itself. The stylesheet counterpart is [lzb_pro/block_style/template](https://www.lazyblocks.com/docs/php-filters/lzb_pro-block_style-template/), and where these files live is covered in [Styles and Scripts](https://www.lazyblocks.com/docs/blocks-code/styles-scripts/).

---

# lzb_pro/preload_blocks

Source: https://www.lazyblocks.com/docs/php-filters/lzb_pro-preload_blocks/

Turns off editor block preloading, which is the switch to reach for when a post with many blocks trips the server's request limit or when a preview will not stop showing stale markup.

The default is `true`. With preloading on, Lazy Blocks Pro captures the HTML of every block WordPress renders while the edit screen loads and hands it to the editor as `window.lzbProBlocksPreloaded`, so previews appear immediately instead of each block fetching its own render over REST. Two situations call for switching it off. A post carrying dozens of blocks issues that many render requests as the screen loads, and a host that rate limits will answer some of them with a [504 or 429](https://www.lazyblocks.com/docs/troubleshooting/receive-a-504-and-429-error-too-many-requests/). And while debugging a block whose preview does not match its output, the preloaded copy is the one you see first, so turning this off forces a fresh render on every change.

## Attributes

| Name       | Type        | Description                               |
| ---------- | ----------- | ----------------------------------------- |
| `$enabled` | **Boolean** | preload block previews, `true` by default |

## Usage

```php title="PHP"
function my_lzb_pro_preload_blocks( $enabled ) {
  // Skip preloading on the post types whose pages carry the most blocks,
  // where the burst of render requests hits the host's rate limit.
  $screen = function_exists( 'get_current_screen' ) ? get_current_screen() : null;

  if ( $screen && in_array( $screen->post_type, array( 'page', 'landing' ), true ) ) {
    return false;
  }

  return $enabled;
}

add_filter( 'lzb_pro/preload_blocks', 'my_lzb_pro_preload_blocks' );
```

The switch is narrower than it looks. Returning `false` skips the script and the localised data, and nothing else. Both render filters Lazy Blocks Pro registers stay hooked, including the one that blanks Inner Blocks attributes in the editor, so turning preloading off does not restore those values in the editor render.

Removing the data also removes it from the Yoast and Rank Math integration, which seeds its content cache from the same `window.lzbProBlocksPreloaded` object. That integration falls back to fetching each block over REST, so the SEO analysis still sees the block output, one request per block instead of none.

The feature itself is described in [Performance](https://www.lazyblocks.com/docs/performance/).

---

# lzb_pro/rich_text/names

Source: https://www.lazyblocks.com/docs/php-filters/lzb_pro-rich_text-names/

Declares the `` names of a block that the static parser cannot find.

Lazy Blocks Pro finds the component by scanning the block code for `` tags. A block using the PHP output method builds those tags at runtime, inside a loop or a conditional, so the scan comes back empty and the names never get registered as block attributes. List them here instead.

## Attributes

| Name     | Type      | Description                                                     |
| -------- | --------- | --------------------------------------------------------------- |
| `$names` | **Array** | component names found in the block code, a flat list of strings |
| `$block` | **Array** | block data                                                      |

Three things read the result:

| Where                         | What it does with the names                                                                                                                             |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `register_block_attributes()` | registers each name as a `string` block attribute, unless a control already registers it, the name is reserved, or it belongs to a Save in Meta control |
| `get_translatable_names()`    | offers the names without a control behind them to WPML through [lzb/wpml/translated_attributes](https://www.lazyblocks.com/docs/php-filters/lzb-wpml-translated_attributes/)      |
| `get_exclusive_names()`       | works out which names the component alone renders, so the editor can skip the server round trip while typing                                            |

## Usage

```php title="PHP"
function my_lzb_pro_rich_text_names( $names, $block ) {
  if ( 'lazyblock/team-member' !== $block['slug'] ) {
    return $names;
  }

  // The tags are printed from a foreach in the PHP output method, so the
  // scan of the block code never sees these two names.
  $names[] = 'member-name';
  $names[] = 'member-role';

  return array_values( array_unique( $names ) );
}

add_filter( 'lzb_pro/rich_text/names', 'my_lzb_pro_rich_text_names', 10, 2 );
```

Return a flat array of strings. The names are used as array keys and as block attribute names, so a nested array or an associative one breaks attribute registration.

Eight names are dropped further down whatever this filter returns: `lazyblock`, `className`, `align`, `anchor`, `blockId`, `blockUniqueClass`, `ghostkitSpacings` and `ghostkitSR`. They belong to the plugin and to block supports, and the front end refuses to print them too.

A name that never reaches this list is not registered as an attribute, so whatever a person types into it is dropped the moment the post is saved. The component itself is covered in [Rich Text](https://www.lazyblocks.com/docs/blocks-code/rich-text/).

---

# lzb_pro/rich_text/is_name_rendered

Source: https://www.lazyblocks.com/docs/php-filters/lzb_pro-rich_text-is_name_rendered/

Tells Lazy Blocks Pro that a `` value is printed a second time somewhere in the block code, in a form the built-in patterns do not recognise.

When the component is the only thing rendering a value, the editor updates the text on the client and never asks the server. When the value is also printed elsewhere, say in a `title` attribute or a data attribute, skipping the server render leaves that second copy stale. Lazy Blocks Pro works this out by pattern matching, and this filter is where a block with its own way of reading values corrects the result.

## Attributes

| Name           | Type        | Description                                                         |
| -------------- | ----------- | ------------------------------------------------------------------- |
| `$is_rendered` | **Boolean** | always `false`, this is the fallback return of `is_name_rendered()` |
| `$name`        | **String**  | component name being tested                                         |
| `$code`        | **String**  | block code with the `` tags removed                     |

Two patterns run before the filter, and a match on either returns `true` without ever reaching a handler:

| Pattern                                      | Matches                                                                  |
| -------------------------------------------- | ------------------------------------------------------------------------ |
| `{{ ... name ... }}`                         | `{{my-title}}`, `{{{my-title}}}`, `{{#if my-title}}`, `{{my-title.sub}}` |
| `$attributes['name']` and `$context['name']` | the PHP output method reading the value directly                         |

A handler can therefore only turn a `false` into a `true`. There is no way to cancel a match the built-in patterns already made.

## Usage

```php title="PHP"
function my_lzb_pro_rich_text_is_name_rendered( $is_rendered, $name, $code ) {
  // Our PHP blocks read values through a helper rather than $attributes[],
  // which is why the built-in pattern misses them.
  $pattern = '/acme_field\(\s*[\'"]' . preg_quote( $name, '/' ) . '[\'"]\s*\)/';

  return (bool) preg_match( $pattern, $code );
}

add_filter( 'lzb_pro/rich_text/is_name_rendered', 'my_lzb_pro_rich_text_is_name_rendered', 10, 3 );
```

Returning `true` takes the name out of the exclusive set, and the editor then refetches the server preview on every keystroke in that field. Returning `false`, the default, leaves editing on the client and risks a second copy of the value going stale in the preview until the block is reselected. The result is cached per block for the request, so a handler runs once per name and not once per render.

Which names end up exclusive is decided from the list [lzb_pro/rich_text/names](https://www.lazyblocks.com/docs/php-filters/lzb_pro-rich_text-names/) returns.

---

# lzb_pro/rich_text/textual_control_types

Source: https://www.lazyblocks.com/docs/php-filters/lzb_pro-rich_text-textual_control_types/

Lists the control types `` is allowed to take over.

A control's registered `type` is not enough to decide this. Image, Gallery and Repeater are all registered as `string` because they store JSON, and letting the component print one of those would dump the raw JSON on the page. Lazy Blocks Pro keeps an explicit list instead, and a custom control that stores a plain string has to be added to it.

## Attributes

| Name     | Type      | Description                             |
| -------- | --------- | --------------------------------------- |
| `$types` | **Array** | control types the component may bind to |

The default list is `text`, `textarea`, `rich_text`, `classic_editor`, `code_editor`, `url` and `email`.

The filter fires at two points, and both have to agree:

| Where                         | What it decides                                                                                                                                                            |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enqueue_block_editor_assets` | the `textualControlTypes` list handed to the editor script, which decides whether the component renders as an editable field or as a plain fallback with a console warning |
| `is_textual_control()`        | whether the front end prints the value or returns an empty string for that tag                                                                                             |

## Usage

```php title="PHP"
function my_lzb_pro_rich_text_textual_control_types( $types ) {
  // Custom control storing a plain string, so the component can edit it
  // inline the same way it edits a Text control.
  $types[] = 'acme_heading';

  return $types;
}

add_filter( 'lzb_pro/rich_text/textual_control_types', 'my_lzb_pro_rich_text_textual_control_types' );
```

A `` bound to a control whose type is not on the list renders as an empty string on the front end. Adding a type that stores JSON does not fix the JSON, it prints it: the value is escaped with `esc_html()` and the reader sees the serialised array in the page.

Whether the value is treated as markup is a separate decision, made from a constant with no filter behind it. Only `rich_text` and `classic_editor` keep their HTML through `wp_kses_post()`. Every other type on this list, including one you add, is escaped with `esc_html()`, so formatting typed into it comes out as visible tags.

The editor list is localised while `enqueue_block_editor_assets` runs, so a filter registered later than that changes the front end only, and the editor goes on offering a field the front end then refuses to print. The component itself is covered in [Rich Text](https://www.lazyblocks.com/docs/blocks-code/rich-text/).

---

# lzb_pro/plugin_path

Source: https://www.lazyblocks.com/docs/php-filters/lzb_pro-plugin_path/

Filters the absolute path Lazy Blocks Pro loads its own class files and build assets from.

The Pro plugin bundled inside a theme or a parent plugin sits somewhere `plugin_dir_path( __FILE__ )` still reports correctly, so this filter is rarely needed. It exists as the counterpart of [lzb_pro/plugin_url](https://www.lazyblocks.com/docs/php-filters/lzb_pro-plugin_url/), for a setup that moves the files after the plugin header has been read.

## Attributes

| Name           | Type       | Description                                                                   |
| -------------- | ---------- | ----------------------------------------------------------------------------- |
| `$plugin_path` | **String** | `plugin_dir_path( __FILE__ )` of `lazy-blocks-pro.php`, with a trailing slash |

Three things read it:

| Where                            | What it loads                                                         |
| -------------------------------- | --------------------------------------------------------------------- |
| `init_options()`                 | every `classes/class-*.php` file the plugin needs                     |
| `include_control_dependencies()` | the Pro control classes, on `lzb/init` at priority 6                  |
| `Lazy_Blocks_Pro_Assets`         | the `.asset.php` files holding each script's dependencies and version |

## Usage

```php title="PHP"
// In a must-use plugin, so it is registered before Lazy Blocks Pro loads.
function my_lzb_pro_plugin_path( $plugin_path ) {
  return WP_CONTENT_DIR . '/vendor/lazy-blocks-pro/';
}

add_filter( 'lzb_pro/plugin_path', 'my_lzb_pro_plugin_path' );
```

The plugin builds its `require_once` calls from this value, so a path that does not exist is a fatal error rather than a missing feature. Keep the trailing slash: the code concatenates the value with `classes/class-assets.php` and similar relative paths.

`init_options()` runs while the plugin file itself is loading, before `plugins_loaded`, so a filter registered from a normal plugin or from a theme is too late for the first block of `require_once` calls. Only a must-use plugin runs early enough. The control dependencies loaded on `lzb/init` see the filter whenever it was added.

Changing the asset URL is a different filter, [lzb_pro/plugin_url](https://www.lazyblocks.com/docs/php-filters/lzb_pro-plugin_url/), and [Include Lazy Blocks within theme or plugin](https://www.lazyblocks.com/docs/examples/include-lazy-blocks-within-theme-or-plugin/) sets that one for you.

---

# lzb_pro/plugin_url

Source: https://www.lazyblocks.com/docs/php-filters/lzb_pro-plugin_url/

Filters the URL the Pro editor scripts and styles are loaded from.

Lazy Blocks Pro shipped inside a theme or another plugin sits at a URL `plugin_dir_url()` cannot work out, because WordPress only knows about files under the plugins directory. Point this filter at the real location and the Pro editor assets resolve again.

## Attributes

| Name          | Type       | Description                                                                  |
| ------------- | ---------- | ---------------------------------------------------------------------------- |
| `$plugin_url` | **String** | `plugin_dir_url( __FILE__ )` of `lazy-blocks-pro.php`, with a trailing slash |

`Lazy_Blocks_Pro_Assets::register_script()` and `register_style()` are the only readers. Each one appends the build path and the extension, so `build/component-rich-text` becomes `<plugin_url>build/component-rich-text.js`.

## Usage

```php title="PHP"
function my_lzb_pro_plugin_url( $plugin_url ) {
  return get_stylesheet_directory_uri() . '/vendor/lazy-blocks-pro/';
}

add_filter( 'lzb_pro/plugin_url', 'my_lzb_pro_plugin_url' );
```

`lazyblocks()->include_within( $url )` already registers this filter along with `lzb/plugin_url`, so a theme following [Include Lazy Blocks within theme or plugin](https://www.lazyblocks.com/docs/examples/include-lazy-blocks-within-theme-or-plugin/) does not need to add it by hand.

A wrong URL is quiet. The scripts still register and enqueue, the browser gets a 404 for each one, and the block builder loads without the Pro panels: no Rich Text component, no conditional logic, no collections. Keep the trailing slash, because the build path is concatenated straight onto the value.

The path counterpart is [lzb_pro/plugin_path](https://www.lazyblocks.com/docs/php-filters/lzb_pro-plugin_path/).

---

# lzb/handlebars/object

Source: https://www.lazyblocks.com/docs/php-actions/lzb-handlebars-object/

Registers a Handlebars helper of your own, which is the only way to call a PHP function from a block's Handlebars template.

It fires at the end of `LazyBlocks_Handlebars::prepare()`, on the WordPress `init` action, after the built-in helpers are in place. Registering a helper under a name that already exists replaces it, so this is also where `truncate`, `compare`, `math`, `date_i18n`, `do_shortcode` and `wp_get_attachment_image` can be swapped for versions of your own.

## Attributes

| Name          | Type       | Description                                               |
| ------------- | ---------- | --------------------------------------------------------- |
| `$handlebars` | **Object** | `Handlebars\Handlebars` engine used to render every block |

## Usage

```php title="PHP"
function my_lzb_handlebars_object( $handlebars ) {
  // {{price 1499 'EUR'}} renders as "€14.99".
  $handlebars->registerHelper(
    'price',
    function ( $cents, $currency = 'USD' ) {
      $symbols = array( 'USD' => '$', 'EUR' => '&euro;', 'GBP' => '&pound;' );
      $symbol  = isset( $symbols[ $currency ] ) ? $symbols[ $currency ] : '';

      return new \Handlebars\SafeString(
        $symbol . number_format_i18n( (int) $cents / 100, 2 )
      );
    }
  );
}

add_action( 'lzb/handlebars/object', 'my_lzb_handlebars_object' );
```

Wrap markup in `\Handlebars\SafeString`, as above. A helper's return value is escaped unless it is a `SafeString`, so a helper returning `<strong>` prints the tags as text. Return a plain string for anything that should be escaped, which is everything the user typed.

Arguments arrive as strings from the template, so cast before doing arithmetic. A helper called with fewer arguments than it declares can receive the Handlebars options array in place of the missing one rather than nothing at all, which is why the built-in helpers inspect their optional arguments before using them.

The helpers Lazy Blocks ships with are listed in [Handlebars](https://www.lazyblocks.com/docs/blocks-code/handlebars/).

---

# lzb/init

Source: https://www.lazyblocks.com/docs/php-actions/lzb-init/

Fires once Lazy Blocks has loaded its classes and its controls, which is the point where `lazyblocks()->add_block()` can be called.

Lazy Blocks hooks this to the WordPress `init` action at priority 5. Its own controls register themselves on `lzb/init` at priority 5, so a handler left at the default priority 10 sees every control type and can reference `text`, `image` or `repeater` by name. Register a block earlier than that and its controls are silently dropped, because `prepare_block_controls()` keeps only the controls whose `type` it recognises.

## Attributes

This action receives no arguments.

## Usage

```php title="PHP"
function my_lzb_init() {
  lazyblocks()->add_block(
    array(
      'title'    => 'Notice',
      'slug'     => 'lazyblock/notice',
      'icon'     => 'dashicons dashicons-info',
      'category' => 'text',
      'controls' => array(
        'control_notice_text' => array(
          'type'    => 'text',
          'name'    => 'notice-text',
          'label'   => 'Notice text',
          'default' => 'Heads up.',
        ),
      ),
      'code'     => array(
        'output_method' => 'html',
        'frontend_html' => '<div useBlockProps class="notice">{{notice-text}}</div>',
      ),
    )
  );
}

add_action( 'lzb/init', 'my_lzb_init' );
```

The array is merged over the block defaults, so every key left out keeps its default value. Two keys have no usable default. `slug` must carry a namespace, and a block without one never reaches `register_block_type()`. The keys of `controls` are arbitrary IDs, while each control needs its own `name`, which is the attribute name the template reads.

Registering blocks from PHP is covered in [Include Lazy Blocks within theme or plugin](https://www.lazyblocks.com/docs/examples/include-lazy-blocks-within-theme-or-plugin/). To change the array before Lazy Blocks stores it, use [lzb/add_user_block](https://www.lazyblocks.com/docs/php-filters/lzb-add_user_block/).

---

# lzb/add_collection

Source: https://www.lazyblocks.com/docs/php-actions/lzb-add_collection/

Registers a block collection from PHP, so a theme or a plugin can ship its own slug namespace instead of asking the site owner to create one in the block builder.

`lazyblocks()->add_collection()` fires this action and does nothing else. The free plugin has no collections, and the listener that stores the data lives in Lazy Blocks Pro, which is why the call is safe to make on a site running either version.

## Attributes

| Name    | Type      | Description     |
| ------- | --------- | --------------- |
| `$data` | **Array** | collection data |

Lazy Blocks Pro reads these keys:

| Name        | Type        | Description                                                                                              |
| ----------- | ----------- | -------------------------------------------------------------------------------------------------------- |
| `namespace` | **String**  | slug prefix, the part before the slash in `acme/pricing-card`                                            |
| `label`     | **String**  | name shown in the block builder slug field                                                               |
| `register`  | **Boolean** | call `registerBlockCollection()` so the inserter groups these blocks under the label, `false` by default |

`namespace` and `label` are read without a fallback, so an array missing either one throws an undefined-index warning while the block builder loads its collections.

## Usage

```php title="PHP"
function my_lzb_add_collection() {
  lazyblocks()->add_collection(
    array(
      'namespace' => 'acme',
      'label'     => 'Acme Blocks',
      'register'  => true,
    )
  );
}

add_action( 'init', 'my_lzb_add_collection' );
```

A namespace that already exists is ignored rather than overwritten, and the built-in `lazyblock` collection is processed first, so a collection cannot take that namespace over.

A collection added this way carries `isEditable` as `false`: it appears in the slug field of the block builder and can be selected, but the rename and delete buttons stay hidden, unlike a collection created on that screen and stored in the `lazy_blocks_pro_block_collections` option. Removing it means removing the `add_collection()` call, which leaves any block already saved under that namespace with a slug nothing registers.

The screen this shows up on is [Collections](https://www.lazyblocks.com/docs/managing-blocks/collections/).

---

# lzb/import/block

Source: https://www.lazyblocks.com/docs/php-actions/lzb-import-block/

Runs after one block has been imported from a JSON file, which is where an imported block gets a term, a namespace of its own or a note about where it came from.

It fires at the end of `import_block()`, after `wp_insert_post()` has created the `lazyblocks` post and after every `lazyblocks_` meta has been written. The post exists and is published, so `update_post_meta()`, `wp_set_object_terms()` and `wp_update_post()` all work on `$post_id` straight away. Importing a file with ten blocks fires the action ten times.

## Attributes

| Name       | Type      | Description                          |
| ---------- | --------- | ------------------------------------ |
| `$post_id` | **Int**   | post ID of the block just created    |
| `$data`    | **Array** | the block as it appeared in the file |

`$data` is the exported block, not the stored meta. It has `id`, `title`, `icon`, `keywords`, `slug`, `description`, `category`, `category_label`, `supports`, `controls`, `code`, `style`, `script`, `styles` and `condition`. Two of those do not match what was saved. `id` is the post ID the block had on the site it was exported from, and `slug` carries the full name with its namespace while the stored `lazyblocks_slug` meta holds only the part after the slash.

## Usage

```php title="PHP"
function my_lzb_import_block( $post_id, $data ) {
  // Move imported blocks into the agency's own namespace, so they cannot
  // collide with blocks the client builds later.
  $name = substr( $data['slug'], strpos( $data['slug'], '/' ) + 1 );

  update_post_meta( $post_id, 'lazyblocks_slug', 'agency/' . $name );
  update_post_meta( $post_id, 'imported_from_id', $data['id'] );
}

add_action( 'lzb/import/block', 'my_lzb_import_block', 10, 2 );
```

Write the slug back through `lazyblocks_slug` without a namespace if you want the default `lazyblock/` one, because Lazy Blocks prepends it when the block data is assembled. Three meta keys cannot be written from here at all. `lazyblocks_code_editor_html`, `lazyblocks_code_frontend_html` and `lazyblocks_script_view` are guarded against direct meta writes and silently rejected for anyone without the `unfiltered_html` capability, which on a multisite install is everyone below super admin. [lzb/allow_unfiltered_html](https://www.lazyblocks.com/docs/php-filters/lzb-allow_unfiltered_html/) is the override.

To rewrite the payload before any post is inserted, use [lzb/import_json](https://www.lazyblocks.com/docs/php-filters/lzb-import_json/). The template equivalent of this action is [lzb/import/template](https://www.lazyblocks.com/docs/php-actions/lzb-import-template/).

---

# lzb/import/template

Source: https://www.lazyblocks.com/docs/php-actions/lzb-import-template/

Runs after one block template has been imported from a JSON file, which is where an imported template gets pointed at the post types this site actually has.

It fires at the end of `import_template()`, once the `lazyblocks_templates` post exists and its four metas have been written. Import stops before this point when a template for any of the same post types is already registered, so the action only fires for templates that were created. A file holding several templates fires it once per template.

## Attributes

| Name       | Type      | Description                             |
| ---------- | --------- | --------------------------------------- |
| `$post_id` | **Int**   | post ID of the template just created    |
| `$data`    | **Array** | the template as it appeared in the file |

`$data` has `id`, `title`, `post_types`, `blocks` and `template_lock`. `id` is the post ID from the site the template was exported from. The metas written from it are `_lzb_template_post_types`, `_lzb_template_blocks` (URL encoded JSON), `_lzb_template_lock` and `_lzb_template_convert_blocks_to_content`, which the importer sets to `true` while the template editor's own default is `false`.

## Usage

```php title="PHP"
function my_lzb_import_template( $post_id, $data ) {
  // The export was made on a site with a "case-study" post type this one
  // calls "project". Retarget the template instead of failing quietly.
  $post_types = array_map(
    function ( $type ) {
      return 'case-study' === $type ? 'project' : $type;
    },
    (array) $data['post_types']
  );

  update_post_meta( $post_id, '_lzb_template_post_types', $post_types );
}

add_action( 'lzb/import/template', 'my_lzb_import_template', 10, 2 );
```

`_lzb_template_post_types` is an array of post type slugs, and a template pointing at a post type that does not exist is simply never applied, with no notice anywhere. `_lzb_template_blocks` has to stay URL encoded JSON, so run any replacement through `rawurlencode( wp_json_encode( ... ) )` the way the importer does.

To rewrite the payload before any post is inserted, use [lzb/import_json](https://www.lazyblocks.com/docs/php-filters/lzb-import_json/). The block equivalent of this action is [lzb/import/block](https://www.lazyblocks.com/docs/php-actions/lzb-import-block/), and templates themselves are covered in [Templates](https://www.lazyblocks.com/docs/templates/).

---

# lzb/cache_cleared

Source: https://www.lazyblocks.com/docs/php-actions/lzb-cache_cleared/

Fires once every `lzb_blocks_cache_` transient has been deleted, so anything you built on top of the block list can be rebuilt at the same moment.

A page cache holding rendered blocks, or your own index built from `get_blocks()`, goes stale on exactly the same events that invalidate the Lazy Blocks cache. Hooking this action saves you from listing those events again.

The action takes no arguments. It is the last statement of `clear_blocks_cache()`, after the transients are gone and after the in-memory block list and the cache key hash have been reset, so a handler calling `lazyblocks()->blocks()->get_blocks()` gets a freshly built list rather than the one that was just thrown away.

## Triggers

| Event                                                    | Fires when                                             |
| -------------------------------------------------------- | ------------------------------------------------------ |
| `save_post_lazyblocks`                                   | a block is saved in the block builder                  |
| `delete_post`, `wp_trash_post`, `untrash_post`           | the post is of the `lazyblocks` type                   |
| `activated_plugin`, `deactivated_plugin`, `switch_theme` | always                                                 |
| `upgrader_process_complete`                              | the update was a plugin or a theme                     |
| Clear Cache link on the Lazy Blocks screen               | the nonce checks out and the user has `manage_options` |
| `lazyblocks()->blocks()->clear_blocks_cache()`           | called from your own code                              |

## Usage

```php title="PHP"
function my_lzb_cache_cleared() {
  // Our block index is built from get_blocks(), so it goes stale at
  // exactly the same moments the plugin's own cache does.
  delete_transient( 'acme_block_index' );

  // WP Super Cache holds rendered pages containing those blocks.
  if ( function_exists( 'wp_cache_clear_cache' ) ) {
    wp_cache_clear_cache();
  }
}

add_action( 'lzb/cache_cleared', 'my_lzb_cache_cleared' );
```

Nothing is passed in, so a handler cannot tell which trigger it came from. Activating a plugin fires it once per plugin, and a bulk activation of ten plugins fires it ten times, so keep the work here cheap or debounce it yourself.

Available since Lazy Blocks 4.2.0. How long the cache lives in the first place is [lzb/cache_expiration](https://www.lazyblocks.com/docs/php-filters/lzb-cache_expiration/).

---

# lzb.constructor.panels

Source: https://www.lazyblocks.com/docs/js-filters/lzb-constructor-panels/

Filters the collapsible panels the block builder puts in the Inspector under the general settings. Add a panel here when an extension keeps its own data on the block and needs somewhere in the builder to edit it.

The default array holds four panels in this order: `style-variations`, `supports`, `supports-ghost-kit` and `condition`. All four start collapsed.

## Attributes

| Name     | Type       | Description                                |
| -------- | ---------- | ------------------------------------------ |
| `panels` | **Array**  | panel definitions, rendered in array order |
| `data`   | **Object** | `blockData`, `updateBlockData`             |

Each panel is an object with four keys:

| Name          | Type         | Description                                                       |
| ------------- | ------------ | ----------------------------------------------------------------- |
| `name`        | **String**   | React key of the panel, and the handle other extensions match on  |
| `title`       | **String**   | heading shown on the panel                                        |
| `component`   | **Function** | React component type, rendered with `data` and `updateData` props |
| `initialOpen` | **Boolean**  | whether the panel is expanded on first render                     |

`component` is the component itself, not an element. The builder writes `` inside a `PanelBody`, so a panel that sets `component` to `` hands React an element where it expects a type and nothing renders.

`data.updateBlockData` shallow merges the object you give it into the block data, so a panel writes one field with `updateData({ my_field: value })`.

## Usage

The Relationships panel finds the `condition` panel and splices itself in after it, which keeps the ordering stable when other extensions add panels too.

```js title="JS"
const { TextControl } = wp.components;

function TrackingPanel({ data, updateData }) {
  return (
    <TextControl
      label="Tracking ID"
      value={data.my_tracking_id || ""}
      onChange={(value) => updateData({ my_tracking_id: value })}
    />
  );
}

wp.hooks.addFilter(
  "lzb.constructor.panels",
  "my.custom.namespace",
  function (panels) {
    const conditionIndex = panels.findIndex(
      (panel) => panel.name === "condition",
    );
    const insertIndex =
      conditionIndex === -1 ? panels.length : conditionIndex + 1;

    panels.splice(insertIndex, 0, {
      name: "my-tracking",
      title: "Tracking",
      component: TrackingPanel,
      initialOpen: false,
    });

    return panels;
  },
);
```

The builder calls `panels.map()` on the result, so returning anything but an array throws `panels.map is not a function` and leaves the block builder Inspector blank. A handler that decides to do nothing must return the incoming `panels`.

---

# lzb.constructor.code-settings

Source: https://www.lazyblocks.com/docs/js-filters/lzb-constructor-code-settings/

The Code box in the block builder renders through six filters, one per part. Reach for them to put a control of your own in the code toolbar, or to fill the empty slot under the editor with a live preview.

There is no filter under the bare `lzb.constructor.code-settings` name. Every one of the six carries a suffix.

## Available Filters

| Name                                            | Description                                                                                   |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `lzb.constructor.code-settings.output-method`   | the output method `Select`, or the plain `CSS` / `JS` label shown on a style or script tab    |
| `lzb.constructor.code-settings.additional`      | the sliders dropdown, holding Unified Block Code, With Editor Style and Code Output in Editor |
| `lzb.constructor.code-settings.info`            | the question mark dropdown, a `Notice` describing the current output method                   |
| `lzb.constructor.code-settings.output-code`     | the toolbar and the code editor, `null` when the output method is Theme Template              |
| `lzb.constructor.code-settings.output-template` | the toolbar and the read-only theme file tree, `null` for every other output method           |
| `lzb.constructor.code-settings.preview`         | an empty slot below the editor, `null` by default                                             |

## Attributes

| Name     | Type            | Description                                            |
| -------- | --------------- | ------------------------------------------------------ |
| `render` | **JSX \| null** | the element about to be rendered, different per filter |
| `data`   | **Object**      | `props`, `tab`, `setTab`                               |

| Name     | Type         | Description                                                                      |
| -------- | ------------ | -------------------------------------------------------------------------------- |
| `props`  | **Object**   | the Code box props: `data`, `updateData`, `onTabChange`                          |
| `tab`    | **String**   | active tab: `frontend`, `editor`, `block-style`, `editor-style` or `view-script` |
| `setTab` | **Function** | switches the active tab                                                          |

The block being edited sits one level deeper than it looks. Read it as `data.props.data`, not `data.data`, and write to it with `data.props.updateData({ code_output_method: "php" })`, which shallow-merges the object you pass in, replacing whole values rather than merging into them.

`preview` is handed `null` and has no core UI behind it, so it is a slot to fill rather than markup to change. Whatever it returns is wrapped in a `Box` under the code editor.

`additional` and `info` are the bodies of two `Dropdown` components, so they fire only while their dropdown is open, not on every render of the box.

`output-method`, `additional` and `info` render inside the toolbars that `output-code` and `output-template` return. Replacing either of those two therefore takes the output method selector and both dropdown buttons off the screen with it.

## Usage

```js title="JS"
wp.hooks.addFilter(
  "lzb.constructor.code-settings.info",
  "my.custom.namespace",
  function (render, data) {
    if (data.props.data.code_output_method !== "php") {
      return render;
    }

    return (
      <>
        {render}
        <p className="description">
          Render callbacks for this site live in <code>inc/blocks.php</code>.
        </p>
      </>
    );
  },
);
```

The empty `preview` slot takes the same two arguments:

```js title="JS"
wp.hooks.addFilter(
  "lzb.constructor.code-settings.preview",
  "my.custom.namespace",
  function (render, data) {
    const controls = data.props.data.controls || {};
    const names = Object.keys(controls)
      .map((id) => controls[id].name)
      .filter(Boolean);

    if (!names.length) {
      return render;
    }

    return (
      <p className="description">
        Available tags: {names.map((name) => `{{${name}}}`).join(", ")}
      </p>
    );
  },
);
```

Return `render` untouched for the cases you do not handle. Returning `null` from `output-code` or `output-template` empties the Code box for that output method, and returning a string instead of an element renders that string as text where the editor used to be.

---

# lzb.constructor.control.settings

Source: https://www.lazyblocks.com/docs/js-filters/lzb-constructor-control-settings/

Fills the control-specific slot in the block builder's settings panel, the gap between the Type row and the Default row where a control type puts the settings only it has. Every Pro control that carries its own options registers here, `lzb.constructor.control.units.settings` for the unit list, `lzb.constructor.control.message.settings` for the message text.

## Attributes

| Name     | Type              | Description                                                |
| -------- | ----------------- | ---------------------------------------------------------- |
| `render` | **JSX \| String** | what the type-specific filter returned, `''` when none ran |
| `props`  | **Object**        | `data`, `id`, `updateData`, `controlTypeData`              |

| Name              | Type         | Description                                                                                            |
| ----------------- | ------------ | ------------------------------------------------------------------------------------------------------ |
| `data`            | **Object**   | the selected control's settings: `type`, `name`, `label`, `default` and any of its own                 |
| `id`              | **String**   | key of this control inside the block's `controls` object                                               |
| `updateData`      | **Function** | merges settings into the control, `updateData({ units: "px,em" })`                                     |
| `controlTypeData` | **Object**   | the registered control type: `name`, `icon`, `type`, `label`, `category`, `restrictions`, `attributes` |

## Additional Filters

| Name                                            | Description                                                  |
| ----------------------------------------------- | ------------------------------------------------------------ |
| `lzb.constructor.control.CONTROL_TYPE.settings` | one control type only, and it runs before the generic filter |

The type-specific filter is applied first with `''` as its starting value, then this one runs on whatever came back. So a handler on the generic name sees the type-specific markup and can add to it or drop it.

## Usage

```js title="JS"
wp.hooks.addFilter(
  "lzb.constructor.control.my_json.settings",
  "my.custom.namespace",
  function (render, props) {
    const { TextareaControl, PanelBody } = wp.components;

    return (
      <PanelBody>
        {render}
        <TextareaControl
          label="Schema"
          help="JSON schema the control validates against."
          value={props.data.my_json_schema || ""}
          onChange={(value) => props.updateData({ my_json_schema: value })}
        />
      </PanelBody>
    );
  },
);
```

Settings written with `updateData` are saved on the control record, so the same key is readable from PHP and from the editor filters. Adding or removing whole rows is a different job. [lzb.constructor.control.settings-rows](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-control-settings-rows/) takes the map of row components and lets you insert your own row or delete a built-in one, while this filter only fills the one slot the plugin has reserved for control types.

---

# lzb.constructor.control.settings-rows

Source: https://www.lazyblocks.com/docs/js-filters/lzb-constructor-control-settings-rows/

Filters the rows of the control settings sidebar, the panel that opens in the block builder when a control is selected. Add a row when a control needs a setting the plugin does not ship, or rebuild the object to put your row next to a related one.

## Attributes

| Name              | Type       | Description                                                 |
| ----------------- | ---------- | ----------------------------------------------------------- |
| `rows`            | **Object** | row components keyed by setting name, rendered in key order |
| `props`           | **Object** | `updateData`, `data`, `id`                                  |
| `controlTypeData` | **Object** | registration data of the selected control type              |

`rows` holds 14 keys by default, in this order: `label`, `name`, `type`, `control_specific_rows`, `default`, `help`, `placement`, `group`, `width`, `required`, `hide_if_not_selected`, `translate`, `save_in_meta`, `pro_notice`. Every value is a React component type, not an element, and each one is rendered with `controlTypeData` plus everything in `props`.

`props.data` holds the settings of the selected control, `props.id` its uid, and `props.updateData` writes changes back to it.

`controlTypeData` comes from the control type registry and carries `name`, `icon`, `type`, `label`, `category`, `restrictions` and `attributes`.

Before rendering a row the builder reads `controlTypeData.restrictions[key + '_settings']` and skips the row when that value is false. A key you add has no matching restriction, so your row shows for every control type. Guard on `props.data.type` when it only makes sense for one of them.

## Usage

Key order is render order, so rebuilding the object is how a row lands at a chosen position. Conditional Logic appends its key to the end, and the Rich Text component inserts its notice directly after `name` this way.

```js title="JS"
const { TextControl } = wp.components;

function CharactersLimitRow({ data, updateData }) {
  return (
    <TextControl
      label="Characters limit"
      type="number"
      value={data.my_characters_limit || ""}
      onChange={(value) => updateData({ my_characters_limit: value })}
    />
  );
}

wp.hooks.addFilter(
  "lzb.constructor.control.settings-rows",
  "my.custom.namespace",
  function (rows, props) {
    if (props.data.type !== "text") {
      return rows;
    }

    const result = {};

    Object.keys(rows).forEach((key) => {
      result[key] = rows[key];

      if (key === "default") {
        result.my_characters_limit = CharactersLimitRow;
      }
    });

    return result;
  },
);
```

The filter runs only while a control is selected, and the result goes straight into `Object.keys()`. Returning `null` throws `Cannot convert undefined or null to object` and the settings sidebar stops rendering, so return the incoming `rows` when a handler has nothing to change.

---

# lzb.constructor.controls.item

Source: https://www.lazyblocks.com/docs/js-filters/lzb-constructor-controls-item/

Filters the finished card of one control in the block builder's Controls list, after the icon, the label, the name and the duplicate and remove buttons are already in it. Use it to put extra markup next to a card, for instance a badge marking the controls that write to post meta.

## Attributes

| Name           | Type       | Description                                                                            |
| -------------- | ---------- | -------------------------------------------------------------------------------------- |
| `controlsItem` | **JSX**    | the card element, a `div` carrying the drag handle and buttons                         |
| `props`        | **Object** | `data`, `id`, `controls`, `updateData`, `addControl`, `removeControl`, `printControls` |

| Name            | Type         | Description                                                                                  |
| --------------- | ------------ | -------------------------------------------------------------------------------------------- |
| `data`          | **Object**   | the control's own settings: `type`, `name`, `label`, `required`, `save_in_meta` and the rest |
| `id`            | **String**   | key of this control inside the block's `controls` object                                     |
| `controls`      | **Object**   | every control on the block, keyed by id                                                      |
| `updateData`    | **Function** | merges settings into this control, `updateData({ label: "New label" })`                      |
| `addControl`    | **Function** | adds a control, taking its settings and the id to sort it after                              |
| `removeControl` | **Function** | deletes this control and every control whose `child_of` points at it                         |
| `printControls` | **Function** | renders the nested list, taking `childOf` and `placement`                                    |

## Additional Filters

| Name                                         | Description                                                  |
| -------------------------------------------- | ------------------------------------------------------------ |
| `lzb.constructor.controls.CONTROL_TYPE.item` | one control type only, and it runs before the generic filter |

## Usage

```js title="JS"
wp.hooks.addFilter(
  "lzb.constructor.controls.item",
  "my.custom.namespace",
  function (controlsItem, props) {
    if (props.data.save_in_meta !== "true") {
      return controlsItem;
    }

    const metaName = props.data.save_in_meta_name || props.data.name;

    return (
      <div className="my-control-item-with-meta">
        {controlsItem}
        <span className="my-control-item-meta-badge">meta: {metaName}</span>
      </div>
    );
  },
);
```

The card keeps the `ref` and the `style` that `useSortable` puts on it, so wrapping it the way the example does leaves the drag transform on the inner element while the outer one stays still. When all you want is a class name or a `data-` attribute, filter the props instead with [lzb.constructor.controls.item-attributes](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-controls-item-attributes/), which runs before the element is built and keeps the card as the single node.

---

# lzb.constructor.controls.item-attributes

Source: https://www.lazyblocks.com/docs/js-filters/lzb-constructor-controls-item-attributes/

Filters the DOM props of a control card in the block builder controls list. Use it to add a class or a data attribute to the card so your own stylesheet or script can find that control.

## Attributes

| Name                     | Type       | Description                                                                            |
| ------------------------ | ---------- | -------------------------------------------------------------------------------------- |
| `controlsItemAttributes` | **Object** | props spread onto the card `<div>`                                                     |
| `props`                  | **Object** | `addControl`, `removeControl`, `updateData`, `printControls`, `data`, `id`, `controls` |

The default object has eight keys:

| Name                 | Type         | Description                                                                           |
| -------------------- | ------------ | ------------------------------------------------------------------------------------- |
| `className`          | **String**   | `lzb-block-builder-controls-item` plus the undefined, selected and dragging modifiers |
| `onClick`            | **Function** | selects the control, which is what opens its settings sidebar                         |
| `role`               | **String**   | `none`                                                                                |
| `data-control-type`  | **String**   | control type, for example `text`                                                      |
| `data-control-name`  | **String**   | control name as entered in the builder                                                |
| `data-control-label` | **String**   | control type again, the same value as `data-control-type`                             |
| `ref`                | **Function** | dnd-kit node ref that makes the card sortable                                         |
| `style`              | **Object**   | drag transform and transition                                                         |

`props.data` holds the settings of this control, `props.id` its uid, and `props.controls` every control on the block keyed by uid.

## Additional Filters

| Name                                                    | Description            |
| ------------------------------------------------------- | ---------------------- |
| `lzb.constructor.controls.CONTROL_TYPE.item-attributes` | specific controls only |

The type-specific filter runs first and the generic one receives its result, so a handler on `lzb.constructor.controls.item-attributes` can overwrite what a type-specific handler set.

## Usage

```js title="JS"
wp.hooks.addFilter(
  "lzb.constructor.controls.item-attributes",
  "my.custom.namespace",
  function (attributes, props) {
    if (props.data.save_in_meta !== "true") {
      return attributes;
    }

    return {
      ...attributes,
      className: `${attributes.className} my-meta-control`,
      "data-meta-name": props.data.save_in_meta_name || props.data.name,
    };
  },
);
```

Spread the incoming object instead of building a new one. Dropping `ref` detaches the card from dnd-kit and the control can no longer be dragged into a new position, and dropping `onClick` makes the control unselectable so its settings never open. To change the rendered card rather than its props, use [lzb.constructor.controls.item](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-controls-item/), which filters the finished element.

---

# lzb.constructor.general-settings.slug

Source: https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-slug/

Filters the Slug field of the block builder general settings. Wrap it to put a control of your own beside the slug, swap it for a picker, or return a falsy value to take the field off the screen.

## Attributes

| Name           | Type       | Description                          |
| -------------- | ---------- | ------------------------------------ |
| `element`      | **JSX**    | `PanelBody` holding the slug control |
| `settingsData` | **Object** | `data`, `updateData`                 |

`settingsData.data` is the whole block data, so `data.slug` holds the current value and `data.icon`, `data.category`, `data.keywords` and `data.description` hold the values behind the other four general settings. `settingsData.updateData` shallow merges the object you pass it into that block data.

The five general settings render in a fixed order: slug, icon, category, keywords, description. This filter changes what stands in the slug position, it cannot move the field.

## Usage

Pro adds its namespace selector by wrapping the default element rather than replacing it.

```js title="JS"
const { PanelBody, ToggleControl } = wp.components;

wp.hooks.addFilter(
  "lzb.constructor.general-settings.slug",
  "my.custom.namespace",
  function (element, settingsData) {
    const { data, updateData } = settingsData;

    return (
      <>
        {element}
        <PanelBody>
          <ToggleControl
            label="Hide this block from the inserter"
            checked={data.my_hidden === "true"}
            onChange={(value) =>
              updateData({ my_hidden: value ? "true" : "false" })
            }
          />
        </PanelBody>
      </>
    );
  },
);
```

The builder renders the filtered value as `{settingsSlug || null}`, so returning `false`, `null` or an empty string removes the Slug field and nothing on that screen can edit the block slug any more. Returning a component function instead of an element makes React warn `Functions are not valid as a React child` and render nothing. The other four fields go through [lzb.constructor.general-settings.icon](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-icon/), [lzb.constructor.general-settings.category](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-category/), [lzb.constructor.general-settings.keywords](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-keywords/) and [lzb.constructor.general-settings.description](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-description/).

---

# lzb.constructor.general-settings.icon

Source: https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-icon/

Filters the Icon field of the block builder general settings. Replace the default icon picker when your blocks must use icons from a set of your own instead of arbitrary Dashicons and SVG markup.

## Attributes

| Name           | Type       | Description                         |
| -------------- | ---------- | ----------------------------------- |
| `element`      | **JSX**    | `PanelBody` holding the icon picker |
| `settingsData` | **Object** | `data`, `updateData`                |

`settingsData.data` is the whole block data, so `data.icon` holds the current value and `data.slug`, `data.category`, `data.keywords` and `data.description` hold the values behind the other four general settings. `settingsData.updateData` shallow merges the object you pass it into that block data.

The five general settings render in a fixed order: slug, icon, category, keywords, description. This filter changes what stands in the icon position, it cannot move the field.

## Usage

Ignoring the incoming `element` replaces the field, which is how you narrow the choice to a fixed set.

```js title="JS"
const { PanelBody, SelectControl } = wp.components;

const MY_ICONS = {
  "dashicons-cart": "Cart",
  "dashicons-star-filled": "Star",
  "dashicons-megaphone": "Megaphone",
};

wp.hooks.addFilter(
  "lzb.constructor.general-settings.icon",
  "my.custom.namespace",
  function (element, settingsData) {
    const { data, updateData } = settingsData;

    return (
      <PanelBody>
        <SelectControl
          label="Icon"
          value={data.icon || ""}
          options={[
            { label: "Select icon", value: "" },
            ...Object.keys(MY_ICONS).map((value) => ({
              label: MY_ICONS[value],
              value,
            })),
          ]}
          onChange={(value) => updateData({ icon: value })}
        />
      </PanelBody>
    );
  },
);
```

A replacement has to write to `data.icon` itself, because the element you dropped was the only thing calling `updateData({ icon })`. The builder renders the filtered value as `{settingsIcon || null}`, so returning `false`, `null` or an empty string removes the Icon field and the block keeps whatever icon it already has. The other four fields go through [lzb.constructor.general-settings.slug](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-slug/), [lzb.constructor.general-settings.category](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-category/), [lzb.constructor.general-settings.keywords](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-keywords/) and [lzb.constructor.general-settings.description](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-description/).

---

# lzb.constructor.general-settings.category

Source: https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-category/

Filters the Category field of the block builder general settings. Put a notice above it when your site groups blocks by a convention the plain field cannot express, so the person editing the block reads the rule before picking a value.

## Attributes

| Name           | Type       | Description                              |
| -------------- | ---------- | ---------------------------------------- |
| `element`      | **JSX**    | `PanelBody` holding the category control |
| `settingsData` | **Object** | `data`, `updateData`                     |

`settingsData.data` is the whole block data, so `data.category` holds the current value and `data.slug`, `data.icon`, `data.keywords` and `data.description` hold the values behind the other four general settings. `settingsData.updateData` shallow merges the object you pass it into that block data.

The five general settings render in a fixed order: slug, icon, category, keywords, description. This filter changes what stands in the category position, it cannot move the field.

## Usage

```js title="JS"
const { Notice } = wp.components;

wp.hooks.addFilter(
  "lzb.constructor.general-settings.category",
  "my.custom.namespace",
  function (element, settingsData) {
    const { data } = settingsData;
    const slug = data.slug || "";

    if (slug.indexOf("lazyblock/marketing-") !== 0) {
      return element;
    }

    if (data.category === "design") {
      return element;
    }

    return (
      <>
        <Notice status="warning" isDismissible={false}>
          Marketing blocks belong in the Design category.
        </Notice>
        {element}
      </>
    );
  },
);
```

`data.slug` is falsy until the block has been given a slug, so fall back before calling string methods on it. The builder renders the filtered value as `{settingsCategory || null}`, so returning `false`, `null` or an empty string removes the Category field and the block stays in whatever category it already has. The other four fields go through [lzb.constructor.general-settings.slug](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-slug/), [lzb.constructor.general-settings.icon](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-icon/), [lzb.constructor.general-settings.keywords](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-keywords/) and [lzb.constructor.general-settings.description](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-description/).

---

# lzb.constructor.general-settings.keywords

Source: https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-keywords/

Filters the Keywords field of the block builder general settings. Return a falsy value to hide it, which is what a site does when the keywords of a block are owned by code and editing them by hand would only cause drift.

## Attributes

| Name           | Type       | Description                              |
| -------------- | ---------- | ---------------------------------------- |
| `element`      | **JSX**    | `PanelBody` holding the keywords control |
| `settingsData` | **Object** | `data`, `updateData`                     |

`settingsData.data` is the whole block data, so `data.keywords` holds the current comma-separated value and `data.slug`, `data.icon`, `data.category` and `data.description` hold the values behind the other four general settings. `settingsData.updateData` shallow merges the object you pass it into that block data.

The five general settings render in a fixed order: slug, icon, category, keywords, description. This filter changes what stands in the keywords position, it cannot move the field.

## Usage

The builder renders the filtered value as `{settingsKeywords || null}`, so returning `null` takes the field off the screen.

```js title="JS"
wp.hooks.addFilter(
  "lzb.constructor.general-settings.keywords",
  "my.custom.namespace",
  function (element, settingsData) {
    const slug = settingsData.data.slug || "";

    if (slug.indexOf("lazyblock/generated-") !== 0) {
      return element;
    }

    return null;
  },
);
```

Hiding the field does not clear the stored value. A block saved earlier keeps the keywords it had and nothing in the builder can change them any more, so code that hides this field has to set `keywords` elsewhere, for example through [lzb/register_block_type_data](https://www.lazyblocks.com/docs/php-filters/lzb-register_block_type_data/). Do not call `updateData` from inside the filter, because it runs during render and dispatching there makes React warn about updating one component while another renders. The other four fields go through [lzb.constructor.general-settings.slug](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-slug/), [lzb.constructor.general-settings.icon](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-icon/), [lzb.constructor.general-settings.category](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-category/) and [lzb.constructor.general-settings.description](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-description/).

---

# lzb.constructor.general-settings.description

Source: https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-description/

Filters the Description field of the block builder general settings. Append help text under it when your team has a house rule for the description, such as a length the block directory or a search index expects.

## Attributes

| Name           | Type       | Description                                  |
| -------------- | ---------- | -------------------------------------------- |
| `element`      | **JSX**    | `PanelBody` holding the description textarea |
| `settingsData` | **Object** | `data`, `updateData`                         |

`settingsData.data` is the whole block data, so `data.description` holds the current value and `data.slug`, `data.icon`, `data.category` and `data.keywords` hold the values behind the other four general settings. `settingsData.updateData` shallow merges the object you pass it into that block data.

The five general settings render in a fixed order: slug, icon, category, keywords, description. Description is the last of them, so anything appended here sits at the bottom of the general settings panel.

## Usage

```js title="JS"
const { PanelBody } = wp.components;

wp.hooks.addFilter(
  "lzb.constructor.general-settings.description",
  "my.custom.namespace",
  function (element, settingsData) {
    const length = (settingsData.data.description || "").length;

    return (
      <>
        {element}
        <PanelBody>
          <p style={{ margin: 0, color: length > 155 ? "#cc1818" : "#757575" }}>
            {length} of 155 characters used.
          </p>
        </PanelBody>
      </>
    );
  },
);
```

The description reaches the front end only through block registration, so a rule enforced here is advisory. Nothing stops a block from being saved with a longer description. The builder renders the filtered value as `{settingsDescription || null}`, so returning `false`, `null` or an empty string removes the Description field along with anything you appended to it. The other four fields go through [lzb.constructor.general-settings.slug](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-slug/), [lzb.constructor.general-settings.icon](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-icon/), [lzb.constructor.general-settings.category](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-category/) and [lzb.constructor.general-settings.keywords](https://www.lazyblocks.com/docs/js-filters/lzb-constructor-general-settings-keywords/).

---

# lzb.constructor.wizard.templates

Source: https://www.lazyblocks.com/docs/js-filters/lzb-constructor-wizard-templates/

Filters the presets the block builder offers when creating a new block. Add your own starting point, or replace the collection entirely.

The filter runs on every render of the wizard rather than once at module load, so a script that registers its presets after the builder script still has them picked up.

## Attributes

| Name        | Type       | Description                             |
| ----------- | ---------- | --------------------------------------- |
| `templates` | **Object** | presets, keyed by preset slug            |

Each preset takes these keys:

| Name          | Type            | Description                                                  |
| ------------- | --------------- | ------------------------------------------------------------ |
| `title`       | **String**      | name shown in the wizard                                      |
| `icon`        | **JSX \| null** | icon shown beside the name in the wizard                      |
| `blockIcon`   | **String**      | SVG markup used as the icon of the block being created        |
| `category`    | **String**      | block category, `text` by default                             |
| `keywords`    | **String**      | comma-separated keywords for the created block                |
| `description` | **String**      | block description                                             |
| `controls`    | **Array**       | controls to create, each with `type`, `name`, `label`, `placement` and any other control settings |
| `template`    | **String**      | starting block code                                           |
| `style`       | **String**      | starting block styles, where `__BLOCK_CLASSNAME__` stands for the generated class |

## Usage

```js title="JS"
wp.hooks.addFilter(
  "lzb.constructor.wizard.templates",
  "my.custom.namespace",
  function (templates) {
    return {
      ...templates,
      "pricing-card": {
        title: "Pricing Card",
        icon: null,
        blockIcon: "",
        category: "design",
        keywords: "pricing,card,plan",
        description: "A single pricing plan with a title and a price.",
        controls: [
          {
            type: "text",
            name: "plan-title",
            label: "Plan Title",
            default: "Starter",
            placement: "inspector",
          },
          {
            type: "text",
            name: "plan-price",
            label: "Price",
            default: "$9",
            placement: "inspector",
          },
        ],
        template: `<div useBlockProps>
  <h3>{{plan-title}}</h3>
  <p>{{plan-price}}</p>
</div>`,
        style: `__BLOCK_CLASSNAME__ {
  padding: 20px;
  border: 1px solid #e0e0e0;
}`,
      },
    };
  }
);
```

The wizard preselects whichever preset comes first in the object, so nothing may assume a particular preset is present.

---

# lzb.editor.BlockEdit.attributesForRender

Source: https://www.lazyblocks.com/docs/js-filters/lzb-editor-blockedit-attributesforrender/

Filters the attributes sent to the server when the editor renders a block preview.

By default the list holds the values of the registered controls plus a few reserved attributes. Use this filter to add an attribute your own code stores on the block but that is not registered as a control, so the preview can render with it.

## Attributes

| Name             | Type       | Description                                             |
| ---------------- | ---------- | ------------------------------------------------------- |
| `attsForRender`  | **Object** | attributes about to be sent for rendering                |
| `data`           | **Object** | `attributes`, `meta`, `lazyBlockData`, `props`           |

`data.attributes` holds every attribute on the block, including the ones left out of `attsForRender`.

## Usage

```js title="JS"
wp.hooks.addFilter(
  "lzb.editor.BlockEdit.attributesForRender",
  "my.custom.namespace",
  function (attsForRender, data) {
    if (data.lazyBlockData.slug !== "lazyblock/my-block") {
      return attsForRender;
    }

    return {
      ...attsForRender,
      myCustomAttribute: data.attributes.myCustomAttribute,
    };
  }
);
```

This affects the editor preview only. On the front end the block renders through PHP, where [lzb/block_render/attributes](https://www.lazyblocks.com/docs/php-filters/lzb-block_render-attributes/) does the same job.

---

# lzb.editor.control.render

Source: https://www.lazyblocks.com/docs/js-filters/lzb-editor-control-render/

Filters the element one control renders in the block editor, after the control type has produced it. Use it to wrap a control in markup of your own, or use the type-specific name to give a control type its editor UI in the first place.

## Attributes

| Name          | Type       | Description                                                                                            |
| ------------- | ---------- | ------------------------------------------------------------------------------------------------------ |
| `render`      | **JSX**    | the element the control type returned                                                                  |
| `controlData` | **Object** | `data`, `placement`, `childIndex`, `uniqueId`, `getValue`, `onChange`, `getControls`, `renderControls` |
| `props`       | **Object** | props of the block being edited, with the block record under `lazyBlockData`                           |

| Name             | Type                  | Description                                                                                                    |
| ---------------- | --------------------- | -------------------------------------------------------------------------------------------------------------- |
| `data`           | **Object**            | the control's settings, with `label` and `help` already wrapped in elements                                    |
| `placement`      | **String**            | `content` or `inspector`                                                                                       |
| `childIndex`     | **Number \| Boolean** | row index inside a repeater, `false` outside one                                                               |
| `uniqueId`       | **String**            | key of this control inside `props.lazyBlockData.controls`                                                      |
| `getValue`       | **Function**          | reads the current value, through [lzb.editor.control.getValue](https://www.lazyblocks.com/docs/js-filters/lzb-editor-control-getvalue/)  |
| `onChange`       | **Function**          | writes a new value, through [lzb.editor.control.updateValue](https://www.lazyblocks.com/docs/js-filters/lzb-editor-control-updatevalue/) |
| `getControls`    | **Function**          | returns the block's controls, or the children of one when given a parent name                                  |
| `renderControls` | **Function**          | renders a whole placement and group, used by repeater controls for their rows                                  |

## Additional Filters

| Name                                     | Description            |
| ---------------------------------------- | ---------------------- |
| `lzb.editor.control.CONTROL_TYPE.render` | specific controls only |

The type-specific filter runs first, and this one only runs when that filter returned something. A control type with no registered renderer never reaches it.

## Usage

The type-specific name starts from an empty string, which makes it the place to register the UI of a control type of your own:

```js title="JS"
wp.hooks.addFilter(
  "lzb.editor.control.my_rating.render",
  "my.custom.namespace",
  function (render, controlData) {
    const { RangeControl } = wp.components;

    return (
      <RangeControl
        label={controlData.data.label}
        help={controlData.data.help}
        min={0}
        max={5}
        value={Number(controlData.getValue()) || 0}
        onChange={(value) => controlData.onChange(String(value))}
      />
    );
  },
);
```

The generic name receives whatever that produced, for every control on every block:

```js title="JS"
wp.hooks.addFilter(
  "lzb.editor.control.render",
  "my.custom.namespace",
  function (render, controlData) {
    if (controlData.data.type !== "textarea") {
      return render;
    }

    const length = String(controlData.getValue() || "").length;

    return (
      <>
        {render}
        <p className="description">{length} characters</p>
      </>
    );
  },
);
```

Both filters run on every render of the block, so a handler that reads the value with `getValue` should stay cheap. Returning a falsy value from either filter drops the control from the editor entirely, and a falsy return from the type-specific one also stops the generic filter from running for that control. To reorder or wrap the whole group of controls at once rather than each one, use [lzb.editor.controls.render](https://www.lazyblocks.com/docs/js-filters/lzb-editor-controls-render/), which filters the finished list for one placement and group.

---

# lzb.editor.controls.render

Source: https://www.lazyblocks.com/docs/js-filters/lzb-editor-controls-render/

Filters the whole list of rendered controls for one placement, group and nesting level. Reach for it to group controls into sections of your own, or to rebuild the list from the raw control data instead of patching elements you cannot inspect.

Note the plural. [lzb.editor.control.render](https://www.lazyblocks.com/docs/js-filters/lzb-editor-control-render/) filters a single control, takes three arguments, and runs only after the type-specific `lzb.editor.control.CONTROL_TYPE.render` filter returned something truthy. This one filters the finished list, takes two arguments, and always runs, including when nothing rendered.

## Attributes

| Name     | Type             | Description                                                                         |
| -------- | ---------------- | ----------------------------------------------------------------------------------- |
| `result` | **Array \| JSX** | rendered controls, or one `PanelBody` wrapping them when the placement is inspector |
| `data`   | **Object**       | `placement`, `group`, `childOf`, `childIndex`, `getControls`, `renderControl`       |

| Name            | Type                  | Description                                                                     |
| --------------- | --------------------- | ------------------------------------------------------------------------------- |
| `placement`     | **String**            | `inspector` or `content`                                                        |
| `group`         | **String**            | `default`, `content`, `list`, `styles` or `advanced`                            |
| `childOf`       | **String**            | uid of the parent control, `''` at the top level                                |
| `childIndex`    | **Number \| Boolean** | repeater row index, `false` outside a repeater                                  |
| `getControls`   | **Function**          | `getControls(childOf)` returns the raw controls of that level, keyed by uid     |
| `renderControl` | **Function**          | `renderControl(control, placement, uid, childIndex, group)` renders one control |

A control stored with the group `settings` is normalised to `default` before the filter runs, so match on `default` and never on `settings`. Content placement and repeater rows are both rendered without a group argument, so they always arrive as `group: 'default'`.

When `placement` is `inspector` and at least one control rendered, `result` is a single `PanelBody` element rather than the array. Check for that before treating the value as a list.

## Usage

The Pro Panel control throws the default result away and rebuilds the list, which is what `getControls` and `renderControl` are there for.

```js title="JS"
const { PanelBody } = wp.components;

wp.hooks.addFilter(
  "lzb.editor.controls.render",
  "my.custom.namespace",
  function (result, data) {
    const {
      placement,
      group,
      childOf,
      childIndex,
      getControls,
      renderControl,
    } = data;

    if (placement !== "inspector") {
      return result;
    }

    const controls = getControls(childOf);
    const main = [];
    const advanced = [];

    Object.keys(controls).forEach((uid) => {
      const rendered = renderControl(
        controls[uid],
        placement,
        uid,
        childIndex,
        group,
      );

      if (!rendered) {
        return;
      }

      if (controls[uid].name.indexOf("advanced_") === 0) {
        advanced.push(rendered);
      } else {
        main.push(rendered);
      }
    });

    if (!advanced.length) {
      return result;
    }

    return [
      <PanelBody key="main">{main}</PanelBody>,
      <PanelBody key="advanced" title="Advanced" initialOpen={false}>
        {advanced}
      </PanelBody>,
    ];
  },
);
```

`renderControl` returns `false` for a control whose placement or group does not match the arguments you passed, so drop the falsy results rather than pushing them into the list. Whatever you return is rendered as it stands, which means an array without a `key` on each element makes React warn on every editor render.

---

# lzb.editor.control.validate

Source: https://www.lazyblocks.com/docs/js-filters/lzb-editor-control-validate/

Decides whether a required control counts as filled in, and what the error under it says. The built-in check is `val !== '' && typeof val !== 'undefined'`, which passes for an empty object, an empty array and the string `"0"`, so anything stricter than "not blank" belongs here.

The filter runs only for control types whose `required_settings` restriction is on and only for controls that have Required turned on in the block builder. Everything else skips it.

## Attributes

| Name      | Type       | Description                                                                                                  |
| --------- | ---------- | ------------------------------------------------------------------------------------------------------------ |
| `data`    | **Object** | `valid` (**Boolean**) and `message` (**String**), the result so far                                          |
| `val`     | **Mixed**  | the value, already read through [lzb.editor.control.getValue](https://www.lazyblocks.com/docs/js-filters/lzb-editor-control-getvalue/) |
| `control` | **Object** | control settings: `type`, `name`, `required`, `label` and the rest                                           |

## Additional Filters

| Name                                       | Description            |
| ------------------------------------------ | ---------------------- |
| `lzb.editor.control.CONTROL_TYPE.validate` | specific controls only |

The type-specific filter is applied inside the generic one's argument list, so it runs first and the generic filter receives its `{ valid, message }` as the incoming `data`.

## Usage

```js title="JS"
wp.hooks.addFilter(
  "lzb.editor.control.my_json.validate",
  "my.custom.namespace",
  function (data, val) {
    if (!val || !val.title) {
      return { valid: false, message: "Add a title before saving." };
    }

    return data;
  },
);
```

The result is destructured as `{ valid, message }`, so returning `null` or `undefined` throws a `TypeError` while the control is being rendered. A string or a boolean does not throw but leaves `valid` undefined, which reads as invalid and shows the default message, `This control is required.` A falsy `valid` puts `message` in a red notice under the control and calls `lockPostSaving`, so the post cannot be saved until the check passes.

---

# lzb.editor.control.getValue

Source: https://www.lazyblocks.com/docs/js-filters/lzb-editor-control-getvalue/

Turns what is stored for a control into what its editor component expects. This is the first of three filters a value passes through in the editor: `getValue` on the way in, [lzb.editor.control.validate](https://www.lazyblocks.com/docs/js-filters/lzb-editor-control-validate/) before the post can be saved, and [lzb.editor.control.updateValue](https://www.lazyblocks.com/docs/js-filters/lzb-editor-control-updatevalue/) on the way back out.

The plugin has already picked the raw value by the time the filter runs. It comes from `attributes[control.name]`, or from `meta[control.save_in_meta_name || control.name]` when the control has `save_in_meta` set to `true`, or from the parent's array at `childIndex` when the control lives inside a repeater.

## Attributes

| Name         | Type                  | Description                                                                                   |
| ------------ | --------------------- | --------------------------------------------------------------------------------------------- |
| `val`        | **Mixed**             | the stored value, before any coercion                                                         |
| `control`    | **Object**            | control settings: `type`, `name`, `default`, `label`, `child_of`, `save_in_meta` and the rest |
| `childIndex` | **Number \| Boolean** | row index inside a repeater, otherwise `false` or `undefined`                                 |

## Additional Filters

| Name                                       | Description            |
| ------------------------------------------ | ---------------------- |
| `lzb.editor.control.CONTROL_TYPE.getValue` | specific controls only |

The type-specific filter runs first and the generic one runs on its result.

## Usage

```js title="JS"
wp.hooks.addFilter(
  "lzb.editor.control.getValue",
  "my.custom.namespace",
  function (val, control) {
    if (control.type !== "my_json") {
      return val;
    }

    try {
      return JSON.parse(val || "{}");
    } catch (e) {
      return {};
    }
  },
);
```

After both filters, an `undefined` result is replaced with an empty string, so a handler cannot use `undefined` to mean "leave the stored value alone". Whatever shape you return here has to survive the trip back through [lzb.editor.control.updateValue](https://www.lazyblocks.com/docs/js-filters/lzb-editor-control-updatevalue/), which is where the value is turned back into something the block attribute or the post meta can hold.

---

# lzb.editor.control.updateValue

Source: https://www.lazyblocks.com/docs/js-filters/lzb-editor-control-updatevalue/

Changes a control value on its way out, after the control component reports a change and before `setAttributes` or `setMeta` stores it. This is the mirror of [lzb.editor.control.getValue](https://www.lazyblocks.com/docs/js-filters/lzb-editor-control-getvalue/), so a pair of handlers can keep one shape in the editor and another in the database.

## Attributes

| Name         | Type                  | Description                                                                                   |
| ------------ | --------------------- | --------------------------------------------------------------------------------------------- |
| `val`        | **Mixed**             | the value the control just produced                                                           |
| `control`    | **Object**            | control settings: `type`, `name`, `default`, `label`, `child_of`, `save_in_meta` and the rest |
| `childIndex` | **Number \| Boolean** | row index inside a repeater, `false` outside one                                              |

## Additional Filters

| Name                                          | Description            |
| --------------------------------------------- | ---------------------- |
| `lzb.editor.control.CONTROL_TYPE.updateValue` | specific controls only |

The type-specific filter runs first and the generic one runs on its result.

For a control inside a repeater, both arguments have already been swapped before the filters run. `control` is the parent repeater, `val` is its whole array of rows with the new value written into row `childIndex`, and `control.type` is therefore the repeater's type rather than the child's. A type-specific handler registered on the child's type never fires for it.

## Usage

```js title="JS"
wp.hooks.addFilter(
  "lzb.editor.control.updateValue",
  "my.custom.namespace",
  function (val, control) {
    if (control.type !== "my_json") {
      return val;
    }

    return typeof val === "string" ? val : JSON.stringify(val);
  },
);
```

The return value is stored as it is, with no coercion on this side. A normal control goes through `setAttributes({ [name]: val })`, a meta control through `setMeta` under `save_in_meta_name` or the control name. That is also the value PHP reads on the front end, so a shape only the editor understands needs handling there too. Values are read back through [lzb.editor.control.getValue](https://www.lazyblocks.com/docs/js-filters/lzb-editor-control-getvalue/), and checked before save by [lzb.editor.control.validate](https://www.lazyblocks.com/docs/js-filters/lzb-editor-control-validate/).

---

# lzb.components.PreviewServerCallback.allowFetch

Source: https://www.lazyblocks.com/docs/js-filters/lzb-components-previewservercallback-allowfetch/

Runs before the editor preview posts to `lazy-blocks/v1/block-render`. Return a falsy value to skip that request, which is how the Pro blocks preloading feature fills the first preview from markup the editor page already carries instead of asking the server again.

## Attributes

| Name    | Type        | Description                                               |
| ------- | ----------- | --------------------------------------------------------- |
| `allow` | **Boolean** | whether the request runs, `true` by default               |
| `data`  | **Object**  | the preview component's props, state and internal handles |

`data` has thirteen keys:

| Name                  | Type                         | Description                                                                                                                 |
| --------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `props`               | **Object**                   | current props of the preview component, including `block`, `attributes` and `context`                                       |
| `prevProps`           | **Object \| undefined**      | the same props from the previous render, `undefined` on the first one                                                       |
| `response`            | **String \| Object \| null** | current preview content: markup on success, `{ error: true, response }` after a failed request, `null` before the first one |
| `setResponse`         | **Function**                 | writes markup into the preview and fires the `onChange` action                                                              |
| `isLoading`           | **Boolean**                  | whether a request is in flight                                                                                              |
| `setIsLoading`        | **Function**                 | state setter behind the loading spinner                                                                                     |
| `allowRender`         | **Boolean**                  | `false` once the block answered `lazy_block_no_render_callback`                                                             |
| `setAllowRender`      | **Function**                 | state setter for `allowRender`                                                                                              |
| `isMountedRef`        | **Object**                   | ref whose `current` turns `false` when the block unmounts                                                                   |
| `currentFetchRequest` | **Object**                   | ref holding the newest `apiFetch` promise, used to drop stale responses                                                     |
| `postId`              | **Number**                   | id of the post being edited, `0` outside the post editor                                                                    |
| `fetchData`           | **Function**                 | sends the request now                                                                                                       |
| `debouncedFetchData`  | **Function**                 | sends the request 500ms from now, cancelling any pending call                                                               |

`prevProps` is how a handler tells the first render from the rest. `setResponse` is not the raw state setter, it is the same wrapper the fetch success path uses, so calling it both paints the preview and fires [lzb.components.PreviewServerCallback.onChange](https://www.lazyblocks.com/docs/js-actions/lzb-components-previewservercallback-onchange/).

The filter sits in an effect with no dependency list, so it runs on every render of the preview, including the renders where nothing would have been fetched anyway. Keep the handler cheap.

## Usage

```js title="JS"
wp.hooks.addFilter(
  "lzb.components.PreviewServerCallback.allowFetch",
  "my.custom.namespace",
  function (allow, { props, prevProps, setResponse }) {
    // Hydrate on the first render only, and let every later one fetch.
    if (prevProps !== undefined) {
      return allow;
    }

    const blockId = props?.attributes?.blockId;
    const cached = blockId && window.myPreloadedBlocks?.[blockId];

    if (typeof cached === "string" && cached.length) {
      setResponse(cached);
      return false;
    }

    return allow;
  },
);
```

Returning falsy without calling `setResponse` leaves the preview blank until an attribute or context change re-runs the effect, so a handler that blocks the request owns the job of putting markup in. The Pro version registers this filter for you as part of [editor preloading](https://www.lazyblocks.com/docs/performance/), and the markup it caches is chosen with [lzb_pro/preload_blocks](https://www.lazyblocks.com/docs/php-filters/lzb_pro-preload_blocks/).

---

# lzb.editor.PreviewServerCallback.replaceNode

Source: https://www.lazyblocks.com/docs/js-filters/lzb-editor-previewservercallback-replacenode/

Filter called for every node while the editor preview parses the rendered block markup. Return a React element to put in place of the node, or the default `null` to leave the node to the standard handling.

Use it to give a custom component of your own the same treatment `` gets: written as a tag in the block code, turned into a real editor component in the preview.

## Attributes

| Name         | Type            | Description                                              |
| ------------ | --------------- | -------------------------------------------------------- |
| `customNode` | **JSX \| null** | replacement node, `null` by default                       |
| `domNode`    | **Object**      | parsed node, with `name`, `attribs` and `children`        |
| `data`       | **Object**      | `props`, `parserOptions`, `domToReact`, `prepareAttributes` |

`prepareAttributes` converts the raw markup attributes the way the rest of the parser does: `"true"` and `"false"` become booleans, `class` becomes `className`.

## Usage

```js title="JS"
wp.hooks.addFilter(
  "lzb.editor.PreviewServerCallback.replaceNode",
  "my.custom.namespace",
  function (customNode, domNode, data) {
    if (domNode.name !== "myComponent") {
      return customNode;
    }

    const atts = data.prepareAttributes(domNode.attribs);

    return <div className={atts.className}>{atts.label}</div>;
  }
);
```

Returning anything other than `null` stops the default handling for that node, so return the incoming `customNode` untouched for every node you do not care about.

---

# lzb.registerBlockType.args

Source: https://www.lazyblocks.com/docs/js-filters/lzb-registerblocktype-args/

Adds registration options that WordPress supports but the block builder has no screen for, such as block variations, transforms, or extra keywords for the inserter. The filter runs once per block as the editor loads, and what it returns is passed straight to `registerBlockType()` with no further processing.

## Attributes

| Name        | Type       | Description                                                                                                   |
| ----------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
| `blockArgs` | **Object** | `apiVersion`, `title`, `description`, `icon`, `category`, `keywords`, `supports`, `lazyblock`, `edit`, `save` |
| `blockSlug` | **String** | the block name, always prefixed `lazyblock/`                                                                  |
| `blockData` | **Object** | the block record the plugin loaded from the database                                                          |

`blockArgs.lazyblock` is `true` on every block the plugin registers, which is how other code recognises one. `blockArgs.edit` renders the plugin's own editor component with `blockData` attached to it, so replacing `edit` or `save` replaces the block's editing and saving behaviour whole.

`blockData` carries `id`, `title`, `slug`, `icon`, `keywords`, `description`, `category`, `category_label`, `supports`, `controls`, `code`, `style`, `script`, `styles`, `condition` and `edit_url`. `blockData.controls` is the map of controls, keyed by id, which is what a handler reads to decide the attributes a variation should set.

## Usage

```js title="JS"
wp.hooks.addFilter(
  "lzb.registerBlockType.args",
  "my.custom.namespace",
  function (blockArgs, blockSlug) {
    if (blockSlug !== "lazyblock/pricing-card") {
      return blockArgs;
    }

    return {
      ...blockArgs,
      keywords: [...(blockArgs.keywords || []), "plan", "tier"],
      variations: [
        {
          name: "featured",
          title: "Pricing Card, featured",
          attributes: {
            "plan-title": "Pro",
            "plan-price": "$29",
          },
        },
      ],
    };
  },
);
```

Attributes are not in `blockArgs`. The plugin registers them on the server, built from the block's controls, so adding an `attributes` key here is not how a field is added to a block. Add a control in the block builder instead. Because the returned object is the whole of the registration, build it by spreading `blockArgs` rather than from scratch, or the block loses its `edit`, its `save` and its `supports`.

---

# lzb-pro.componentRichText.textualControlTypes

Source: https://www.lazyblocks.com/docs/js-filters/lzb-pro-componentrichtext-textualcontroltypes/

Filters which control types the `` component may edit in place. A control type of your own that stores a plain string is not on the default list, so the component refuses to make it editable until its type is added here.

## Attributes

| Name    | Type      | Description                               |
| ------- | --------- | ----------------------------------------- |
| `types` | **Array** | control types the component may take over |

This filter takes one argument. There is no context object, so a handler cannot tell which block or which control the check is being made for.

The default list is `text`, `textarea`, `rich_text`, `classic_editor`, `code_editor`, `url` and `email`. It reaches the editor through `window.lzbProRichText.textualControlTypes`, which the plugin prints after running the PHP filter [lzb_pro/rich_text/textual_control_types](https://www.lazyblocks.com/docs/php-filters/lzb_pro-rich_text-textual_control_types/). Image, Gallery and Repeater are left off on purpose. All three register as `string` because they store JSON, and letting the component overwrite that with plain text would destroy the value.

## Usage

```js title="JS"
wp.hooks.addFilter(
  "lzb-pro.componentRichText.textualControlTypes",
  "my.custom.namespace",
  function (types) {
    return [...types, "my_plain_text_control"];
  },
);
```

The check is `(Array.isArray(types) ? types : []).indexOf(type) > -1`, so a return value that is not an array is swallowed and makes every type non textual. Every `` then renders as a static fallback with a console warning, and the block builder turns its Rich Text notice from info into an error. This filter moves the editor half only. The front end render reads the PHP list, so change [lzb_pro/rich_text/textual_control_types](https://www.lazyblocks.com/docs/php-filters/lzb_pro-rich_text-textual_control_types/) when both halves must agree, and use this one only for an editor-side adjustment on top of it. [Rich Text component](https://www.lazyblocks.com/docs/blocks-code/rich-text/) covers what the component does with a value once it is editable.

---

# lzb.components.PreviewServerCallback.onBeforeChange

Source: https://www.lazyblocks.com/docs/js-actions/lzb-components-previewservercallback-onbeforechange/

Fires in the editor the moment a block preview response arrives, before the old markup is replaced. It is where a script tears down whatever it attached to that markup, a slider instance or an event listener on a node that is about to disappear.

The action runs on both paths, after a successful render and after a failed request, and only for the response of the newest request. A response from a request that a later one has already replaced is dropped without firing it.

## Attributes

| Name    | Type       | Description                    |
| ------- | ---------- | ------------------------------ |
| `props` | **Object** | props of the preview component |

| Name             | Type               | Description                                                                     |
| ---------------- | ------------------ | ------------------------------------------------------------------------------- |
| `block`          | **String**         | block name, for example `lazyblock/slider`                                      |
| `attributes`     | **Object \| null** | attributes sent for rendering, `null` when the caller passed none               |
| `urlQueryArgs`   | **Object**         | extra fields merged into the REST request body, `{}` by default                 |
| `onBeforeChange` | **Function**       | the component's own callback, called immediately before this action             |
| `onChange`       | **Function**       | the component's own callback for the render that follows                        |
| `withBlockProps` | **Boolean**        | whether the rendered markup is wrapped with the block props, `false` by default |
| `context`        | **Object**         | block context sent to the server                                                |
| `clientId`       | **String**         | client id of the block, passed in by the caller and forwarded untouched         |

## Usage

```js title="JS"
wp.hooks.addAction(
  "lzb.components.PreviewServerCallback.onBeforeChange",
  "my.custom.namespace",
  function (props) {
    if (props.block !== "lazyblock/slider") {
      return;
    }

    const node = document.querySelector(
      `[data-block="${props.clientId}"] .my-slider`,
    );

    if (node && node.mySlider) {
      node.mySlider.destroy();
      delete node.mySlider;
    }
  },
);
```

## Deprecated alias

`lazyblocks.components.PreviewServerCallback.onBeforeChange` fires immediately after this one, with the same single argument. It is kept so old integrations keep working. Do not add handlers to it in new code.

The markup is still on the page when this action runs, so a handler can read it. Anything that has to run against the new markup belongs in [lzb.components.PreviewServerCallback.onChange](https://www.lazyblocks.com/docs/js-actions/lzb-components-previewservercallback-onchange/) instead, which fires after React has committed it.

---

# lzb.components.PreviewServerCallback.onChange

Source: https://www.lazyblocks.com/docs/js-actions/lzb-components-previewservercallback-onchange/

Fires in the editor after a block preview has been rendered with a new response. It is where a script starts up again on the fresh markup, the counterpart to the teardown in [lzb.components.PreviewServerCallback.onBeforeChange](https://www.lazyblocks.com/docs/js-actions/lzb-components-previewservercallback-onbeforechange/).

It runs from an effect that skips the first render and then fires for every response, the first one included. A failed request counts as a response, and so does a block with no render callback, which renders as nothing, so the markup a handler is looking for is not guaranteed to be on the page.

The same effect lists the component's props among its dependencies, and the block that owns the preview hands it a fresh props object on every one of its renders. The action therefore fires again on renders where no new response arrived. A handler has to be safe to run repeatedly.

## Attributes

| Name    | Type       | Description                    |
| ------- | ---------- | ------------------------------ |
| `props` | **Object** | props of the preview component |

| Name             | Type               | Description                                                                     |
| ---------------- | ------------------ | ------------------------------------------------------------------------------- |
| `block`          | **String**         | block name, for example `lazyblock/slider`                                      |
| `attributes`     | **Object \| null** | attributes sent for rendering, `null` when the caller passed none               |
| `urlQueryArgs`   | **Object**         | extra fields merged into the REST request body, `{}` by default                 |
| `onBeforeChange` | **Function**       | the component's own callback for the teardown that came before                  |
| `onChange`       | **Function**       | the component's own callback, called immediately before this action             |
| `withBlockProps` | **Boolean**        | whether the rendered markup is wrapped with the block props, `false` by default |
| `context`        | **Object**         | block context sent to the server                                                |
| `clientId`       | **String**         | client id of the block, passed in by the caller and forwarded untouched         |

## Usage

```js title="JS"
wp.hooks.addAction(
  "lzb.components.PreviewServerCallback.onChange",
  "my.custom.namespace",
  function (props) {
    if (props.block !== "lazyblock/slider") {
      return;
    }

    const node = document.querySelector(
      `[data-block="${props.clientId}"] .my-slider`,
    );

    if (node && !node.mySlider) {
      node.mySlider = new window.MySlider(node);
    }
  },
);
```

## Deprecated alias

`lazyblocks.components.PreviewServerCallback.onChange` fires immediately after this one, with the same single argument. It is kept so old integrations keep working. Do not add handlers to it in new code.

Guard on `props.block` and check the node before touching it, as the example does. The action fires for every previewed block on the page, not only the one being edited, and the `!node.mySlider` test is what keeps a repeat run from building a second instance on the same node.

---

# lzb.constructor.post-change

Source: https://www.lazyblocks.com/docs/js-actions/lzb-constructor-post-change/

Action fired while the block builder watches the save state of the block post. Hook it to push data of your own to the server at the moment the block itself is saved.

## Attributes

| Name   | Type       | Description                                                               |
| ------ | ---------- | ------------------------------------------------------------------------- |
| `data` | **Object** | `isSavingPost`, `isAutosavingPost`, `shouldUpdate`, `blockData`, `postId` |

| Name               | Type        | Description                                                            |
| ------------------ | ----------- | ---------------------------------------------------------------------- |
| `isSavingPost`     | **Boolean** | the editor is saving right now                                         |
| `isAutosavingPost` | **Boolean** | the save in flight is an autosave                                      |
| `shouldUpdate`     | **Boolean** | a save that was not an autosave has just finished                      |
| `blockData`        | **Object**  | current block settings, with `slug`, `icon`, `category` and `controls` |
| `postId`           | **Number**  | ID of the `lazyblocks` post being edited                               |

The action sits in a `useEffect` keyed on `isSavingPost`, `isAutosavingPost`, `postId` and `blockData`, so it runs on every change of any of them and not only on save. Typing one character into a control label fires it. `shouldUpdate` is the only argument that marks a finished save, and it is true exactly once per save that was not an autosave.

It fires immediately after the builder issues its own `/lazy-blocks/v1/update-block-data/` request, not after that request resolves. A handler that reads the block back over REST can still see the previous values.

## Usage

```js title="JS"
let myDataChanged = false;

wp.hooks.addAction(
  "lzb.constructor.post-change",
  "my.custom.namespace",
  function ({ shouldUpdate, postId }) {
    if (!shouldUpdate || !myDataChanged) {
      return;
    }

    wp.apiFetch({
      path: "/my-plugin/v1/block-saved/",
      method: "POST",
      data: { post_id: postId },
    }).then(() => {
      myDataChanged = false;
    });
  },
);
```

Without the `shouldUpdate` gate the handler runs on every keystroke in the builder, which is how a request per character ends up in the network tab. Pro uses exactly this shape to write its block collections once the block post is saved.

---

# Create Custom Control

Source: https://www.lazyblocks.com/docs/examples/create-custom-control/

While Lazy Blocks plugin comes with a comprehensive set of built-in controls like text, gallery, and repeater, you might need to create custom controls for specific project requirements. This guide will help you implement your own custom controls.

## Getting Started with Custom Controls

We've created a template plugin to help you quickly start developing custom controls. This template includes a basic text control with custom styling and attributes, serving as an excellent foundation for your custom control development:

Download Custom Control Template

Download and review all files in the template repository, including comments and documentation, to understand the implementation details.

## Customizing the Template

The template contains placeholders that you'll need to replace with your specific implementation details. Here's a reference table of available placeholders:

| Placeholder            | Description                                                     | Example           |
| ---------------------- | --------------------------------------------------------------- | ----------------- |
| `NAMESPACE`            | Single-word identifier used in class names to prevent conflicts | `my`              |
| `CONTROL-NAME`         | Hyphen-separated identifier for your control                    | `icon-picker`     |
| `CONTROL_NAME`         | Underscore-separated identifier for your control                | `icon_picker`     |
| `CONTROL_LABEL`        | Human-readable name for your control                            | `Icon Picker`     |
| `TEXTDOMAIN`           | Translation identifier (recommended: use your plugin slug)      | `lzb-icon-picker` |
| `PLUGIN_URL`           | URL to your plugin's repository                                 |                   |
| `PLUGIN_TAGS`          | SEO-friendly tags for wordpress.org                             |                   |
| `SHORT_DESCRIPTION`    | Concise control description (max 2 lines)                       |                   |
| `EXTENDED_DESCRIPTION` | Detailed control description                                    |                   |
| `AUTHOR_NAME`          | Your name or wordpress.org username                             |                   |
| `AUTHOR_URL`           | Your website URL                                                |                   |

## Implementation Steps

1. Download the template repository
2. Replace all placeholders with your custom values
3. Copy the modified plugin to your WordPress plugins directory (`wp-content/plugins`)
4. Activate the plugin through WordPress admin panel

Ensure all placeholders are replaced before activating the plugin to avoid conflicts with other WordPress plugins.

The resulting plugin will contain all necessary components for your custom control implementation, ready for further customization according to your specific needs.

---

# Include Lazy Blocks within theme or plugin

Source: https://www.lazyblocks.com/docs/examples/include-lazy-blocks-within-theme-or-plugin/

Lazy Blocks provides a powerful solution for creating custom blocks and comes as a separate plugin. Although designed primarily for individual use, it may also be used as a framework by both plugin and theme authors to power their free and premium products.

We encourage authors to include Lazy Blocks and have only a few simple rules to follow, which we hope you respect. This guide outlines the do's and don'ts when including Lazy Blocks within you plugin or theme.

## Product Types

When talking about a WordPress product, we can consider it as either a plugin, theme, premium plugin or premium theme.

Our rules differ only if your product is considered as free or premium, and not if it is a plugin or theme.

## Rules

Please see the following table of rules that govern the inclusion of our plugins.

|                                              | Lazy Blocks | Lazy Blocks Pro         |
| -------------------------------------------- | ----------- | ----------------------- |
| Include in a free plugin                     | ✅          | ❌                      |
| Include in a free theme                      | ✅          | ❌                      |
| Include in a premium plugin                  | ✅          | ✅ **with Agency plan** |
| Include in a premium theme                   | ✅          | ✅ **with Agency plan** |
| Include in a "Lazy Blocks" extension plugins | ❌          | ❌                      |
| Share license key information                | ❌          | ❌                      |
| Use as a selling point                       | ✅          | ❌                      |

If you would like to **include Lazy Blocks Pro in your premium theme or plugin**, required to purchase the [**Agency plan**](https://www.lazyblocks.com/pro/#pricing).

## Notes about marketing

Although we love idea of you empowering your customers with custom blocks, we don't love the idea of you advertising this to boost sales.

When including Lazy Blocks Pro within your premium theme or premium plugin, please do not advertise this in your marketing material. For example, stay away from messages like "This theme also includes Lazy Blocks Pro, normally $$$, for free!"

## Notes about "Lazy Blocks" extension plugins

We do not allow Lazy Blocks or Lazy Blocks Pro to be included in any type of "Lazy Blocks" extension or plugin. For example, a plugin named "Lazy Blocks Pro Kit" that extends the plugin with extra features may not include Lazy Blocks Pro. In this case, the "Lazy Blocks Pro Kit" plugin should require Lazy Blocks Pro to be installed.

## How to include plugin files

To include Lazy Blocks within your theme or plugin, please download the appropriate Lazy Blocks plugin files and copy them into your theme or plugin. We recommend using the folder `inc/lzb` within your product files.

Next, use the following code as a starter to customize and include the Lazy Blocks plugin into your theme or plugin.

```php title="PHP"
if ( ! function_exists( 'lazyblocks' ) ) {
  // Define path and URL to the LZB plugin.
  $my_lzb_path = get_stylesheet_directory() . '/inc/lzb/';
  $my_lzb_url  = get_stylesheet_directory_uri() . '/inc/lzb/';

  // Include the LZB plugin.
  require_once $my_lzb_path . 'lazy-blocks.php';

  lazyblocks()->include_within( $my_lzb_url );
}
```

Or if you use Lazy Blocks v3.3.0 and older, use the following code:

```php title="PHP for old Lazy Blocks"
// Define path and URL to the LZB plugin.
define( 'MY_LZB_PATH', get_stylesheet_directory() . '/inc/lzb/' );
define( 'MY_LZB_URL', get_stylesheet_directory_uri() . '/inc/lzb/' );

// Include the LZB plugin.
require_once MY_LZB_PATH . 'lazy-blocks.php';

// Customize the url setting to fix incorrect asset URLs.
add_filter( 'lzb/plugin_url', 'my_lzb_url' );
function my_lzb_url( $url ) {
  return MY_LZB_URL;
}
```

---

# Display Custom Fields (Meta)

Source: https://www.lazyblocks.com/docs/examples/display-custom-fields-meta/

This guide explains how to display and manipulate custom meta fields created with Lazy Blocks in your WordPress theme or plugin.

Custom meta fields are primarily intended for developers. If you're new to custom fields, please review the [WordPress Custom Fields documentation](https://wordpress.org/documentation/article/assign-custom-fields/) first.

## Basic Meta Value Display

To display a simple meta value:

```php title="PHP"
<p>
    <?php echo get_lzb_meta('control_meta_name'); ?>
</p>
```

## Working with Meta Values

### Conditional Display

```php title="PHP"
if (get_lzb_meta('control_meta_name')) {
    ?>
    <p>The value is True</p>
    <?php
} else {
    ?>
    <p>The value is False</p>
    <?php
}
```

### Handling Array Data (e.g., Repeater Fields)

```php title="PHP"
$repeater = get_lzb_meta('control_meta_name');

foreach ($repeater as $inner_control) {
    ?>
    <p><?php echo esc_html($inner_control); ?></p>
    <?php
}
```

### Working with Image Fields

Display image with URL and alt text:

```php title="PHP"
$image = get_lzb_meta('control_meta_name');

if (isset($image['url'])) : ?>
    <img src="<?php echo esc_url($image['url']); ?>"
         alt="<?php echo esc_attr($image['alt']); ?>">
<?php endif; ?>
```

Display image using WordPress attachment functions:

```php title="PHP"
$image = get_lzb_meta('control_meta_name');

if (isset($image['id'])) {
    echo wp_get_attachment_image($image['id'], 'large');
}
```

## Manual Meta Data Handling

When Lazy Blocks plugin is not active but you need to access previously saved meta data, you'll need to manually decode the stored values.

Here's how to manually retrieve and decode meta values:

```php title="PHP"
// Get raw meta value from database
$meta_val = get_post_meta(get_the_ID(), 'meta_name', true);

if ($meta_val) {
    // Decode the stored meta value
    $meta_val = json_decode(rawurldecode($meta_val), true);

    // Use the decoded value
    var_dump($meta_val);
}
```

The `get_lzb_meta()` function automatically handles decoding of stored meta values. Only use the manual decoding method when the plugin is not available.

---

# Custom Post Type and Save in Meta control

Source: https://www.lazyblocks.com/docs/examples/custom-post-type-and-save-in-meta-control/

When implementing blocks with the `Save in Meta` option in Custom Post Types, it's crucial to ensure your post type properly supports custom fields. This guide explains how to set up Custom Post Types correctly for use with Lazy Blocks meta fields.

## Registering Custom Post Type

Here's how to register a Custom Post Type with proper support for both the block editor and meta fields:

```php title="PHP"
function create_my_custom_post_type() {
    register_post_type(
        'my_custom_post',
        array(
            'labels' => array(
                'name'          => __('My Custom Post'),
                'singular_name' => __('My Custom Post')
            ),
            'public' => true,

            // Enable Gutenberg editor support
            'show_in_rest' => true,

            'supports' => array(
                'title',
                'editor',
                'thumbnail',
                // Enable custom meta fields support
                'custom-fields',
            ),
        )
    );
}
add_action('init', 'create_my_custom_post_type');
```

## Important Considerations

- Always include `show_in_rest => true` to ensure compatibility with the block editor
- Add `custom-fields` to the supports array to enable meta field functionality
- Register your Custom Post Type early in the WordPress initialization process using the `init` hook

Without proper custom-fields support, blocks with the "Save in Meta" option will not function correctly in your Custom Post Type.

This setup ensures your Custom Post Type works seamlessly with Lazy Blocks' meta field features while maintaining full compatibility with the WordPress block editor.

---

# Shortcode + Gutenberg

Source: https://www.lazyblocks.com/docs/examples/shortcode-gutenberg/

If you already have shortcodes and want to make it compatible with Gutenberg, you can easily make it possible.

## Lazy Block Edit

First, you need to add block Name, Slug, Icon, Category, Description, and Keywords. Then you can start adding Controls:

- Textarea control named Content will be used as shortcode content `[my_shortcode]Content[/my_shortcode]`
- Attribute control you can add as many as you want. You can also name it as you need, `Attribute 1` and `Attribute 2` for example only

## PHP

```php title="PHP"
echo do_shortcode(
  '[my_shortcode attribute_1="' . esc_attr( $attributes['attribute_1'] ) . '" attribute_2="' . esc_attr( $attributes['attribute_2'] ) . '"]' .
    $attributes['content'] .
  '[/my_shortcode]'
);
```

## Handlebars

```hbs title="Handlebars"
{{{do_shortcode "my_shortcode" this}}}
```

It will output shortcode automatically:

```php title="PHP"
[my_shortcode attribute_1="attr 1 value" attribute_2="" className="" align="" anchor=""]Shortcode Content[/my_shortcode]
```

---

# Alert Block

Source: https://www.lazyblocks.com/docs/examples/alert-block/

This guide demonstrates how to create a custom Alert block using the Lazy Blocks plugin. The block supports multiple alert types, dismissible functionality, and custom content.

## Creating the Alert Block

### Step 1: Basic Block Configuration

Configure the essential block settings in the Lazy Blocks builder:

1. Set block name, slug, and icon
2. Choose appropriate category
3. Add description and keywords for better discoverability
4. Configure Style Variations for different alert types (Info, Success, Warning, Error)

### Step 2: Adding Controls

Configure the following controls in the block builder:

1. **Alert Title** (Text control)
   - Allows users to input an optional alert title

2. **Alert Content** (Rich Text control)
   - Allows users to input the main alert message with rich text formatting

3. **Dismissible** (Toggle control)
   - Enables/disables close button functionality

### Step 3: Block Code

Add the template code in the Block Code section. This code will automatically work for both editor and frontend rendering. Choose either PHP or Handlebars template:

```php title="PHP Template"
<div useBlockProps<?php echo $attributes['dismissible'] ? ' class="alert-dismissible"' : ''; ?>>
  <div class="alert-content">
    <?php if ( ! empty( $attributes['alert-title'] ) ) : ?>
      <h4 class="alert-title"><?php echo esc_html( $attributes['alert-title'] ); ?></h4>
    <?php endif; ?>
    <div class="alert-message"><?php echo $attributes['alert-content']; ?></div>
  </div>
  <?php if ( $attributes['dismissible'] ) : ?>
    <button class="alert-dismiss" onclick="this.parentNode.style.display='none';">
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24">
        <path fill="none" d="M0 0h24v24H0z"/>
        <path d="M12 10.586l4.95-4.95 1.414 1.414-4.95 4.95 4.95 4.95-1.414 1.414-4.95-4.95-4.95 4.95-1.414-1.414 4.95-4.95-4.95-4.95L7.05 5.636z"/>
      </svg>
    </button>
  <?php endif; ?>
</div>
```

```hbs title="Handlebars Template"
<div useBlockProps{{#if dismissible}} class="alert-dismissible"{{/if}}>
  <div class="alert-content">
    {{#if alert-title}}<h4 class="alert-title">{{alert-title}}</h4>{{/if}}
    <div class="alert-message">{{{alert-content}}}</div>
  </div>
  {{#if dismissible}}
    <button class="alert-dismiss" onclick="this.parentNode.style.display='none';">
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24">
        <path fill="none" d="M0 0h24v24H0z"/>
        <path d="M12 10.586l4.95-4.95 1.414 1.414-4.95 4.95 4.95 4.95-1.414 1.414-4.95-4.95-4.95 4.95-1.414-1.414 4.95-4.95-4.95-4.95L7.05 5.636z"/>
      </svg>
    </button>
  {{/if}}
</div>
```

### Step 4: Block Styles

Add the CSS styles in the Block Styles section of the Lazy Blocks builder:

```css
.wp-block-lazyblock-alert-block {
  display: flex;
  padding: 16px;
  border-radius: 4px;
  position: relative;
  background-color: #f3f3f3;
  border-left: 4px solid #b3b3b3;
  color: #4a4a4a;
}
.wp-block-lazyblock-alert-block .alert-content {
  flex-grow: 1;
}
.wp-block-lazyblock-alert-block .alert-title {
  margin-top: 0;
  margin-bottom: 8px;
  font-size: 18px;
}
.wp-block-lazyblock-alert-block .alert-message p:last-child {
  margin-bottom: 0;
}
.wp-block-lazyblock-alert-block .alert-dismiss {
  background: none;
  border: none;
  cursor: pointer;
  padding: 0;
  position: absolute;
  top: 16px;
  right: 16px;
  opacity: 0.7;
}
.wp-block-lazyblock-alert-block .alert-dismiss:hover {
  opacity: 1;
}

/* Alert types */
.wp-block-lazyblock-alert-block.is-style-info {
  background-color: #e8f4fd;
  border-left: 4px solid #3498db;
  color: #0c5d95;
}

.wp-block-lazyblock-alert-block.is-style-success {
  background-color: #e8f8f5;
  border-left: 4px solid #2ecc71;
  color: #1b7943;
}

.wp-block-lazyblock-alert-block.is-style-warning {
  background-color: #fef9e7;
  border-left: 4px solid #f1c40f;
  color: #9a7d0a;
}

.wp-block-lazyblock-alert-block.is-style-error {
  background-color: #fdedec;
  border-left: 4px solid #e74c3c;
  color: #922b21;
}
```

## Style Variations

The Alert block comes with predefined Style Variations that can be applied in the WordPress editor. These are configured in the Basic Block Configuration step:

- **Info** - Blue styling for informational messages
- **Success** - Green styling for success messages
- **Warning** - Yellow styling for warning messages
- **Error** - Red styling for error messages

## Theme Integration

Add this code to your theme's functions.php or plugin file:

```php
add_action( 'lzb/init', function() {
  lazyblocks()->add_block( array(
    'title' => 'Alert Block',
    'icon' => '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path d="M11 15h2v2h-2zm0-8h2v6h-2zm.99-5C6.47 2 2 6.48 2 12s4.47 10 9.99 10C17.52 22 22 17.52 22 12S17.52 2 11.99 2zM12 20c-4.42 0-8-3.58-8-8s3.58-8 8-8 8 3.58 8 8-3.58 8-8 8z"></path></svg>',
    'keywords' => array(
      'alert',
      'notice',
      'message',
      'notification',
    ),
    'slug' => 'lazyblock/alert-block',
    'description' => 'Attention-grabbing alert box, perfect for important announcements and notifications.',
    'category' => 'design',
    'category_label' => 'design',
    'supports' => array(
      'customClassName' => true,
      'anchor' => false,
      'html' => false,
      'multiple' => true,
      'inserter' => true,
      'reusable' => true,
      'lock' => true,
      'align' => array(
        'wide',
        'full',
      ),
    ),
    'controls' => array(
      'control_d4aad34f6e' => array(
        'type' => 'text',
        'name' => 'alert-title',
        'default' => 'Important Notice',
        'label' => 'Alert Title',
        'help' => 'Title of the alert (optional)',
        'placement' => 'inspector',
        'translate' => 'true',
      ),
      'control_3ebbb94850' => array(
        'type' => 'rich_text',
        'name' => 'alert-content',
        'default' => 'This is an important message that you should pay attention to.',
        'label' => 'Alert Content',
        'placement' => 'inspector',
        'translate' => 'true',
      ),
      'control_daeade4589' => array(
        'type' => 'toggle',
        'name' => 'dismissible',
        'default' => 'false',
        'label' => 'Dismissible',
        'placement' => 'inspector',
        'checked' => 'false',
        'alongside_text' => 'Make alert dismissible',
      ),
    ),
    'code' => array(
      'output_method' => 'html',
      'editor_html' => '',
      'editor_callback' => '',
      'frontend_html' => '
        /* INSERT BLOCK CODE HERE */
      ',
      'frontend_callback' => '',
      'show_preview' => 'always',
      'single_output' => true,
    ),
    'style' => array(
      'block' => '
        /* INSERT BLOCK STYLES HERE */
      ',
      'editor' => '',
    ),
    'script' => array(
      'view' => '',
    ),
    'styles' => array(
      array(
          'name' => 'info',
          'label' => 'Info',
      ),
      array(
          'name' => 'success',
          'label' => 'Success',
      ),
      array(
          'name' => 'warning',
          'label' => 'Warning',
      ),
      array(
          'name' => 'error',
          'label' => 'Error',
      ),
    ),
    'condition' => array(),
  ) );
} );
```

This implementation provides a fully functional Alert block that integrates seamlessly with the WordPress block editor with custom styling and multiple alert variations.

---

# Download Failed: Unauthorized

Source: https://www.lazyblocks.com/docs/troubleshooting/download-failed-unauthorized/

There are 2 main reasons why you see this error when trying to update the Pro plugin.

## Expired License

If your license key is expired, you will need to renew it before you can install the update. The status of your license key will be shown in the **Licenses** section of [your order page](https://www.lazyblocks.com/docs/getting-started/install-pro-version/#activate).

## License Key is not activated on the URL

This is happening because the license key is not activated on the URL the plugin is installed on. This can sometimes happen if you install the plugin and activate the license key on a temporary URL and then update the site to the final URL.

To resolve the problem, [log into your Lemon Squeezy](https://www.lazyblocks.com/docs/getting-started/install-pro-version/#activate), find the **Licenses** section, then click on the license. From that page you will be able to add or remove URLs for the license.

Once the proper URL is registered on the license key, you will be able to install the update.

If your receipt came from Paddle or nkdev.info, renew the license and manage its sites in the nkdev.info account instead. See [Licenses bought through Paddle](https://www.lazyblocks.com/docs/getting-started/legacy-licenses/#manage-sites).

---

# An error occurred while updating Lazy Blocks Pro: Could not create directory

Source: https://www.lazyblocks.com/docs/troubleshooting/an-error-occurred-while-updating-lazy-blocks-pro-could-not-create-directory/

If you know that your Lazy Blocks Pro license is active, and when you try to update Lazy Blocks Pro using the standard WordPress plugin update method but you’re met with an error that states:

`An error occurred while updating Lazy Blocks Pro: Could not create directory. lazy-blocks-pro/assets`

There is a fix available! For some background on the issue: Lazy Blocks’s update process uses signed URLs (to make the update more secure) which involves generation of a long string that’s used as the filename during the update process.

There is a limitation of the Windows operating system that prevents a file path from extending beyond a certain number of characters (250 or so) and Lazy Blocks’s signed update URLs can exceed this limit. This is what causes the “could not create directory” error message to appear.

It is possible to work around this issue, but it involves installing a [Must Use Plugin](https://developer.wordpress.org/advanced-administration/plugins/mu-plugins/). Must Use Plugins are different than Plugins in that they’re loaded first and they also require a manual installation.

This process needs to happen only once, but once it does your Lazy Blocks Pro updates should operate as expected.

You will need to create a new file within your `/wp-content/mu-plugins` folder. If this folder doesn’t exist **you must create it**.

You can name the new file `lazy-blocks-pro-windows-compat.php` and save the following contents in that file:

```php
<?php
/**
 * Plugin Name: Lazy Blocks Pro Windows Server Compatibility
 * Plugin URI: https://www.lazyblocks.com/docs/troubleshooting/an-error-occurred-while-updating-lazy-blocks-pro-could-not-create-directory/
 * Description: Resolves an issue on Windows servers that prevents Lazy Blocks Pro from automatically updating.
 */

/**
 * @link https://gist.github.com/spivurno/d7a93ab4920c4fa88bad0e5177b45ba1
 * Easy Digital Downloads provides packages URLs that look something like this:
 *
 * http://mysite.com/edd-sl/package_download/MTQ4NjA1NTA0NjphMDA5MTkzZjQ0NGRiNmVmMzczY2JhNTFiZWIxMWZiYzo0NzM3MzphM2Q5ZDA3NDQwMjZjZDFmOWVhYTBiNzBjMjVlZjI0YjpodHRwQC8vbXVzaWNmZXN0aXZhbC5zY2hvb2wubno
 *
 * This generates a temporary filename for the update process that look something like this:
 *
 * MTQ4NjA1NTA0NjphMDA5MTkzZjQ0NGRiNmVmMzczY2JhNTFiZWIxMWZiYzo0NzM3MzphM2Q5ZDA3NDQwMjZjZDFmOWVhYTBiNzBjMjVlZjI0YjpodHRwQC8vbXVzaWNmZXN0aXZhbC5zY2hvb2wubno.tmp
 *
 * Some Windows servers choke on filenames of this size. As a result, the update wil fail and WordPress
 * will give you a "Could not copy file." error.
 *
 * This solution (which is a little weird) will check if the package URL that is about to be downloaded
 * by WordPress is an EDD package URL. If so, it will truncate the temporary filename to 50 characters.
 */

// initiate a fix for Windows servers where the GP package file name is too long and prevents installs/updates from processing
add_filter( 'upgrader_pre_download', 'mu_lzb_pro_maybe_shorten_edd_filename', 10, 4 );

/**
 * Check if the URL that is about to be downloaded is an EDD package URL. If so, hook our function to shorten
 * the filename.
 *
 * @param mixed  $return
 * @param string $package The URL of the file to be downloaded.
 *
 * @return mixed
 */
function mu_lzb_pro_maybe_shorten_edd_filename( $return, $package ) {
    if( strpos( $package, '/edd-sl/package_download/' ) !== false ) {
        add_filter( 'wp_unique_filename', 'mu_lzb_pro_shorten_edd_filename', 10, 2 );
    }

    return $return;
}

/**
 * Truncate the temporary filename to 50 characters. This resolves issues with some Windows servers which
 * cannot handle very long filenames.
 *
 * @param string $filename
 * @param string $ext
 *
 * @return string
 */
function mu_lzb_pro_shorten_edd_filename( $filename, $ext ) {
    $filename = substr( $filename, 0, 50 ) . $ext;
    remove_filter( 'wp_unique_filename', 'mu_lzb_pro_shorten_edd_filename', 10 );

    return $filename;
}
```

Once that file is saved, the Must Use Plugin will be active, and it will essentially truncate the long signed URL to be something that Windows servers can manage.

**Please note:** this truncation will happen for Lazy Blocks Pro and any other plugins you’re using that are updated using Easy Digital Downloads Software Licensing solution. This is a popular platform for many WordPress products and it should not interfere in any way, but it needs to be noted.

---

# Receive a 403 error when trying to activate the License

Source: https://www.lazyblocks.com/docs/troubleshooting/receive-a-403-error-when-trying-to-activate-the-license/

If you receive a 403 error when you try to activate your license that means that your server is blocking the connection with our server.

In this case, you have to contact your hosting company and ask them to allow the connection with `api.lazyblocks.com`

---

# Receive a 504 and 429 error Too Many Requests

Source: https://www.lazyblocks.com/docs/troubleshooting/receive-a-504-and-429-error-too-many-requests/

If you receive a 504 or 429 error while working with lazy blocks in the page editor that means that your server is limiting too many AJAX requests.

Block previews are loaded over AJAX, and that is usually the cause. Twenty lazy blocks on a page means twenty requests while the editor loads, and a server with a rate limit answers some of them with a 429 or drops them with a 504.

Pro renders those previews once while the edit screen loads and hands the markup to the editor, so the editor makes no request per block at all. [Performance](https://www.lazyblocks.com/docs/performance/) explains how that works and how to switch it off again if a preview goes stale.

---

# Receive an Error Type E_ERROR eval()’d code causes error: Uncaught TypeError

Source: https://www.lazyblocks.com/docs/troubleshooting/receive-an-error-type-e-error-eval/

If you receive an error "Type E_ERROR in line ... of the file ... eval()’d code causes error: Uncaught TypeError...", that means that the error received from your block code.

If you use the block PHP render string, your code is executed using `eval()` function, and the error comes from your custom block code. Since it is rendered using eval it is hard to debug what exactly is failed.

Try to change your block code to the functional callback or template render to better understand what happens.

- [PHP Callback](https://www.lazyblocks.com/docs/blocks-code/php-callback/)
- [Theme Template](https://www.lazyblocks.com/docs/blocks-code/theme-template/)