Widget Embed Guide

Add powerful, production-ready widgets to any website with just two lines of code. All widgets are fully responsive and work on any platform.

Quick Start

The fastest way to get started is to add the widget container and load our CDN script:

<!-- Add the widget container -->
<div id="qt-portal-estimate"
  data-widget="estimate"
  data-tenant="YOUR_TENANT_ID"
  data-container="qt-portal-estimate"
  data-display-mode="button">
</div>

<!-- Load the widget script (single script for all widgets) -->
<script type="module" 
  src="https://cdn.widgetfied.com/portal.js">
</script>

Replace YOUR_TENANT_ID with your actual tenant ID from the dashboard

The script automatically initializes all widget containers on the page

You can add multiple widgets - they all share the same script

Available Widgets

AI Estimates Widget

AI-powered estimates using computer vision. Customers upload photos and receive instant quotes.

Photo upload & compressionAI-powered analysisInstant pricingEmail notifications

Booking Widget

Full-featured booking system with Google Calendar integration and real-time availability.

Google Calendar syncTime zone handlingDeposit collectionEmail confirmations

Customer Portal Widget

Self-service customer portal for job tracking, document uploads, and payment history.

Job status trackingDocument uploadsPayment historyReal-time updates

Payment Widget

Secure payment processing with Stripe integration, tipping, and Venmo support.

Stripe integrationDynamic tippingFee handlingVenmo support

Multiple Widgets on One Page

You can embed multiple widgets on the same page. Each widget needs its own container with a unique ID:

<!-- AI Estimates Widget (button mode) -->
<div id="qt-portal-estimate"
  data-widget="estimate"
  data-tenant="YOUR_TENANT_ID"
  data-container="qt-portal-estimate"
  data-display-mode="button">
</div>

<!-- Booking Widget (button mode) -->
<div id="qt-portal-booking"
  data-widget="booking"
  data-tenant="YOUR_TENANT_ID"
  data-container="qt-portal-booking"
  data-display-mode="button">
</div>

<!-- Customer Portal with Payment enabled -->
<div id="qt-portal-jobportal"
  data-widget="jobportal"
  data-tenant="YOUR_TENANT_ID"
  data-container="qt-portal-jobportal"
  data-display-mode="button"
  data-payment-enabled="true"
  data-payment-widget="qtPortalPayment">
</div>

<!-- Payment Widget (for Customer Portal integration) -->
<div id="qt-portal-payment"
  data-widget="payment"
  data-tenant="YOUR_TENANT_ID"
  data-container="qt-portal-payment"
  data-global-name="qtPortalPayment">
</div>

<!-- Single script initializes ALL widgets -->
<script type="module" 
  src="https://cdn.widgetfied.com/portal.js">
</script>

Display Modes

Control how widgets render using the data-display-mode attribute:

inline(default)

Widget renders directly inside the container element. Subject to parent CSS (overflow, transforms, etc.).

buttonRecommended

Shows a trigger button. When clicked, opens the widget as a fullscreen modal overlay that escapes CSS constraints.

modal

Widget is hidden until triggered programmatically. Opens as fullscreen overlay at document root level.

<!-- Button mode (recommended) - shows button, opens modal on click -->
<div id="qt-portal-booking"
  data-widget="booking"
  data-tenant="YOUR_TENANT_ID"
  data-container="qt-portal-booking"
  data-display-mode="button">
</div>

<!-- Inline mode - renders directly in the container -->
<div id="qt-portal-booking"
  data-widget="booking"
  data-tenant="YOUR_TENANT_ID"
  data-container="qt-portal-booking"
  data-display-mode="inline">
</div>

<!-- Modal mode - hidden until triggered programmatically -->
<div id="qt-portal-booking"
  data-widget="booking"
  data-tenant="YOUR_TENANT_ID"
  data-container="qt-portal-booking"
  data-display-mode="modal">
</div>

Use button or modal mode when embedding on sites with deep nesting (10+ layers), overflow: hidden, transform, or backdrop-filter CSS properties. These modes use React portals to render at the document root, escaping any CSS containing blocks.

Common Attributes Reference

These attributes work with all widget types:

Attribute	Required	Description	Example
`data-widget`		Widget type to render	`booking \| estimate \| jobportal \| payment`
`data-tenant`		Your tenant ID from the Widgetfied dashboard	`YOUR_TENANT_ID`
`data-container`	Optional	Container element ID (defaults to "qt-portal")	`qt-portal-booking`
`data-display-mode`	Optional	How the widget displays: inline, button, or modal	`button (recommended)`
`data-global-name`	Optional	Custom global variable name for multiple instances	`qtPortalPayment`

Payment Widget Attributes

Additional attributes for the Payment Widget (Stripe Connect):

Attribute	Required	Description	Example
`data-platform-api-url`	Optional	Platform API URL for Stripe Connect	`https://api.widgetfied.com`
`data-success-url`	Optional	Custom redirect URL after successful payment	`https://yoursite.com/thank-you`
`data-cancel-url`	Optional	Custom redirect URL if payment is cancelled	`https://yoursite.com/cancelled`
`data-platform-fee-percent`	Optional	Platform fee percentage (default: 0 - no fees)	`0`

Customer Portal Attributes

Additional attributes for the Customer Portal Widget:

Attribute	Required	Description	Example
`data-payment-enabled`	Optional	Enable payment functionality within the portal	`true \| false`
`data-payment-widget`	Optional	Global name of the payment widget to use (requires matching data-global-name on Payment Widget)	`qtPortalPayment`

Finding Your Tenant ID

1
Log in to your Widgetfied Dashboard (you'll receive login details after signing up)
2
Navigate to Settings in the sidebar
3
Your Tenant ID is displayed at the top of the page
4
Copy the ID and use it in your widget embed code

Platform Integration Guides

Our widgets work on any platform that supports custom HTML. Here are quick guides for popular platforms:

WordPress

Add a Custom HTML block and paste the embed code

Webflow

Use an Embed element in the designer

Squarespace

Add a Code Block and paste the embed code

Wix

Use the HTML iframe or Embed element

Shopify

Add Custom Liquid section with the embed code

React/Next.js

Use dangerouslySetInnerHTML or a custom component

Styling & Customization

Widgets automatically adapt to your site's design using your white-label settings. You can customize:

Primary colors and accent colors
Logo and business branding
Button styles and fonts
Email templates and messaging

Configure these settings in your Dashboard under Settings → White Label

Troubleshooting

Widget not appearing

• Verify your Tenant ID is correct
• Check that the container has all required data attributes
• Ensure the script tag has type="module"
• Check browser console for JavaScript errors

Modal/overlay is clipped or hidden

• Use data-display-mode="button" instead of "inline"
• Check if parent containers have overflow: hidden, transform, or backdrop-filter
• Button/modal modes use React portals to escape CSS constraints
• Ensure the widget container is not inside a deeply nested element (10+ layers)

Widget shows error message

• Verify your account is active and subscription is current
• Check that the domain is whitelisted in your settings
• Ensure all required integrations (Google Sheets, etc.) are configured

Payment not working in Customer Portal

• Add data-payment-enabled="true" to the Customer Portal widget
• Add a Payment Widget with a matching data-global-name
• Reference the payment widget using data-payment-widget on the portal

Styling looks wrong

• Check for CSS conflicts with your site styles
• Verify white-label settings are configured
• Try adding the widget in an isolated container

Next Steps

Configure Google Sheets for data sync Set up Google Calendar for bookings Get started with Widgetfied