Intermediate6 min

Embedding Widgets

Add interactive widgets to your website or application. Let users trigger workflows and view data.

Widget Types

Form Widgets

Collect data that triggers workflows:

  • Lead capture forms
  • Support request forms
  • Feedback collection
  • Survey forms

Display Widgets

Show workflow data:

  • Status trackers
  • Dashboards
  • Data tables
  • Charts

Action Widgets

Trigger workflows with one click:

  • Submit buttons
  • Approval buttons
  • Quick actions

Creating Embeddable Widgets

From Workflow

  1. Open your workflow
  2. Click Share > Create Widget
  3. Configure widget type
  4. Customize appearance
  5. Get embed code

From Forms

  1. Open your form
  2. Click Embed
  3. Choose embed style
  4. Copy code

Embed Methods

JavaScript Embed

Most flexible option:

<div id="workflow-widget"></div>
<script src="https://embed.yourapp.com/widget.js"></script>
<script>
  WorkflowWidget.create({
    containerId: 'workflow-widget',
    widgetId: 'your-widget-id',
    apiKey: 'your-public-key'
  });
</script>

iFrame Embed

Simple but limited:

<iframe
  src="https://embed.yourapp.com/widget/your-widget-id"
  width="400"
  height="600"
  frameborder="0">
</iframe>

React/Vue Components

For JavaScript apps:

// React
import { WorkflowWidget } from '@yourapp/widgets-react';

<WorkflowWidget
  widgetId="your-widget-id"
  apiKey="your-public-key"
  onComplete={(data) => console.log(data)}
/>

<!-- Vue -->
<template>
  <WorkflowWidget
    :widget-id="widgetId"
    :api-key="apiKey"
    @complete="handleComplete"
  />
</template>

Configuration Options

Basic Options

WorkflowWidget.create({
  containerId: 'widget',
  widgetId: 'your-widget-id',
  apiKey: 'your-public-key',

  // Appearance
  theme: 'light',  // light, dark, auto
  width: '100%',
  height: 'auto',
});

Styling Options

WorkflowWidget.create({
  // ... basic options

  style: {
    primaryColor: '#3B82F6',
    borderRadius: '8px',
    fontFamily: 'Inter, sans-serif',
    fontSize: '14px',
  },

  // Or use CSS class
  className: 'my-custom-widget',
});

Behavior Options

WorkflowWidget.create({
  // ... basic options

  behavior: {
    autoFocus: true,
    submitOnEnter: false,
    showProgress: true,
    confirmSubmit: true,
  },
});

Passing Data

Prefill Fields

Pass data to widget:

WorkflowWidget.create({
  // ... options

  prefill: {
    email: 'user@example.com',
    name: 'John Doe',
    plan: 'pro',
  },
});

Hidden Fields

Pass data without displaying:

WorkflowWidget.create({
  // ... options

  hiddenData: {
    source: 'marketing-page',
    campaign: 'spring-2024',
    referrer: document.referrer,
  },
});

Dynamic Data

Update data after init:

const widget = WorkflowWidget.create({ ... });

// Later...
widget.setData({
  userId: getCurrentUserId(),
});

Events

Available Events

WorkflowWidget.create({
  // ... options

  onReady: () => {
    console.log('Widget loaded');
  },

  onSubmit: (data) => {
    console.log('Form submitted:', data);
  },

  onComplete: (result) => {
    console.log('Workflow completed:', result);
  },

  onError: (error) => {
    console.error('Error:', error);
  },
});

Event Handling

const widget = WorkflowWidget.create({ ... });

widget.on('complete', (result) => {
  // Show success message
  showNotification('Success!');

  // Redirect
  if (result.redirect) {
    window.location.href = result.redirect;
  }
});

Authentication

Anonymous Widgets

No login required:

WorkflowWidget.create({
  // ... options
  auth: 'none',
});

User Context

Pass user information:

WorkflowWidget.create({
  // ... options

  user: {
    id: 'user-123',
    email: 'user@example.com',
    token: 'user-auth-token',  // If needed
  },
});

Protected Widgets

Require authentication:

WorkflowWidget.create({
  // ... options

  auth: {
    required: true,
    loginUrl: '/login',
    returnUrl: window.location.href,
  },
});

Responsive Design

Auto-Sizing

WorkflowWidget.create({
  // ... options

  responsive: true,
  minWidth: 300,
  maxWidth: 600,
});

Mobile Optimization

WorkflowWidget.create({
  // ... options

  mobile: {
    fullscreen: true,  // Full screen on mobile
    position: 'bottom', // Stick to bottom
  },
});

Security

Domain Restrictions

Limit where widget can load:

  1. Go to widget settings
  2. Add allowed domains
  3. Widget only loads on those domains

Content Security Policy

Add to your CSP:

script-src 'self' https://embed.yourapp.com;
frame-src https://embed.yourapp.com;

Data Validation

All widget data is:

  • Validated server-side
  • Sanitized for XSS
  • Rate limited

Testing

Preview Mode

Test before deploying:

  1. Click Preview in widget editor
  2. Test all functionality
  3. Check responsive behavior

Test on localhost

Widgets work on localhost for testing.

Troubleshooting

Widget Not Loading

  • Check API key
  • Verify domain is allowed
  • Check console for errors
  • Test in incognito mode

Styling Issues

  • Check for CSS conflicts
  • Use more specific selectors
  • Try iframe embed

Data Not Submitting

  • Check required fields
  • Verify workflow is active
  • Check network tab

Next Steps

Tags

embeddingwidgetsintegration