From Zero to Landing Page: A Hands-On Payload CMS Blocks Tutorial (Beginner's Guide)

High-level overview

Hands-on beginner tutorial showing how to build a simple landing page with Payload CMS using Blocks and the Form Builder plugin. It covers:

• Project setup and inspecting the admin/API.
• Creating a Pages collection with a blocks-based layout.
• Authoring block types: Hero, Content, Newsletter Form.
• Wiring front-end components to render blocks.
• Submitting forms to Payload’s form submissions API.
• Basic TypeScript typing, code organization, and UI/state handling for forms.

---

Key steps / concepts demonstrated

Project bootstrap

• Create a new project: npx create-payload-app (blank template, SQLite).
• Install dependencies and run dev server: npm install, npm run dev.
• Use the Payload admin UI to create an admin user and inspect collections / API.

Backend: Collections & Blocks

• Create a Pages collection with required title and slug.
• Add a layout field of type blocks to Pages — stores an ordered array of block objects.
• Define block types (examples shown in the tutorial):
  • Hero block: heading, subheading (Rich Text), image (media), CTA button (label + URL).
  • Content block: heading + Rich Text body.
  • Newsletter form block: heading + relationship to a Form (from the Form Builder plugin).
• Blocks act like “Legos” — editors compose pages by adding multiple block instances in any order.

Form Builder plugin

• Install and configure the Payload Form Builder plugin. It creates Forms and Form Submissions collections.
• Create a form in the admin (example: “newsletter form one”) with fields such as: first name, last name, email, submit label, confirmation message.
• Attach that form to the newsletter form block via a relationship field.

---

Front-end: fetching and rendering

• Server-side page fetch: query Payload for a page by slug using the Payload client; the response includes the layout array.
• Render blocks by mapping over page.layout and using a renderBlocks(block) function.
• Use a switch on block.type (or block.blockType) to render the appropriate React component for each block.
• Create separate components for each block (e.g., HeroBlock, ContentBlock, NewsletterBlock) and organize them in a components/blocks folder.
• Use Payload’s RichText renderer for rich text fields.
• Use Next.js <Image> or equivalent after checking the media object exists (defensive checks before rendering).

---

Newsletter form: rendering and submission

• The Newsletter block dynamically renders inputs by iterating over form.fields provided by the form relationship, preserving the order defined in the admin — keeps the front end flexible.

• Client-side submission flow:

  • Gather form values into an array of { field, value } pairs.

  • POST JSON to Payload’s form submission endpoint with the form id and submissionData mapped as field/value pairs. Example payload shape: json { "form": "FORM_ID", "submissionData": [ { "field": "firstName", "value": "Jane" }, { "field": "lastName", "value": "Doe" }, { "field": "email", "value": "jane@example.com" } ] }

  • Use async / try-catch and set Content-Type: application/json.

  • Manage local form state: loading, error, success.
  • On success: show the confirmation message (rich text), reset the form, hide the submit button while showing confirmation, then clear success state after a timeout.
  • Submitted results appear in the Form Submissions collection in the admin.

---

TypeScript & code organization

• Extract block types from the Pages layout type to define component props (e.g., heroProps, contentProps, newsletterProps).
• Destructure block objects to get fields and guard against undefined media.
• Separate components for readability and reusability; keep blocks in a dedicated folder.

---

Debugging and practical tips

• When adding new fields/blocks repeatedly, the schema may need a rebuild or the dev server restarted.
• Keep styling minimal for tutorial focus; enhance UI later.
• Render defensive checks for media objects and optional fields to avoid runtime errors.
• Use the admin UI to preview API structure and confirm data shapes before wiring the front end.

---

What you’ll get by following the tutorial

• A working minimal landing page composed of Payload blocks (Hero, Content, Newsletter).
• A dynamic form built in the admin that renders automatically on the front end and submits to Payload’s submissions collection.
• Source code (author provides it) and a repeatable pattern for adding more blocks and forms.

---

Related resources / mentions

• Payload CMS documentation (blocks, collections, RichText).
• Payload Form Builder plugin docs.
• Presenter’s separate video on plugins (linked in the video).

---

Main speakers / sources

• Video presenter / channel author (walks through the tutorial and code).
• Payload CMS (documentation and Form Builder plugin used as authoritative sources).