Skip to main content

Custom Form - Advanced

Using the Custom Form experience gives you complete control over the appearance and functionality (UI/UX).

In our previous examples we covered adding the component and styling it. In these examples we'll go over a few different scenarios for improving UX.

info

This guide assumes you've already gone through the Basic implementation here.

Submission Handling​

Using the onSuccess callback will let us know when the form was submitted successfully.

Let's add in a small element that shows after success.

Example
<body>
  <form id="form">
    <div id="vtagz-container"></div>
    <button id="submit" type="button">
      Submit
    </button>
  </form>
  <div id="success" style="display: none;">Subscribed!</div>
  <script>
    const vtagz = VTAGZ.open({
      link: "YOUR_CAMPAIGN_LINK",
      containerId: "vtagz-container",
      submitButtonId: "submit",
      mode: "capture",
    });
    const formEl = document.getElementById('form');
    const successEl = document.getElementById('success');
    
    // listen for "success" event
    vtagz.onSucess(() => {
      // hide our form
      formEl.style.display = 'none';
      // show our success element
      successEl.style.display = 'block';
    });
  </script>
</body>
Result

After submitting with a valid number, we'll see our "Subscribed!" message.

tip

You'll notice that VTAGZ automatically handles form validation and has default messages for users (all of which can be customized).

Error Handling​

Using the onError and onInputChange callbacks we can check the validity of the current input.

Let's add these along with a custom error element.

Example
<body>
  <form id="form">
    <div id="vtagz-container"></div>
    <div id="error" style="display: none;">Check your form for errors</div>
    <button id="submit" type="button">
      Submit
    </button>
  </form>
  <div id="success" style="display: none;">Subscribed!</div>
  <script>
    const vtagz = VTAGZ.open({
      link: "YOUR_CAMPAIGN_LINK",
      containerId: "vtagz-container",
      submitButtonId: "submit",
      mode: "capture",
    });
    const formEl = document.getElementById('form');
    const successEl = document.getElementById('success');
    const errorEl = document.getElementById('error');
    
    // listen for "success" event
    vtagz.onSucess(() => {
      // hide our form
      formEl.style.display = 'none';
      // show our success element
      successEl.style.display = 'block';
    });
    vtagz.onError(() => {
      // show error element
      errorEl.style.display = 'block';
    });
    vtagz.onInputChange((data) => {
      // hide error if input is valid
      if (data.isValid) {
        errorEl.style.display = 'none';
      }
    });
  </script>
</body>
Result

Controlling the input state​

The vtagz instance exposes the input state interface allowing you to disable/enable the input, as well as a few other options.

Let's use the enable() and disable() methods to control the flow with a required checkbox field.

We'll also need to handle our own submit call, removing the submitButtonId helper.

Example
<body>
  <form>
    <div>
      <input id='required' type='checkbox' required />
      <div>Some required checkbox field</div>
    </div>
    <div id="vtagz-container"></div>
    <button id="submit" type="button">
      Submit
    </button>
  </form>
  <script>
    const vtagz = VTAGZ.open({
      link: "YOUR_CAMPAIGN_LINK",
      containerId: "vtagz-container",
      //highligh-next-line
      // no submitButtonId
      mode: "capture",
    });

    const requiredEl = document.getElementById('required');

    // disable the input and button
    vtagz.input.disable();
    submitBtnEl.disabled = true;

    // listen for checkbox changes
    requiredEl.onchange = (e) => {
      if (e.target.checked) {
        vtagz.input.enable();
        submitBtnEl.disabled = false;
      } else {
        vtagz.input.disable();
        submitBtnEl.disabled = true;
      }
    }

    // handle handle submitting VTAGZ form
    const btn = document.getElementById('submit');
    btn.onclick = () => {
      vtagz.submit();
    };
  </script>
</body>
Result