FormElements API Reference

The Form Elements component enables real-time synchronization of form elements, such as input fields, checkboxes, and radio buttons, among participants in the same room as well as seeing who is typing in real-time.

How to use

To initialize the Form Elements component, you can follow our quickstart guide.

Supported form elements

When using the Form Elements component, you will be able to synchronize the following input types: text, textarea, checkbox, color, date, datetime-local, email, month, number, password, radio, range, search, tel, time, url and week.

When using the date, datetime-local, and time, please note that it will be synchronized once the user finalizes typing a valid value, not while typing. Also, please use the password input type with caution.

Unsupported form elements

The following input types are not supported: div with content-editable, reset, submit, button, file, hidden, image, and input with type="hidden".

Usage

When initializing the Form Elements component, you can pass the following properties:

import { FormElements } from "@superviz/sdk";

const formElements = new FormElements({
  fields: ["name", "email", "dog", "cat", "fish"],
  disableOutline: true,
  disableRealtimeSync: false,
});

room.addComponent(formElements);

Properties

See below the parameters to use when initializing the Form Elements:

Name	Type	Description
fields	string[] or string	Specify the ID of the form elements that you want to be synchronized.
disableOutline	boolean	Disables the outline of the form elements.
disableRealtimeSync	boolean	Disables the real-time synchronization of the form content.

info

When adding a form element ID to the fields property, make sure that the id is rendered on the page before initializing the Form Elements component.

Callbacks

The Forms Elements in SuperViz SDK offer a range of events that allow you to monitor and respond to interactions and changes within the input elements.

BLUR

The BLUR event is triggered when an input element loses focus.

Example:

JavaScript

formElements.subscribe('field.blur', onBlur);

function onBlur(event) {
// do something
}

TypeScript

import { FieldEvents } from "@superviz/sdk/lib/components/form-elements/types";

formElements.subscribe(FieldEvents.BLUR, onBlur);

function onBlur(event: InputEvent) {
  // do something
}

On the callback function, you will receive an InputEvent object.

FOCUS

The FOCUS event is triggered when an input element gains focus.

Example:

JavaScript

formElements.subscribe('field.focus', onFocus);

function onFocus(event) {
// do something
}

TypeScript

import { FieldEvents } from "@superviz/sdk/lib/components/form-elements/types";

formElements.subscribe(FieldEvents.FOCUS, onFocus);

function onFocus(event: InputEvent) {
  // do something
}

On the callback function, you will receive an InputEvent object.

CONTENT_CHANGE

The CONTENT_CHANGE event is triggered when the content of an input element changes, it only works when a field is registered and Real-time Sync is enabled.

Example:

JavaScript

formElements.subscribe('field.contentChange', onContentChange);

function onContentChange(event) {
// do something
}

TypeScript

import { FieldEvents } from '@superviz/sdk/lib/components/form-elements/types';

formElements.subscribe(FieldEvents.CONTENT_CHANGE , onContentChange);

function onContentChange(event: InputPayload) {
  // do something
}

On the callback function, you will receive an object with the following arguments:

Name	Type	Description
value	string	The new value of the input element.
fieldId	string	The ID of the input element.
color	string	The color of the participant that is currently editing the element.
showOutline	boolean	Whether the outline of the input element is enabled.
syncContent	boolean	Whether the real-time synchronization of the input element is enabled.
attribute	string	The attribute of the input element that was changed.

INTERACTION

The INTERACTION event is triggered when a participant interacts with an input element, such as typing or selecting a value. This event only works when a field is registered, but it will also fire when the Real-time Sync is disabled.

Example:

JavaScript

formElements.subscribe('field.interaction', onInteraction);

function onInteraction(event) {
// do something
}

TypeScript

import { FieldEvents } from '@superviz/sdk/lib/components/form-elements/types';

formElements.subscribe(FieldEvents.INTERACTION , onInteraction);

function onInteraction(event: InputPayload) {
  // do something
}

On the callback function, you will receive an object with the following arguments:

Name	Type	Description
value	string	The new value of the input element.
fieldId	string	The ID of the input element.
color	string	The color of the participant that is currently editing the element.
showOutline	boolean	Whether the outline of the input element is enabled.
syncContent	boolean	Whether the real-time synchronization of the input element is enabled.
attribute	string	The attribute of the input element that was changed.

Methods

enableOutline()

The enableOutline method allows you to enable the outline of a specific form element. You need to pass the ID of the element as a parameter.

Enabling this feature through this method overrides the global flag enableOutline set in the constructor for this particular input.

Example:

formElements.enableOutline("name");

Parameters

Name	Type	Description
fieldId	string	Required. The ID of the form element.

disableOutline()

The disableOutline method allows you to disable the outline of a specific form element. You need to pass the ID of the element as a parameter.

Disabling this feature through this method overrides the global flag disableOutline set in the constructor for this particular input.

Example:

formElements.disableOutline("name");

Parameters

Name	Type	Description
fieldId	string	Required. The ID of the form element.

enableRealtimeSync()

The enableRealtimeSync method allows you to enable the real-time synchronization of the data of an input element. You need to pass the ID of the element as a parameter.

Enabling this feature through this method overrides the global flag disableRealtimeSync set in the constructor for this particular input.

Example:

formElements.enableRealtimeSync("name");

Parameters

Name	Type	Description
fieldId	string	Required. The ID of the form element.

disableRealtimeSync()

The disableRealtimeSync method allows you to disable the real-time synchronization of the data of an input element. You need to pass the ID of the element as a parameter.

Disabling this feature through this method overrides the global flag disableRealtimeSync set in the constructor for this particular input.

Example:

formElements.disableRealtimeSync("name");

Parameters

Name	Type	Description
fieldId	string	Required. The ID of the form element.

registerField()

The registerField method allows you to register a form element to receive updates from other participants. By utilizing this method, you don't need to enable the input field on the Form Elements constructor, allowing you to add a form element to the synchronization after the initialization. You need to pass the ID of the element as a parameter.

Example:

formElements.registerField("name");

Parameters

Name	Type	Description
fieldId	string	Required. The ID of the form element.

deregisterField()

The deregisterField method allows you to deregister a form element to stop receiving updates from other participants. You need to pass the ID of the element as a parameter.

Example:

formElements.deregisterField("name");

Parameters

Name	Type	Description
fieldId	string	Required. The ID of the form element.

sync()

When using the sync method, a registered field will be monitored and most interactions with it will be shared with every other user in the room that is tracking the same field. Examples of common interactions that will be monitored include typing, focusing, and blurring.

Example:

formElements.sync("name");

Parameters

Name	Type	Description
fieldId	string	Required. The ID of the form element.