Integrating HeavySet Forms with Next.js – HeavySet Tech

Overview

This guide provides a production-tested implementation for integrating HeavySet Tech forms into your Next.js application. The component supports both standard forms (with session caching) and fresh load forms (for events and canvassing).

Prerequisites

Next.js 12+ (with App Router or Pages Router)
React 16.8+ (for Hooks support)
Your HeavySet API Token ID
Your domain must be whitelisted for your API Token ID (contact support@heavyset.tech if unsure)

Installation

Create components/HeavySetForm.jsx:

// components/HeavySetForm.jsx
import { useEffect, useRef, useState } from 'react';
import Head from 'next/head';

/**
 * HeavySet Form Component
 * 
 * @param {string} apiTokenId - Your HeavySet API token ID
 * @param {string} iframeId - Unique ID for the iframe/container element
 * @param {boolean} freshLoad - Use fresh load mode for events/canvassing (no session caching)
 */
export default function HeavySetForm({ 
  apiTokenId, 
  iframeId, 
  freshLoad = false
}) {
  const [isMounted, setIsMounted] = useState(false);
  const scriptExecuted = useRef(false);

  useEffect(() => {
    setIsMounted(true);
  }, []);

  useEffect(() => {
    if (isMounted && !scriptExecuted.current) {
      scriptExecuted.current = true;

      if (freshLoad) {
        // FRESH LOAD MODE: For events/canvassing - no session caching
        const script = document.createElement('script');
        script.src = 'https://cdn.heavyset.tech/iframe-loader.min.js?v=1';
        script.onload = function () {
          window.injectHeavySetIframe(apiTokenId, iframeId, '');
        };
        document.body.appendChild(script);
      } else {
        // STANDARD MODE: With session caching
        if (typeof window.authHeavySetIframe === 'function') {
          window.authHeavySetIframe(apiTokenId, iframeId);
        } else {
          const script = document.createElement('script');
          script.src = 'https://cdn.heavyset.tech/iframe-loader.min.js?v=1';
          script.onload = function () {
            window.authHeavySetIframe(apiTokenId, iframeId);
          };
          document.body.appendChild(script);
        }
      }
    }
  }, [isMounted, apiTokenId, iframeId, freshLoad]);

  return (
    <>
      <Head>
        <link rel="dns-prefetch" href="https://apt-ui-classic1.heavyset.tech" />
        <link rel="preconnect" href="https://apt-ui-classic1.heavyset.tech" crossOrigin="anonymous" />
        <link rel="dns-prefetch" href="https://cdn.heavyset.tech" />
        <link rel="preconnect" href="https://cdn.heavyset.tech" crossOrigin="anonymous" />

        {!freshLoad && (
          <link rel="prefetch" href={`https://apt-ui-classic1.heavyset.tech?apiTokenId=${apiTokenId}`} as="document" />
        )}

        <link
          rel="preload"
          href="https://cdn.heavyset.tech/iframe-loader.min.js?v=1"
          as="script"
          crossOrigin="anonymous"
        />
      </Head>
      
      {isMounted && (
        <>
          <style jsx global>{`
            .heavyset-container iframe {
              border: none;
              width: 560px;
              max-width: 100%;
              height: 730px;
            }
          `}</style>
          
          {freshLoad ? (
            <div id={iframeId} className="heavyset-container" />
          ) : (
            <div className="heavyset-container">
              <iframe
                title="HeavySet Form"
                id={iframeId}
                fetchpriority="high"
                src={`https://apt-ui-classic1.heavyset.tech?apiTokenId=${apiTokenId}`}
              />
            </div>
          )}
        </>
      )}
    </>
  );
}

Usage Examples

Standard Mode (Website Contact Forms)

// pages/contact.jsx
import HeavySetForm from '@/components/HeavySetForm';

export default function ContactPage() {
  return (
    <div>
      <h1>Contact Us</h1>
      <HeavySetForm 
        apiTokenId="12345678-1234-1234-1234-123456789abc" 
        iframeId="contactForm" 
      />
    </div>
  );
}

Fresh Load Mode (Events/Trade Shows)

// pages/event.jsx
import HeavySetForm from '@/components/HeavySetForm';

export default function EventPage() {
  return (
    <div>
      <h1>Event Registration</h1>
      <HeavySetForm 
        apiTokenId="87654321-4321-4321-4321-cba987654321" 
        iframeId="eventForm"
        freshLoad={true}
      />
    </div>
  );
}

Multiple Forms on One Page

<HeavySetForm apiTokenId="..." iframeId="form1" />
<HeavySetForm apiTokenId="..." iframeId="form2" freshLoad={true} />

When to Use Each Mode

Standard Mode (freshLoad={false})

Website contact forms
Demo requests
General inquiries
Uses session caching

Fresh Load Mode (freshLoad={true})

Events and trade shows
Canvassing
Kiosks
No session caching

Styling

Default Styles

Width: 560px (max-width: 100%)
Height: 730px
Border: none

Custom Styling

Override the default styles by adding a <style> tag to your page or adding CSS to your stylesheet. Target the iframe using the iframeId:

<HeavySetForm apiTokenId="..." iframeId="myForm" />

<style>{`
  #myForm iframe {
    width: 100%;
    height: 800px;
    max-width: 900px;
  }
`}</style>

Or add to your CSS file:

/* styles.css */
#myForm iframe {
  width: 100%;
  height: 800px;
  max-width: 900px;
}

Responsive Example

<HeavySetForm apiTokenId="..." iframeId="myForm" />

<style>
  #myForm iframe {
    width: 100%;
    height: 680px;
  }

  @media (max-width: 768px) {
    #myForm iframe {
      height: 850px;
    }
  }
</style>

Centered with Max Width

<style>
  #myForm {
    display: flex;
    justify-content: center;
  }

  #myForm iframe {
    width: 780px;
    max-width: 100%;
    height: 680px;
  }
</style>

Troubleshooting

Form Not Loading

Most Common Cause: Your domain is not whitelisted for this API Token ID.

Solution: Contact support@heavyset.tech with:

Your API Token ID
The domain where you're embedding the form
Whether it's for production, staging, or development

Multiple Forms Not Working

If apiTokenId's are different or forms need different styling, ensure each form has a unique iframeId:

// ❌ Bad - Same ID
<HeavySetForm apiTokenId="..." iframeId="form" />
<HeavySetForm apiTokenId="..." iframeId="form" />

// ✅ Good - Unique IDs
<HeavySetForm apiTokenId="..." iframeId="salesForm" />
<HeavySetForm apiTokenId="..." iframeId="eventForm" />

Styles Not Applied

Use the correct selector targeting the iframe:

/* ✅ Correct */
#myForm iframe { ... }

/* ❌ Wrong */
#myForm { ... }

TypeScript Support

For TypeScript projects, add type declarations:

// types/heavyset.d.ts
interface Window {
  authHeavySetIframe?: (apiTokenId: string, iframeId: string) => void;
  injectHeavySetIframe?: (apiTokenId: string, containerId: string, styles: string) => void;
}

Support

Form not loading or domain whitelisting issues:
Contact: support@heavyset.tech

Next.js integration questions:
Refer to this guide or Next.js documentation at https://nextjs.org/docs

Related to