Form Configuration Guide

Basic Form Configuration

@enlolab/forms provides a simple and declarative way to create complex forms. The main configuration is done through the FormConfig object.

Basic Structure

const myForm = FormFactory({
  formId: "my-form",
  fields: {
    // Field configuration
  },
  steps: {
    // Steps configuration
  },
  layout: {
    // Layout configuration
  },
  submit: {
    // Submit configuration
  },
  buttons: {
    // Button configuration
  },
});

Main Properties

Below is a high-level overview of every top-level key inside FormConfig:

Property	Type	Required	Description
formId	string	Yes	Unique identifier passed to the backend and DOM.
fields	Record<string, FieldConfig>	Yes	Declarative configuration for every field in the form.
steps	Record<string, Step>	Yes	Defines the navigation flow and conditional branching.
layout	LayoutConfig	No	Controls the grid columns, gaps and container classes.
submit	SubmitConfig	No	Determines how data is sent (default, recaptcha, custom).
buttons	FormButtons	No	Overrides labels, variants and actions for Submit, Next, Back.
successMessage	string | (values) => string	No	HTML or function returning the success message.
errorMessage	string | (error, values) => string	No	Custom message when submission fails.
onStepChange	(stepId) => void	No	Callback executed whenever the current step changes.
onSuccess	(values) => void	No	Callback after a successful submission.
onError	(error, values) => void	No	Callback when the submission throws.

submit

@enlolab/forms ships with three submission strategies:

Type	reCAPTCHA	When to use	Payload
default	✔️	Production forms that require bot protection	clientId, formId, data, recaptchaToken
default-no-recaptcha	✖️	Internal tools or low-risk environments	clientId, formId, data
custom	N/A	Full control over networking logic	Whatever you send from onSubmit

Example using the built-in endpoint + reCAPTCHA:

submit: {
  type: "default",
  endpoint: {
    url: "https://api.yourapp.com/forms/submit",
    clientId: "marketing-site" // optional
  },
  recaptcha: {
    siteKey: "YOUR_SITE_KEY",
    action: "submit"
  }
}

If you need advanced logic, switch to custom:

submit: {
  type: "custom",
  onSubmit: async (values) => {
    await fetch("/api/contact", {
      method: "POST",
      body: JSON.stringify(values),
      headers: { "Content-Type": "application/json" }
    });
  }
}

buttons

Form buttons configuration:

buttons: {
  submit: {
    label: "Submit",
    variant: "default"
  },
  next: {
    label: "Next",
    variant: "outline"
  },
  back: {
    label: "Back",
    variant: "ghost"
  }
}

Custom Messages

You can customize success and error messages in two ways:

Static messages

Simple string messages:

successMessage: "Form submitted successfully!",
errorMessage: "An error occurred while submitting the form"

Dynamic messages with HTML

You can use functions to generate messages dynamically based on form values:

successMessage: (values) => `✅ Thanks <strong>${values.name}</strong>, we'll be in touch!`,
errorMessage: (error, values) => `❌ Oops: ${error.message}`

The function receives:

• For successMessage: values: Record<string, unknown> - all form field values
• For errorMessage: error: Error and values: Record<string, unknown>

You can access any field value from the values object (e.g., values.email, values.transport). The returned string can contain HTML tags that will be safely rendered.

Callbacks

Tip: All callbacks receive the latest form values so you can call analytics or mutate state outside the form.

@enlolab/forms provides several callbacks to handle important events: