# Intro to Superform API

## Getting Started

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

```javascript
// 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:

* [x] If you want to get form data. [Learn more](https://deltaclan.gitbook.io/superform/superform-instance#getformdata).
* [x] If you want to listen to when the form is submitted. [Learn more](https://deltaclan.gitbook.io/superform/superform-instance#onformsubmit-cb).
* [x] If you want to listen to state changes on navigation. [Learn more](https://deltaclan.gitbook.io/superform/superform-instance#beforestepchange-cb).
* [x] If you want to manually initialize Superform, for example, using it in a [Wized](https://wized.com/) project. [Learn more](#superform-class).
* [x] 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 ](https://deltaclan.gitbook.io/superform/essentials/navigation-overview/hook)and about input [validation hooks](https://deltaclan.gitbook.io/superform/input-validation-and-errors/validation/hook).
* [x] ~~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**

```javascript
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:

```javascript
// 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

```javascript
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:

```javascript
// 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

```javascript
const myAllForms = allForms;
```

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

#### Usage example:

```javascript
// 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](https://deltaclan.gitbook.io/superform/js-sdk/superform-instance "mention") documentation.