@useblok/forms

First-party form blocks for Blok. Drop a form onto a page, wire a webhook or a handler, done.

Install

npm install @useblok/forms @useblok/core

Quickstart

import type { Config } from "@useblok/core";
import { defineFormBlock } from "@useblok/forms";

const config: Config = {
  components: {
    // ...your other blocks
    Form: defineFormBlock({
      onSubmit: async ({ values, meta }) => {
        await fetch("/api/submit", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ values, meta }),
        });
      },
    }),
  },
};

Authors can now drop a Form block into any page from the block library. Field schema is edited inline in the right panel — labels, input types, placeholders, required flags, select options, and help text.

What's shipped

| Input type | Rendered as | | ------------ | ---------------------- | | text | <input type="text"> | | email | <input type="email"> | | tel | <input type="tel"> | | url | <input type="url"> | | number | <input type="number">| | textarea | <textarea> | | select | <select> with options| | checkbox | <input type="checkbox">|

Submission flow:

1. Client-side validation for required fields runs first.
2. If defineFormBlock({ onSubmit }) was supplied, the handler is called with { values, meta }.
3. Else if the form's action URL is set in the inspector, values + meta is POSTed as JSON.
4. On success the block swaps to the successMessage. On error, a red error row appears above the submit button.

meta includes blockId, the per-form formId, the current path, and the configured action URL — enough to route submissions per-page.

API

defineFormBlock(options?)

Returns a ComponentConfig ready to drop into config.components.

| Option | Type | Notes | | ------------ | ------------------------------------------- | --------------------------------------------- | | label | string | Block library label. Default "Form". | | folder | string | Block library folder. Default "Content". | | accent | string | Accent color. Default #6b6cff. | | onSubmit | (submission) => void \| Promise<void> | Host-level handler. When set, skips fetch. | | defaults | Partial<FormBlockProps> | Seed values for new form instances. |

Types

• FormFieldDef — { name, label, type, placeholder?, required?, options?, help? }
• FormSubmission — { values, meta } payload passed to onSubmit
• FormSubmitHandler — the onSubmit callback signature

Notes

• Styling is inline on the renderer so the block ships looking clean with zero CSS setup. Override visuals by wrapping the block in a custom root, or fork the renderer.
• The block is intentionally dumb — it submits the values it has. Server-side validation, spam protection, and storage are the host's job.