Superform Instance

Gain total programmatic control of your Superform instance.

Superform instances allow you to utilize useful methods and properties, enabling fine-grained control over your forms.

Form Data Methods

getFormData()

With the getFormData() method, you can retrieve form values as an object.

Syntax

const formData = myForm.getFormData() 

Method

Name	Returns	Description
getFormData	Object	Retrieves form values as an object.

Usage example:

window.SuperformAPI = window.SuperformAPI || [];
window.SuperformAPI.push(({ getForm, allForms }) => {
    const myForm = getForm("myForm");
    const formData = myForm.getFormData(); // Returns form data as an object
    console.log(formData); // {email: "[e-mail]", ...}
});

---

Step Lifecycle Methods

beforeStepChange(fn)

With the beforeStepChange method, you can register a listener that will execute right before a step change. This is useful for performing actions like triggering events for analytics.

Syntax

myForm.beforeStepChange((params) => {})

Params Object

The params object passed to the beforeStepChange callback function contains the following properties:

Property	Type	Description
data	Object	The current form data
stepCount	number	The current step index
progress	number	The current progress percentage (0-100)
scores	Object	Contains score data

Usage example:

window.SuperformAPI = window.SuperformAPI || [];
window.SuperformAPI.push(({ getForm, allForms }) => {
    const myForm = getForm("myForm");
    myForm.beforeStepChange((params) => {
        console.log(params.data); // Returns form data
        console.log(params.stepCount); // Returns current step index
        console.log(params.progress); // Returns current progress percentage
        console.log(params.scores); // Returns scores object

        // Sending custom event for analytics
        gtag("event", "step_event", {
            "step_index": params.stepCount,
            "progress": params.progress
        });
    });
});

onStepChange(fn)

With the onStepChange method, you can register a listener that will execute on a step change. This is useful for performing actions like playing/pausing videos, playing animations, or storing user progress via third-party APIs.

Syntax

myForm.onStepChange((params) => {})

Params Object

The params object passed to the onStepChange callback function contains the following properties:

Property	Type	Description
data	Object	The current form data
stepCount	number	The current step index
progress	number	The current progress percentage (0-100)
scores	Object	Contains score data

Usage example:

window.SuperformAPI = window.SuperformAPI || [];
window.SuperformAPI.push(({ getForm, allForms }) => {
    const myForm = getForm("myForm");
    const myVideo = document.getElementById("myVideo");

    myForm.onStepChange((params) => {
        console.log(params.data); // Returns form data
        console.log(params.stepCount); // Returns current step index
        console.log(params.progress); // Returns current progress percentage
        console.log(params.scores); // Returns scores object

        /**
        * Assuming a video element is present on the first step, 
        * auto-play when the user is on the first step. On step change, 
        * pause the video.
        **/
        if (params.stepCount === 0) {
            myVideo.play();
        } else {
            myVideo.pause();
        }
    });
});

---

Form Submit Methods

onFormSubmit(fn)

With the onFormSubmit method, you can register a listener that will execute when the form is submitted. This is useful for performing actions like triggering events for analytics or executing your business logic.

Syntax

myForm.onFormSubmit((params) => {})

Params Object

The params object passed to the onFormSubmit callback function contains the following properties:

Property	Type	Description
data	Object	The current form data
stepCount	number	The current step index
progress	number	The current progress percentage (0-100)
scores	Object	Contains score data

Usage example:

window.SuperformAPI = window.SuperformAPI || [];
window.SuperformAPI.push(({ getForm, allForms }) => {
    const myForm = getForm("myForm");
    const myVideo = document.getElementById("myVideo");

    myForm.onFormSubmit((params) => {
        console.log(params.data); // Returns form data
        console.log(params.stepCount); // Returns current step index
        console.log(params.progress); // Returns current progress percentage
        console.log(params.scores); // Returns scores object

        // Sending custom event for analytics
        gtag("event", "lead_capture", {
            "interest": params.data.interest,
            "rating": params.scores.rating
        });
    });
});

---

Hook Methods

registerNavigationHook(hookName, fn)

Registers a custom navigation hook for form elements, enabling dynamic navigation logic based on form data or other conditions. Read more about navigation hooks here.

Navigation hooks support async returns, allowing you to return a promise that resolves to a string or number.

Parameter	Type	Description
hookName	string	A unique identifier for the hook.
fn	function	A function that executes for navigation. Receives a params object with form data and other details.
Returns		Returns either one valid instruction
step-name	string or Promise<string>	The callback function can return a Step Teleport by step name indicating the next step name.
Linear navigation instruction	"next" "prev" "previous" "back" or Promise<Linear Instruction>	The callback function can return a Linear navigation instruction.
Step Teleport by signed number instruction (i.e +1, -2 or valid signed number)	Signed number as string or Promise<Step teleport string>	The callback function can return a Step Teleport by signed number navigation instruction.
Hook instruction (i.e hook(another_Hook))	hook(HOOK_NAME) or Promise<"hook(HOOK_NAME)">	The callback function can return a hook navigation instruction.

// Wait for Superform to be ready before registering hooks
window.SuperformAPI = window.SuperformAPI || [];
window.SuperformAPI.push(({ getForm }) => {
    const myForm = getForm("myForm");

    // Register a navigation hook for conditional navigation
    myForm.registerNavigationHook("checkNavigation", (params) => {
        const { data, stepCount, progress, scores } = params;

        // Example condition for navigation
        if (data.bookingType === "Business") {
            return "business_step";
        } else {
            return "economy_step";
        }
    });
});

registerInputValidationHook(hookName, fn)

Registers a custom validation hook for form inputs. This method allows you to define complex validation logic programmatically. Read more about validation hooks here.

Parameter	Type	Description
hookName	string	A unique identifier for the hook.
fn	function	A function that executes for validation. Receives a params object with form data and other details.
Returns
true or false	Boolean	The callback function must return a Boolean indicating the validation result (true for pass, false for fail).

// Wait for Superform to be ready before registering hooks
window.SuperformAPI = window.SuperformAPI || [];
window.SuperformAPI.push(({ getForm }) => {
    const myForm = getForm("myForm");

    // Register a validation hook for the email input field
    myForm.registerInputValidationHook("validateEmail", (params) => {
        const { data } = params; // Destructure to access form data directly
        return !data.email.includes("@gmail.com"); // Fail validation for Gmail addresses
    });
});

Notes

• The hook function must be synchronous; asynchronous operations should be managed outside this method.

• Using a unique hook name is crucial as reusing a hook name will overwrite the previous hook.