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: "name@example.com", ...}
});


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)

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.

Last updated

Was this helpful?