> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vulpy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Storefront blocks and the block registry

> Add or customize Payload blocks in the Vulpy storefront by registering them with the block registry and mapping fields to React components.

The Vulpy storefront renders landing pages, product editorial, and category editorial using Payload blocks. Each block is a Payload field configuration paired with a React component registered in the storefront block registry. This page shows how to add new blocks and how selection pages work.

<Tip>
  **Ask Fox to scaffold the block.** Fox works in the same checkout, creates the files, and wires the registry; you review the diff and commit.

  Try prompts like:

  * "Scaffold a new `testimonial` block."
  * "Register my new block in the storefront registry."
  * "Add a colour picker field to the hero block."
</Tip>

## Where blocks live

* **Block configs**: Payload collection fields under `pages`, `productContent`, and `categoryContent`. See the [Payload blocks field docs](https://payloadcms.com/docs/fields/blocks).
* **Renderers**: React components inside the Next.js storefront app. A block registry maps each `blockType` to its component so Payload content resolves at runtime.

## Add a new block

<Steps>
  <Step title="Define the block in Payload">
    Add a blocks field to the relevant collection (`pages`, `productContent`, or `categoryContent`). Give the block a `slug` and the fields editors need. For example, a hero block might have `heading`, `body`, and `backgroundImage` fields.
  </Step>

  <Step title="Build the React renderer">
    Create a React component that accepts the block fields as props and renders the layout you want. Keep it in the storefront app so it can use your design system and shared components.
  </Step>

  <Step title="Register the component">
    Add an entry to the storefront block registry that maps the block `slug` (used as `blockType`) to your React component. The registry is the single source of truth for which blocks the storefront can render.
  </Step>

  <Step title="Expose the block per collection (optional)">
    If the block should only appear in certain collections, configure the `blocks` field array so the block is listed only where it is relevant. This keeps the editor UI focused.
  </Step>
</Steps>

## Selection pages

`categoryContent` supports pseudo categories called selection pages. Create a `categoryContent` entry with:

* `kind: "selection"`
* A custom `route` value
* A `filterQuery` that defines which products to include

The storefront middleware rewrites the public URL to `/selection/[handle]` so shoppers see a curated product grid without a real Medusa category.

<Note>
  Read-only fields for Medusa identity (`title`, `handle`, `medusaCategoryId`) stay read-only in Payload. Only editorial fields, such as blocks, `h1`, and `seo`, are writable.
</Note>

<Warning>
  Renaming a block `slug` breaks existing Payload documents that reference the old slug. Add a new block instead and migrate content in the Payload admin.
</Warning>

<CardGroup cols={2}>
  <Card title="Payload schema" icon="database" href="/customize/payload-schema">
    Reference the collections and globals that own blocks and editorial content.
  </Card>

  <Card title="Content management" icon="pen" href="/shop/content">
    Learn how editorial content flows from Payload into the storefront.
  </Card>
</CardGroup>