Integration

Embeddable Forms

Embed beautiful, customizable forms on any website. Use our hosted form builder or customize with your own CSS.

Quick Start

Add a form to your website with a single script tag:

HTML
<script 
  src="https://townhall.gg/embed.js" 
  data-form-id="YOUR_FORM_ID"
></script>
💡
Find your Form ID

Go to your dashboard, click on any form, and copy the Form ID from the Setup tab.

Embed Types

Choose from four different embed styles:

Inline (Default)

Embeds the form directly in your page content.

HTML
<script 
  src="https://townhall.gg/embed.js" 
  data-form-id="YOUR_FORM_ID"
  data-type="inline"
></script>

Popup Modal

Shows a button that opens the form in a centered modal.

HTML
<script 
  src="https://townhall.gg/embed.js" 
  data-form-id="YOUR_FORM_ID"
  data-type="popup"
  data-button-text="Contact Us"
></script>

Slide-in Panel

Shows a button that slides in a panel from the right side.

HTML
<script 
  src="https://townhall.gg/embed.js" 
  data-form-id="YOUR_FORM_ID"
  data-type="slide"
  data-button-text="Get in Touch"
></script>

Floating Button

Adds a floating button in the corner that opens a popup form.

HTML
<script 
  src="https://townhall.gg/embed.js" 
  data-form-id="YOUR_FORM_ID"
  data-type="floating"
  data-position="bottom-right"
  data-button-text="💬 Contact"
></script>

Customization Options

Customize the appearance with data attributes:

HTML
<script 
  src="https://townhall.gg/embed.js" 
  data-form-id="YOUR_FORM_ID"
  data-type="popup"
  data-theme="dark"
  data-accent="6366f1"
  data-radius="12"
  data-button-text="Contact Sales"
  data-button-color="6366f1"
  data-hide-title="true"
  data-hide-branding="true"
  data-width="500px"
  data-css="https://example.com/custom-form.css"
></script>

All Options

AttributeDescriptionDefault
data-form-idYour form ID (required)-
data-typeinline, popup, slide, floatinginline
data-themelight, dark, autoauto
data-accentAccent color (hex without #)3b82f6
data-radiusBorder radius in pixels8
data-button-textText for trigger buttonContact Us
data-button-colorButton background color (hex)Same as accent
data-positionbottom-right, bottom-left (floating only)bottom-right
data-widthPopup/slide width440px
data-hide-titleHide form titlefalse
data-hide-brandingHide "Powered by TownHall"false
data-cssURL to custom CSS file-

Iframe Embed

For more control, embed the form using an iframe:

HTML
<iframe 
  src="https://townhall.gg/embed/YOUR_FORM_ID?theme=light&accent=6366f1"
  width="100%" 
  height="500" 
  style="border: none;"
></iframe>

URL Parameters

Customize via query parameters:

text
https://townhall.gg/embed/YOUR_FORM_ID
  ?theme=dark
  &accent=6366f1
  &radius=12
  &hideTitle=true
  &hideBranding=true
  &css=https://example.com/custom.css

Form Builder

Create custom forms with our visual form builder. Access it from the "Builder" tab in your form details.

Supported Field Types

  • Text - Single line text input
  • Email - Email address with validation
  • Phone - Phone number input
  • URL - Website URL input
  • Number - Numeric input with min/max
  • Textarea - Multi-line text
  • Dropdown - Select from options
  • Radio - Single choice from options
  • Checkbox - Multiple selections or single toggle
  • Date - Date picker
  • Time - Time picker
  • File - File upload
  • Hidden - Hidden field with preset value

Field Options

Each field supports:

  • Label - Display text shown above the field
  • Field Name - Key used in submission data
  • Placeholder - Hint text inside the field
  • Help Text - Description shown below the field
  • Required - Make the field mandatory
  • Width - Full or half width for layout

Custom CSS

Override default styles by providing a URL to your own CSS file. The form uses CSS variables that you can customize:

CSS
/* Custom form styles */
:root {
  --embed-bg: #ffffff;
  --embed-bg-secondary: #f9fafb;
  --embed-text: #111827;
  --embed-text-secondary: #6b7280;
  --embed-text-muted: #9ca3af;
  --embed-border: #e5e7eb;
  --embed-input-bg: #ffffff;
  --embed-accent: #3b82f6;
  --embed-radius: 8px;
}

/* Example: Custom submit button */
.submitButton {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  font-weight: 700;
  text-transform: uppercase;
  letter-spacing: 1px;
}

/* Example: Custom field styling */
.field input,
.field textarea {
  border-width: 2px;
  font-size: 16px;
}
⚠️
CORS Required

Your CSS file must be served with CORS headers allowing cross-origin requests, or hosted on the same domain as your website.

JavaScript Events

Listen for form events using postMessage:

JavaScript
window.addEventListener('message', (event) => {
  // Form submitted successfully
  if (event.data.type === 'townhall:submit') {
    console.log('Form submitted!', {
      formId: event.data.formId,
      submissionId: event.data.submissionId,
      data: event.data.data
    });
    
    // Track conversion
    gtag('event', 'form_submission', {
      form_id: event.data.formId
    });
  }
  
  // Form requested a redirect
  if (event.data.type === 'townhall:redirect') {
    window.location.href = event.data.url;
  }
  
  // Form height changed (for iframe resizing)
  if (event.data.type === 'townhall:resize') {
    const iframe = document.querySelector('iframe');
    if (iframe) {
      iframe.style.height = event.data.height + 'px';
    }
  }
});

Examples

Contact Form with Dark Theme

HTML
<script 
  src="https://townhall.gg/embed.js" 
  data-form-id="YOUR_FORM_ID"
  data-type="inline"
  data-theme="dark"
  data-accent="22c55e"
></script>

Floating Support Widget

HTML
<script 
  src="https://townhall.gg/embed.js" 
  data-form-id="YOUR_FORM_ID"
  data-type="floating"
  data-position="bottom-right"
  data-button-text="💬 Need Help?"
  data-theme="auto"
></script>

Newsletter Signup Popup

HTML
<!-- Trigger button -->
<button onclick="openNewsletterForm()">Subscribe to Newsletter</button>

<script src="https://townhall.gg/embed.js" 
  id="newsletter-form"
  data-form-id="YOUR_FORM_ID"
  data-type="popup"
  data-theme="light"
  data-hide-branding="true"
></script>