Intro to Superform API

Harness the full power of Superform with our JavaScript SDK.

Getting Started

Initializing the Superform API is pretty simple. Check out this JavaScript example below:

// Use this snippet to get started

window.SuperformAPI = window.SuperformAPI || [];

// Subscribe to listen when Superform is ready 
window.SuperformAPI.push(({ getForm, allForms }) => {

    // Start interacting with the Superform API here
    
});

When to Use the Superform API?

Superform is powerful — out of the box. However, if something is not supported and you wish to extend Superform's functionalities, you can use the Superform API. We picked the best use cases you might want to use the Superform API for:

• If you want to get form data. Learn more.

• If you want to listen to when the form is submitted. Learn more.

• If you want to listen to state changes on navigation. Learn more.

• If you want to manually initialize Superform, for example, using it in a Wized project. Learn more.

• If you want to use hook() features, which allow you to bind your JavaScript logic with navigation and input validation. You can read more about navigation hooks and about input validation hooks.

• If you want to build plugins for Superform. Plugin guides coming soon 😊.

---

Global Superform API

The following APIs are available to interact with Superform.

Superform Class

With the Superform class, you can manually initialize Superform. Make sure not to include the sf attribute on your form container.

Syntax

const myForm = new Superform(formName)

Parameter	Type	Description
formName	string	The name or selector of the form container
Returns
A form instance	Superform Instance	Returns a Superform instance associated with the specified container

Usage example:

// Use this snippet to get started
window.SuperformAPI = window.SuperformAPI || [];
// Subscribe to listen when Superform is ready 
window.SuperformAPI.push(({ getForm, allForms }) => {
   /**
    * In this example, we are initializing Superform for the #myForm container
    **/
   const myForm = new Superform("#myForm");
   console.log(myForm);
});

getForm(formName)

Allows you to get a form by name if it is auto-initialized using the sf attribute.

Syntax

const myForm = getForm(formName)

Parameter	Type	Description
formName	string	The name of the form to retrieve
Returns
A form instance	Superform Instance	Returns a Superform instance if it exists, otherwise undefined

Usage example:

// Use this snippet to get started
window.SuperformAPI = window.SuperformAPI || [];
// Subscribe to listen when Superform is ready 
window.SuperformAPI.push(({ getForm, allForms }) => {
   /**
    * In this example, we are fetching a Superform instance with the name FORM_NAME
    **/
   const myForm = getForm("FORM_NAME"); // Returns Superform instance if it exists 
   console.log(myForm);

   /**
    * Another method to fetch a Superform instance 
    **/
   const myForm1 = SuperformAPI.getForm("FORM_NAME"); // Returns Superform instance if it exists 
   console.log(myForm1);
});

allForms()

Allows you to get an array of all initialized Superform instances.

Syntax

const myAllForms = allForms;

Returns	Type	Description
All forms	Array	An array containing all Superform instances

Usage example:

// Use this snippet to get started
window.SuperformAPI = window.SuperformAPI || [];
// Subscribe to listen when Superform is ready 
window.SuperformAPI.push(({ getForm, allForms }) => {
   /**
    * In this example, we are fetching all Superform instances
    **/
   const myAllForms = allForms; // Returns all Superform instances as an array
   console.log(myAllForms);

   /**
    * Another method to fetch all Superform instances 
    **/
   const myAllForms1 = SuperformAPI.allForms; // Returns all Superform instances as an array
   console.log(myAllForms1);
});

---

Managing Superform Instances

For advanced control of Superform instances and learn how to:

• Retrieve Form Data: Access form values programmatically with getFormData.

• Event Listeners: Utilize beforeStepChange, onStepChange, and onFormSubmit for custom actions.

• Register Hooks: Implement custom logic using registerInputValidationHook and registerNavigationHook.

Visit the Superform Instance documentation.