Contact Form Basic

An accessible contact form with inline validation and confirmed submission feedback from your own endpoint.

v0.1.0Page blockContact familyContact form

Installation

npx payload-components add contact-form-basic

What it installs

Copies 4 source files into your project:

  • src/blocks/ContactFormBasic/config.ts
  • src/blocks/ContactFormBasic/Component.tsx
  • src/blocks/ContactFormBasic/form.ts
  • src/blocks/shared/safeUrls.tsshared

…and makes 4 edits to wire the block into your project:

Registers the blocksrc/collections/Pages/index.ts
Maps the renderersrc/blocks/RenderBlocks.tsx
Regenerates typessrc/payload-types.ts
Regenerates the admin import mapsrc/app/(payload)/admin/importMap.js
safeUrls.ts is shared source for this component family. Components that install the same path reuse that local copy, and re-running an install never overwrites a copy you have changed.

Re-running the CLI install detects existing source and wiring, then records install state in .payload-components/state.json.

Content model

All editor fields belong to this block. The shared URL validator restricts the action to a same-origin path.

Prop

Type

The fixed visitor fields are name, email, organization, and message. Name, email, and message are required. Name and organization accept up to 200 characters, email up to 254, and message up to 10,000. Labels are editable; required indicators and submission feedback can be translated in the installed source.

Usage

Add the block to a page. In the Payload admin, open (or create) a Page and add the ContactFormBasic block to its layout.
Fill the content. Complete the fields from the content model above — the component ships sample content you can start from.
Publish. Save and publish the page; the block renders through RenderBlocks on the frontend, fully typed — no extra wiring.

Provide the submit endpoint in your consumer project before publishing. The block sends a POST with multipart/form-data containing the four visitor fields. Your handler should read request.formData(), validate these values on the server, and return a successful HTTP response with JSON { "success": true } only after it accepts the message. Do not redirect: redirects, HTML responses, HTTP errors, and missing acknowledgements display a retry message and preserve the visitor's input. The request times out after 15 seconds; a timeout means delivery could not be confirmed, so your endpoint should handle retries appropriately.

The form focuses the first invalid field, connects each validation message to its input, announces submission results, and disables controls while sending. With JavaScript disabled it falls back to a native form POST; your endpoint then controls the response page. A missing or unsafe action disables submission.

This block installs no API route, email service, database collection, spam protection, or CRM integration. The endpoint owner is responsible for server-side validation, rate limiting, and delivery. For a contact section combining a form and multiple contact channels, see Contact Routing Form.

Requirements

Target
payload-website-starter, payload-blocks-app
Payload
v3
Next.js
15 / 16
shadcn UI
none

Your project must already expose components.json, src/payload.config.ts — the surfaces patched by payload-components add. The CLI verifies this against the support matrix before touching anything.

In this family

contact-routing-form
Contact Routing FormA contact section with validated channels and a fixed accessible form that posts to a same-origin endpoint.
contact-channels
Contact ChannelsA form-free contact section: heading, supporting copy, and a grid of validated email, phone, and URL channels.
contact-form-basiccurrent
Contact Form BasicAn accessible contact form with inline validation and confirmed submission feedback from your own endpoint.