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/react-sdk';

function FormElementsImplementation() {
  return (
      <FormElements fields={['name', 'email', 'dog', 'cat', 'fish']} />
      <label>
        Name:
        <input type="text" id="name" name="name" />
      </label>
      <label>
        Email:
        <input type="email" id="email" name="email" />
      </label>
      <label>
        What is your kind of pet?
        <input type="radio" name="pet" value="cat" id="cat" /> Cat
        <input type="radio" name="pet" value="dog" id="dog" /> Dog
        <input type="radio" name="pet" value="fish" id="fish" /> Fish
      </label>
  );
}

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.
onContentSync	(data) => void	This callback function is triggered when the content of an input element changes, it only works when a field is registered and Real-time Sync is enabled.
onContentChange	(data) => void	This callback function 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.

info

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

Hooks

useFormElements

enableOutline

Type: (fieldId: string): void

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:

import { useFormElements } from "@superviz/react-sdk";

function YourComponent() {
  const { enableOutline } = useFormElements();

  useEffect(() => {
    enableOutline("name");
  }, []);

  return (
    <>
      <label>
        Name: <input type="text" id="name" name="name" />
      </label>
      <label>
        Email: <input type="email" id="email" name="email" />
      </label>
    </>
  );
}

Parameters

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

disableOutline

Type: (fieldId: string): void

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:

import { useFormElements } from "@superviz/react-sdk";

function YourComponent() {
  const { disableOutline } = useFormElements();

  useEffect(() => {
    disableOutline("name");
  }, []);

  return (
    <>
      <label>
        Name: <input type="text" id="name" name="name" />
      </label>
      <label>
        Email: <input type="email" id="email" name="email" />
      </label>
    </>
  );
}

Parameters

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

enableRealtimeSync

Type: (fieldId: string): void

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:

import { useFormElements } from "@superviz/react-sdk";

function YourComponent() {
  const { enableRealtimeSync } = useFormElements();

  useEffect(() => {
    enableRealtimeSync("name");
  }, []);

  return (
    <>
      <label>
        Name: <input type="text" id="name" name="name" />
      </label>
      <label>
        Email: <input type="email" id="email" name="email" />
      </label>
    </>
  );
}

Parameters

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

disableRealtimeSync

Type: (fieldId: string): void

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:

import { useFormElements } from "@superviz/react-sdk";

function YourComponent() {
  const { disableRealtimeSync } = useFormElements();

  useEffect(() => {
    disableRealtimeSync("name");
  }, []);

  return (
    <>
      <label>
        Name: <input type="text" id="name" name="name" />
      </label>
      <label>
        Email: <input type="email" id="email" name="email" />
      </label>
    </>
  );
}

Parameters

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

sync

Type: (fieldId: string): void

When using the sync function, 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 or selecting a value.

Example:

import { useFormElements } from "@superviz/react-sdk";

function YourComponent() {
  const { sync } = useFormElements();

  useEffect(() => {
    sync("name");
  }, []);

  return (
    <>
      <label>
        Name: <input type="text" id="name" name="name" />
      </label>
      <label>
        Email: <input type="email" id="email" name="email" />
      </label>
    </>
  );
}

Parameters

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

registerField

Type: (fieldId: string): void

The register 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:

import { useFormElements } from "@superviz/react-sdk";

function YourComponent() {
  const { registerField } = useFormElements();

  useEffect(() => {
    registerField("name");
  }, []);

  return (
    <>
      <label>
        Name: <input type="text" id="name" name="name" />
      </label>
      <label>
        Email: <input type="email" id="email" name="email" />
      </label>
    </>
  );
}

Parameters

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

deregisterField

Type: (fieldId: string): void

The deregister 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:

import { useFormElements } from "@superviz/react-sdk";

function YourComponent() {
  const { deregisterField } = useFormElements();

  useEffect(() => {
    deregisterField("name");
  }, []);

  return (
    <>
      <label>
        Name: <input type="text" id="name" name="name" />
      </label>
      <label>
        Email: <input type="email" id="email" name="email" />
      </label>
    </>
  );
}

Parameters

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