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
Comments
0 comments
Please sign in to leave a comment.