Skip to main content
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.
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.”

​
Where blocks live

  • Block configs: Payload collection fields under pages, productContent, and categoryContent. See the Payload blocks field docs.
  • 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

1

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.
2

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.
3

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.
4

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.

​
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.
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.
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.

Payload schema

Reference the collections and globals that own blocks and editorial content.

Content management

Learn how editorial content flows from Payload into the storefront.