Form instance, hooks & events

Install, init, and walkthrough examples live in Overview & setup. This page is the reference for initForms / initFormsServer, the form instance methods, the React hooks, and the analytics events Forms emits. Which fields a form reads and writes depends on its schema.

Set up & use forms

In the browser, call initForms; on the server, call initFormsServer. Each checks your Core setup once, then lets you open a form with getForm.

JavaScript
Server

import { initForms } from '@embeddables/forms'

const forms = initForms(options)
const form = forms.getForm({ formId })

import { initEmbeddablesServer } from '@embeddables/core/server'
import { initFormsServer } from '@embeddables/forms/server'

const server = initEmbeddablesServer({ ...config })
const forms = initFormsServer({ server })
const form = forms.getForm({ formId })

Use this when Forms runs during a server page load (SSR). You open forms the same way with getForm, but answers stay in memory for that request — they are not saved to the visitor’s browser or sent to Analytics unless you set that up separately.

const serverFormData = forms.getServerFormData()
// pass into client initForms:
// serverFormData: [{ formId: 'signup', serverFormData: serverFormData['signup'] }]

getServerFormData() on the initFormsServer client returns the current values for every initialized form, keyed by form id. Feed each entry into the client initForms serverFormData option to hydrate the browser form from SSR.

InitFormsOptions

required

Init configuration. core is required; the rest are optional. See Options below.

string

required

Passed to getForm. Must be the id of a schema registered on Core. An unknown id throws a FormsError. getForm returns one instance per form id — the first call builds it, every later call returns that same instance.

Options

Passed to initForms. Per-form options (customValidations, serverFormData) are arrays keyed by formId.

core

Initialized Core instance with registered schemas

import { initEmbeddables } from '@embeddables/core'
import { initForms } from '@embeddables/forms'

const core = initEmbeddables({ ...config, publishableKey: 'pk_sandbox_<your-key>' })
const forms = initForms({ core })

EmbeddablesInstance

required

An initialized @embeddables/core instance with at least one form schema registered (via config.forms from em build, or forms on initEmbeddables). Init throws a FormsError if Core is missing required methods or has no form schemas. Forms composes on Core for identity but never reads or writes the identity entry.

customValidations

Runtime validator functions for CLI-authored schemas

const forms = initForms({
  core,
  customValidations: [
    {
      formId: 'signup',
      customValidations: {
        email: ({ value }) => (value.endsWith('@example.com') ? 'No example.com addresses' : null),
      },
    },
  ],
})

{ formId, customValidations }[]

Per-field validator functions, matched to schemas by formId. Use this for CLI-generated schemas, which cannot carry functions themselves (a schema must survive a JSON round trip; only validations.custom may be a function). Each validator receives { value, values } and returns a string, a list of strings, or null. An unknown formId or field key throws a SchemaError.

serverFormData

SSR hydration seed from initFormsServer

const forms = initForms({
  core,
  serverFormData: [{ formId: 'signup', serverFormData: { email: '[email protected]' } }],
})

{ formId, serverFormData }[]

Per-form values used to seed the form on init — typically the output of initFormsServer().getServerFormData(). On overlapping keys, serverFormData overrides localStorage; localStorage fills only the gaps. An unknown formId throws a SchemaError.

analyticsInstance

Optional analytics client for event tracking

import { initAnalytics } from '@embeddables/analytics'

const analytics = initAnalytics({ core })
const forms = initForms({ core, analyticsInstance: analytics })

AnalyticsInstance

Optional analytics client used only for event tracking. When provided, a successful .set() emits data:updated plus one field:updated per changed field, and .submit() emits form:submitted — see Analytics events. A rejected trackEvent() never fails a .set() / .submit(); the failure surfaces as trackError on the result. In React, the CLI wires Analytics into Forms automatically from Core — pass analyticsInstance only to override that default. Omitting it disables event tracking; durable saves still run when Core resolves persistence config.

Methods and hooks

React covers the forms() module factory and the hooks — register the factory on EmbeddablesProvider before calling hooks. JavaScript & Server lists methods on the form from initForms or initFormsServer — the same names on both entry points; SSR uses in-memory storage only (no localStorage, durable save, or Analytics on .set() / .submit()). After set, submit, or validate, check result.ok and result.errors — a failed validation does not throw an error.

React
JavaScript & Server

React bindings from @embeddables/forms/react. Register Forms on EmbeddablesProvider’s modules prop with the forms() module factory, then bind fields with these hooks. Every hook returns null / empty state until Forms is ready — handle that before calling instance methods.

forms()

Module factory for EmbeddablesProvider

import { EmbeddablesProvider } from '@embeddables/core/react'
import { forms } from '@embeddables/forms/react'

<EmbeddablesProvider config={config} modules={[forms({ analyticsInstance })]}>
  {children}
</EmbeddablesProvider>

Returns an EmbeddablesReactModule for the provider’s modules prop. The generated CLI setup wires this for you; pass options only to override. core is supplied by the provider — do not pass it here. Form schemas must be on config (from em build), not on forms().

{ formId, customValidations }[]

Same as customValidations on initForms.

{ formId, serverFormData }[]

Same as serverFormData on initForms — typically SSR hydration seed.

AnalyticsInstance

Optional analytics client for auto-emitted form events. The generated React setup wires Analytics automatically when both SDKs are installed.

useForm()

Reactive form, values, and errors for one form

const { form, values, errors } = useForm({ formId: 'signup' })

string

required

Id of a declared form. No type arguments needed — the id narrows the form and the schema map comes from the registry em build augments.

FormInstance | null

The shared instance for this form id, or null until Forms is ready. Every useForm with the same id shares one instance.

Partial<FormValues>

Reactive stored values.

FieldErrors

Reactive per-field validation messages.

useFormField()

Commit-on-blur binding for one field

const { value, error, setValue, onBlur } = useFormField({ form, key: 'email' })

Typing updates local draft state via setValue; form.set() runs on onBlur (and only when the draft changed). Wire the input’s onChange to setValue and its onBlur to onBlur.

FormInstance | null

required

The instance from useForm (may be null).

FormFieldKey

required

The field key to bind.

useFormErrors()

Just the reactive validation errors

const errors = useFormErrors(form)

FormInstance | null

required

The instance from useForm. Returns the reactive FieldErrors map.

Everything you can call on the form from getForm — in plain JavaScript or from useForm in React.

set()

Validate and persist a patch atomically

const result = await form.set({ email: '[email protected]' })
if (!result.ok) console.log(result.errors)

Applies every key in one call or writes nothing. On success it persists locally, fires a best-effort durable save, and — when Analytics is wired — emits data:updated plus one field:updated per changed field (Analytics events). Bind it to blur, a “next step” button, or a short debounce — never per-keystroke onChange.

Partial<FormValues>

required

The field keys to write, typed to the schema. An empty patch resolves immediately with ok: true and does not validate, write, or emit. Unknown or non-serializable keys fail validation. A custom validator that throws propagates synchronously out of .set().

get() / getAll()

Read stored values by field key

const email = form.get('email')
const all = form.getAll()

FormFieldKey

required

For get(key) — a declared field key. Returns the stored value typed by the field’s declared type, or undefined if unset or undeclared. Values are served from an in-memory copy taken at init and are not refreshed by writes from another instance or tab.

getAll() takes no arguments and returns the stored values for every declared field.

getValueByProtocolFieldId()

Read a value by the field's protocolFieldId

const value = form.getValueByProtocolFieldId('protocol_email')

ProtocolFieldId

required

A field’s declared protocolFieldId. Returns the stored value typed like get() for the backing field, or undefined when no field maps to the id or the value is unset.

validate()

Check values without writing or tracking

const result = await form.validate({ email: 'not-an-email' })
// or validate every declared field against stored values:
const all = await form.validate()

Runs validation without touching storage or Analytics. With a patch, it validates only those keys against a merged snapshot and updates their errors; with no argument, it validates every declared field and replaces errors() wholesale.

Partial<FormValues>

Optional. The keys to validate. Omit to validate the whole form. An empty patch resolves with ok: true and no error-state change.

submit()

Validate every field, then emit form:submitted

const result = await form.submit()
if (result.ok) console.log(result.values)

Validates every declared field, fires a best-effort durable save, and — when Analytics is wired — emits form:submitted (Analytics events). Not idempotent: every call emits another event, so guard against double-clicks. Nothing is emitted when validation fails. Takes no arguments.

Read errors, reset the form, observe changes

const errors = form.errors()
form.clear()
const unsubscribe = form.subscribe(() => rerender())

errors() returns the current per-field validation messages. clear() removes this form’s stored values (other forms on the origin are untouched). subscribe(listener) registers a synchronous listener for value and error changes and returns an unsubscribe function — the React hooks use it internally.

() => void

required

For subscribe — called on every value or error mutation. A listener that throws never affects form state.

Analytics events

Emitted automatically only when an analyticsInstance is wired (directly, or via the CLI in React). Each is a standard Analytics event — see the Analytics event reference for the full field list.

When Analytics is wired, do not also call analytics.trackEvent(...) yourself for these events — you will double-count. Forms owns data:updated, field:updated, and form:submitted for the forms it manages.

data:updated

Emitted once per successful set(), carrying every changed key

// sent automatically on a successful form.set({ ... })
{
  event_name: 'data:updated',
  data: { email: { value: '[email protected]', label: 'Email' } },
}

object

One entry per changed key; each has value (stringified, max 1024 chars) and label (the field’s label, max 256 chars).

field:updated

One per changed field on set()

// one event per changed field, alongside data:updated
{
  event_name: 'field:updated',
  field_key: 'email',
  field_type: 'email',
  field_value: '[email protected]',
}

string

The changed field’s key.

string

The field’s declared type (text, email, number, boolean, select, multiselect, json).

string | number | boolean | object | array

The raw new value.

string

Included only when the field declares a registryId / protocolFieldId.

form:submitted

Emitted once per successful submit()

// sent automatically on a successful form.submit()
{ event_name: 'form:submitted', form_key: 'signup' }

string

The submitted form’s id. Answers are sent as separate data:updated / field:updated events, not on this event.

Returns

getForm returns a FormInstance. Its write methods resolve to result objects that never reject on validation failure.

boolean

required

true when the operation succeeded. set, submit, and validate all return it.

FieldErrors

required

Per-field validation messages; an empty object means no errors.

Partial<FormValues>

Present on submit and validate results — the current stored values.

unknown

Present on set / submit results only when an analyticsInstance was configured and its trackEvent rejected. The field values are still persisted; the error is reported, never thrown.

{
  "ok": true,
  "errors": {},
  "values": { "email": "[email protected]" }
}

​Set up & use forms

​Options

​Methods and hooks

​Analytics events

​Returns

Set up & use forms

Options

Methods and hooks

Analytics events

Returns