Web Component

Embed FormWork forms on any website using the web component.

FormWork provides a web component for embedding forms on any website. The <formwork-form> element makes integration simple and flexible.

Quick Start

Add the script and component to your HTML:

<!-- Include the FormWork embed script -->
<script src="https://app.formwork.io/embed.js"></script>

<!-- Add the form component -->
<formwork-form
  form-id="your-form-id"
  api-base-url="https://app.formwork.io"
></formwork-form>

Attributes

Required Attributes

Optional Attributes

Entry Management

New Entry Each Load

Default behavior - creates a fresh entry:

<formwork-form
  form-id="abc123"
  api-base-url="https://app.formwork.io"
></formwork-form>

Resume Existing Entry

Pass an entry key to continue a saved entry:

<formwork-form
  form-id="abc123"
  api-base-url="https://app.formwork.io"
  entry-key="xyz789"
></formwork-form>

Entry Key from URL

Read entry key from URL parameters:

const urlParams = new URLSearchParams(window.location.search);
const entryKey = urlParams.get('entry');

const form = document.querySelector('formwork-form');
if (entryKey) {
  form.setAttribute('entry-key', entryKey);
}

Theme Options

Light Theme

<formwork-form theme="light" ...></formwork-form>

Dark Theme

<formwork-form theme="dark" ...></formwork-form>

Auto (System Preference)

<formwork-form theme="auto" ...></formwork-form>

Uses the user’s system color scheme preference.

Events

The component emits events for form lifecycle:

Form Loaded

document.querySelector('formwork-form')
  .addEventListener('formwork:loaded', (e) => {
    console.log('Form loaded', e.detail);
  });

Form Submitted

document.querySelector('formwork-form')
  .addEventListener('formwork:submitted', (e) => {
    console.log('Form submitted', e.detail.entryId);
    // Redirect or show success
  });

Validation Error

document.querySelector('formwork-form')
  .addEventListener('formwork:validation-error', (e) => {
    console.log('Validation failed', e.detail.errors);
  });

Page Changed

document.querySelector('formwork-form')
  .addEventListener('formwork:page-changed', (e) => {
    console.log('Now on page', e.detail.pageIndex);
  });

JavaScript API

Get Form Reference

const form = document.querySelector('formwork-form');

Get Current Values

const values = form.getValues();
console.log(values); // { name: "John", email: "[email protected]" }

Set Values Programmatically

form.setValues({
  source: 'website',
  campaign: 'summer2024'
});

Submit Programmatically

await form.submit();

Navigate Pages

form.nextPage();
form.previousPage();
form.goToPage(2);

Styling

Container Sizing

The component fills its container:

<div style="max-width: 600px; margin: 0 auto;">
  <formwork-form ...></formwork-form>
</div>

CSS Custom Properties

Override theme values with CSS:

formwork-form {
  --fw-primary: #3b82f6;
  --fw-background: #ffffff;
  --fw-foreground: #0f172a;
  --fw-border-radius: 8px;
}

See Theming for full customization.

Integration Examples

React

import { useEffect, useRef } from 'react';

function FormEmbed({ formId }) {
  const ref = useRef();

  useEffect(() => {
    const form = ref.current;
    const handleSubmit = (e) => {
      console.log('Submitted:', e.detail);
    };
    form.addEventListener('formwork:submitted', handleSubmit);
    return () => form.removeEventListener('formwork:submitted', handleSubmit);
  }, []);

  return (
    <formwork-form
      ref={ref}
      form-id={formId}
      api-base-url="https://app.formwork.io"
    />
  );
}

Vue

<template>
  <formwork-form
    :form-id="formId"
    api-base-url="https://app.formwork.io"
    @formwork:submitted="handleSubmit"
  />
</template>

<script setup>
const props = defineProps(['formId']);
const handleSubmit = (e) => {
  console.log('Submitted:', e.detail);
};
</script>

Next.js

'use client';
import Script from 'next/script';

export default function Form({ formId }) {
  return (
    <>
      <Script src="https://app.formwork.io/embed.js" />
      <formwork-form
        form-id={formId}
        api-base-url="https://app.formwork.io"
      />
    </>
  );
}

Troubleshooting

Form Not Loading

• Verify form-id is correct
• Check api-base-url is accessible
• Ensure form is published
• Check browser console for errors

CORS Errors

• Add your domain to allowed origins in form settings
• Ensure HTTPS if API is HTTPS

Styling Conflicts

• Form uses Shadow DOM to isolate styles
• Override with CSS custom properties
• Check for conflicting global styles