@formbrew/js

Typed JavaScript client and accessible DOM renderer for Formbrew forms.

Version 0.4.0 supports multiline Text configuration, Number sign and precision settings, and Date/Time, Hidden, Confirm, and Content fields. Integrations on 0.3.0 must upgrade before loading definitions that use those features. See the 0.4.0 release notes.

Install

npm install @formbrew/js

Headless client

import { createFormbrewClient } from "@formbrew/js";

const client = createFormbrewClient({ token: "YOUR_TOKEN" });
const definition = await client.fetchForm();

const result = await client.submit(
  { email: "[email protected]" },
  { metadata: { source: "contact-page" } },
);

console.log(result.message);

Browsers supply the request Origin automatically. Node and Bun integrations must provide the configured origin explicitly:

const client = createFormbrewClient({
  token: process.env.FORMBREW_TOKEN!,
  origin: "https://www.example.com",
});

Origin identifies the intended website context for the public API. It is not an authentication credential and can be set by non-browser HTTP clients.

DOM renderer

import { createFormbrewClient } from "@formbrew/js";
import { mountFormbrewForm } from "@formbrew/js/dom";
import "@formbrew/js/styles.css";

const client = createFormbrewClient({ token: "YOUR_TOKEN" });
const controller = await mountFormbrewForm("#contact-form", {
  client,
  metadata: { source: "pricing-page" },
  onSuccess(result) {
    console.log(result.message);
  },
});

// Later, if the host view is removed:
controller.destroy();

The stylesheet is optional. The renderer emits semantic markup with fb-* classes and CSS variables for custom themes.

The renderer supports every public field type. Multiline TEXT fields render a textarea, DATETIME fields use native date/time controls, HIDDEN fields are emitted as bare hidden inputs at the top of the form, CONFIRM fields mirror their target control and validate for a match, and CONTENT fields render safe rich text built entirely from explicit DOM nodes (never raw HTML).

Custom rendering

fetchForm() and the controller both expose the typed public definition. Fields are a discriminated union, so TypeScript narrows configuration and validation by type:

const definition = await client.fetchForm();

for (const field of definition.fields) {
  switch (field.type) {
    case "NUMBER":
      console.log(field.validationJson?.min);
      break;
    case "CHECKBOX_GROUP":
      console.log(field.configJson.options);
      console.log(field.validationJson?.maxSelections);
      break;
    case "SELECT":
      console.log(field.configJson.options);
      break;
    case "TEXT":
      console.log(field.configJson?.multiline);
      break;
    case "DATETIME":
      console.log(field.configJson.mode);
      break;
    case "CONFIRM":
      console.log(field.configJson.targetFieldId);
      break;
    case "CONTENT":
      console.log(field.configJson.document);
      break;
  }
}

const controller = await mountFormbrewForm("#contact-form", {
  client,
  definition,
});

console.log(controller.definition.schemaVersion);

Framework-neutral form helpers are available from @formbrew/js/form:

import {
  collectFormbrewSubmission,
  getCheckboxGroupValidationMessage,
  resolveFormbrewMetadata,
  synchronizeConfirmFields,
} from "@formbrew/js/form";

synchronizeConfirmFields(formElement, definition.fields);
const submission = collectFormbrewSubmission(formElement);
const metadata = {
  ...resolveFormbrewMetadata(() => ({ source: "custom-form" })),
  ...submission.metadata,
};

await client.submit(submission.values, { metadata });

if (field.type === "CHECKBOX_GROUP") {
  const message = getCheckboxGroupValidationMessage(field, selectedValues.length);
}

collectFormbrewSubmission() collects repeated string values into arrays and returns null-prototype values and metadata objects. Form fields whose names begin with _ are placed in metadata with the first underscore removed; file values are ignored.

synchronizeConfirmFields(form, fields) matches controls by name within that form and updates only the confirmation controls' custom validity. Call it after input/change handling, after native reset has restored default values, and before reporting validity. It uses the target's normalization, including multiline text, numeric formatting, and timezone-free time values. It does not remove confirmation answers from the submitted payload; the server validates and excludes them from storage. The managed DOM renderer handles this wiring and cleans up its listeners on destroy().

Content links use normal same-tab navigation, consistently with the React and generated HTML renderers. Custom renderers can choose different navigation behavior while retaining safe URL rules.

Cancellation

Both network methods and the renderer accept AbortSignal:

const abortController = new AbortController();
await client.fetchForm({ signal: abortController.signal });

Errors

API, response, network, and configuration errors use FormbrewError. Standard AbortError exceptions are preserved.

import { FormbrewError } from "@formbrew/js";

try {
  await client.submit({ email: "invalid" });
} catch (error) {
  if (error instanceof FormbrewError) {
    console.error(error.code, error.status, error.details);
  }
}

The Formbrew API remains authoritative for submission validation. The DOM renderer maps supported constraints to native browser controls for immediate feedback.

0.4.0

0.4.0 adds multiline Text configuration, Number sign and precision settings, and Date/Time, Hidden, Confirm, and Content fields. Full notes: Frontend 0.4.0.

0.3.0

0.3.0 adds SELECT field support (SelectFieldDefinition, isSelectField()) and removes the FormbrewFieldWidth type and width field property. PublicFormFieldBase no longer has width. Full notes: Frontend 0.3.0.