---
title: "Collections & Namespaces"
description: "Register custom blocks under your own namespace instead of lazyblock/, group them in the WordPress inserter, and understand what renaming a namespace does to saved content."
url: "https://www.lazyblocks.com/docs/managing-blocks/collections/"
source: "managing-blocks/collections.mdx"
---
# Collections & Namespaces [Pro]

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.

## Documentation Index
> Fetch the complete documentation index at: https://www.lazyblocks.com/llms.txt
> Fetch every page in a single file at: https://www.lazyblocks.com/llms-full.txt