@formvue/embed-react

React components for embedding FormVue lead-capture widgets in any modern React application — Next.js, Vite, TanStack Start, Remix, Astro, Gatsby.

Each component renders a Preact widget inside a Shadow DOM so styles, scripts, and DOM events stay fully isolated from the host page. The widget collects a visitor's phone number and triggers a personalized SMS link to a FormVue video form.

Table of contents

• Install
• Quick start
• Components
  • <FormVueInline />
  • <FormVueModal />
  • <FormVueContact />
  • <FormVueContent />
• Props reference
• Callbacks
• TypeScript
• Framework guides
  • Next.js (App Router)
  • Next.js (Pages Router)
  • Vite + React
  • TanStack Start
  • Remix
• Vanilla HTML / CDN bundles
• Content Security Policy
• SSR safety
• Bundle size
• Browser support
• License

Install

pnpm add @formvue/embed-react
# or
npm install @formvue/embed-react
# or
yarn add @formvue/embed-react

Peer dependencies:

• react@^18 || ^19
• react-dom@^18 || ^19

The Preact runtime and all internal helpers (signals, formisch, valibot, openapi-fetch) are bundled inside the package — you don't need to install them.

Quick start

'use client';
import { FormVueModal } from '@formvue/embed-react';

export function Header() {
  return (
    <FormVueModal
      formId="your-form-id"
      id="your-button-id"
    />
  );
}

That's it. The component mounts a Preact-powered trigger button. Clicking it opens a modal containing the FormVue form with phone-number capture, validation, and submission baked in.

Components

The package exposes four components — one per widget mode. They share the same prop shape (extending the corresponding FormVueXxxOptions interface) and lifecycle pattern (useEffect mount → Preact render → cleanup on unmount).

<FormVueInline />

Animated inline button that expands into a phone-number input.

[ Start Your Free Estimate ▶ ]   →   [ +1 (___) ___-____ ▶ ]

Behavior:

• State machine: button → input → submitting → success / error
• CSS transitions on flex, opacity, and transform
• Mobile fallback renders a simple <a> link instead of the interactive widget (screen size + pointer/hover capability detection)

'use client';
import { FormVueInline } from '@formvue/embed-react';

export function CTA() {
  return (
    <FormVueInline
      formId="your-form-id"
      variant="primary"
      size="lg"
      text="Get a free quote"
      label="Trusted by 10,000+ homeowners:"
      onSuccess={(data) => console.log('Submitted!', data)}
    />
  );
}

<FormVueModal />

Trigger button that opens a Shadow-DOM-isolated modal overlay containing the full embed form.

Behavior:

• Trigger button uses the same variants/styling as <FormVueInline />
• Modal is mounted on document.body in its own Shadow DOM (avoids z-index stacking issues with the host page)
• Form fields are built dynamically from your FormVue embed config (text, email, phone, number, textarea, select, radio, checkbox)
• Mobile: opens the form in the same tab via deep link (configurable)

'use client';
import { FormVueModal } from '@formvue/embed-react';

export function NavbarCTA() {
  return (
    <FormVueModal
      formId="your-form-id"
      id="your-embed-id"
      text="Open Video Form"
      label="Complete from your phone:"
    />
  );
}

<FormVueContact />

Embedded form rendered directly without a trigger button — ideal for contact pages and dedicated form sections.

Behavior:

• Same dynamic field rendering as <FormVueModal />
• No trigger / no modal — form is always visible
• Skeleton state during config fetch

'use client';
import { FormVueContact } from '@formvue/embed-react';

export function ContactPage() {
  return (
    <section>
      <h1>Get in touch</h1>
      <FormVueContact
        formId="your-form-id"
        id="your-embed-id"
        onSuccess={(data) => console.log('Submitted!', data)}
      />
    </section>
  );
}

<FormVueContent />

Embedded form with a coupon screen shown after submission and before the SMS is sent. Use when you want to incentivize completion with a discount code, promo offer, or printable voucher.

Behavior:

• Contact form → coupon screen → SMS submission
• Coupon copy (headline, offer, ctaLabel, subtext) configured per embed in FormVue dashboard
• Same dynamic fields as Contact

'use client';
import { FormVueContent } from '@formvue/embed-react';

export function PromoSection() {
  return (
    <FormVueContent
      formId="your-form-id"
      id="your-embed-id"
    />
  );
}

Props reference

Common to all components

| Prop | Type | Default | Description | |---|---|---|---| | formId | string | — | Required. FormVue form UUID. | | id | string | — | Embed config ID (required for Modal / Contact / Content). | | locale | string | 'en-US' | Locale for phone formatting and validation. | | attribution | Attribution | — | UTM parameters and campaign attribution. | | mobileNewTab | boolean | mode-dependent | Whether the mobile form link opens in a new tab. | | className | string | — | Class applied to the host <div> (not the Shadow DOM content). | | style | React.CSSProperties | — | Inline styles applied to the host <div>. | | onSubmit | (phone: string) => void | — | Fires when the user submits a phone number. | | onSuccess | (data: FormLinkResponse) => void | — | Fires after the API returns a successful form-link creation. | | onError | (err: Error) => void | — | Fires on any submission error (network, validation, API). |

Button styling (Inline + Modal)

| Prop | Type | Default | Description | |---|---|---|---| | variant | 'default' \| 'primary' \| 'outline' | 'default' | Button layout. default has a body + logo overlay on the right; primary puts the logo on the left; outline is primary with a light border. | | size | 'sm' \| 'md' \| 'lg' | 'md' | Preset dimensions (see size presets). | | text | string | 'Start Your Free Estimate' | Button label. | | label | string | 'Get Faster Quotes With Video:' | Caption shown above the button. | | width | 'auto' \| 'full' | 'auto' | Whether the button fills its container width. | | height | number | from size preset | Override button height in pixels. | | fontSize | number | from size preset | Button text size in pixels. | | borderRadius | number | from size preset | Corner radius in pixels (set to height / 2 for a pill). | | glass | boolean | false | Adds a translucent backdrop-blur background — pair with colors.label = '#fff' over dark backgrounds. | | buttonBorder | string | 'none' | CSS border shorthand applied to the button (e.g. '1px solid #ccc'). | | colors | Colors | see color defaults | Per-element colors. | | inputBorder | string (Inline only) | 'none' | CSS border on the expanded phone input. |

CallRail attribution capture

Sites with CallRail Form Tracking can opt in to FormVue's supported browser bridge:

<FormVueContact
  formId="your-form-id"
  id="your-embed-id"
  attribution={{
    callrail: { enabled: true },
  }}
/>

After FormVue creates the FormLink, the SDK calls CallRail's documented window.CallTrk.captureForm(...) API with a temporary standard HTML form. The form contains the visitor's actual name, phone, and email values plus a hidden formvue_capture_id. The FormLink stores the matching correlation data as:

{
  "callrail": {
    "schemaVersion": 1,
    "captureId": "c3dfd6f0-5ff6-4bc2-a25a-023e9f30d587",
    "status": "pending"
  }
}

Your CallRail form-submission webhook can use formvue_capture_id to associate CallRail's attribution with the FormVue lead. CallRail absence, blocking, exceptions, and callback timeouts never fail the FormVue submission. When the integration is enabled, callrail is a reserved metadata namespace; a page query parameter with that name is not forwarded.

This capture works for Contact and Content embeds on all devices and for the desktop Inline and Modal widgets. Inline and Modal render a direct FormVue link on mobile and do not collect contact information on the host page, so those two mobile fallbacks cannot be captured by CallRail. The bridge does not read or depend on CallRail cookies.

Size presets

| Preset | height | fontSize | borderRadius | logoSize | |---|---|---|---|---| | sm | 36 | 13 | 8 | 24 | | md | 44 | 16 | 10 | 32 | | lg | 52 | 18 | 12 | 36 |

Color defaults

| Key | Default | Used for | |---|---|---| | button | #007145 | Button background | | buttonText | #FFFFFF | Button text | | logo | #5A5A5A | Logo background | | logoIcon | #FFFFFF | Logo icon | | label | #5A5A5A | Caption above the button |

<FormVueInline
  formId="..."
  colors={{
    button: '#2563eb',
    buttonText: '#ffffff',
    logo: '#1e40af',
    logoIcon: '#ffffff',
    label: '#374151',
  }}
/>

Callbacks

All four components accept onSubmit, onSuccess, and onError. They're stable across re-renders — the wrapper uses useStableCallbacks so updates don't tear down the Preact tree.

<FormVueModal
  formId="..."
  id="..."
  onSubmit={(phone) => {
    // Fires before the API request
    console.log('Submitting:', phone);
  }}
  onSuccess={(data) => {
    // Fires after the form-link is created
    // data.id is the FormLink UUID
    analytics.track('lead_captured', { formLinkId: data.id });
  }}
  onError={(err) => {
    // Fires on network failure, validation error, or API error
    Sentry.captureException(err);
  }}
/>

TypeScript

The package ships full TypeScript declarations. All props are typed; auto-complete shows every option in your editor.

import type {
  FormVueInlineOptions,
  FormVueModalOptions,
  FormVueContactOptions,
  FormVueContentOptions,
} from '@formvue/embed-react';

// Build helper functions that wrap our types
function makeButtonProps(formId: string): FormVueInlineOptions {
  return {
    formId,
    variant: 'primary',
    size: 'lg',
  };
}

Framework guides

Next.js (App Router)

The package preserves the "use client" directive on its ESM chunk, so Next.js treats the import boundary as a Client Component automatically — no transpilePackages needed.

// app/contact/page.tsx
import { FormVueModal } from '@formvue/embed-react';

export default function ContactPage() {
  return (
    <main>
      <h1>Get a quote</h1>
      <FormVueModal formId="..." id="..." />
    </main>
  );
}

If you want the form to render conditionally inside a Server Component:

// app/page.tsx (Server Component)
import dynamic from 'next/dynamic';

const FormVueModal = dynamic(
  () => import('@formvue/embed-react').then((m) => m.FormVueModal),
  { ssr: false }
);

export default function Page() {
  return <FormVueModal formId="..." id="..." />;
}

Next.js (Pages Router)

Works the same way. If you're on Next < 13.1, add the package to transpilePackages in next.config.js:

module.exports = {
  transpilePackages: ['@formvue/embed-react'],
};

Vite + React

No setup required — just import and render.

// src/App.tsx
import { FormVueInline } from '@formvue/embed-react';

export default function App() {
  return <FormVueInline formId="..." />;
}

TanStack Start

Treat the components as client-side; mount inside a route component.

// app/routes/contact.tsx
import { createFileRoute } from '@tanstack/react-router';
import { FormVueContact } from '@formvue/embed-react';

export const Route = createFileRoute('/contact')({
  component: ContactPage,
});

function ContactPage() {
  return <FormVueContact formId="..." id="..." />;
}

Remix

// app/routes/contact.tsx
import { ClientOnly } from 'remix-utils/client-only';
import { FormVueModal } from '@formvue/embed-react';

export default function Contact() {
  return (
    <ClientOnly fallback={<div style={{ height: 44 }} />}>
      {() => <FormVueModal formId="..." id="..." />}
    </ClientOnly>
  );
}

ClientOnly is optional — the component is SSR-safe — but using it skips the server-rendered empty <div> flash.

Vanilla HTML / CDN bundles

For non-React integrations (WordPress, Webflow, plain HTML, static sites), use the CDN bundles instead. They're fully bundled IIFE scripts that expose mode-specific globals.

<div id="formvue-btn"></div>
<script src="https://cdn.formvue.com/v1/formvue-modal.js"></script>
<script>
  FormVueModal.button('#formvue-btn', {
    formId: 'your-form-id',
    id: 'your-embed-id',
  });
</script>

Available bundles:

| URL | Global | Method | |---|---|---| | cdn.formvue.com/v1/formvue-inline.js | window.FormVueInline | .button(target, options) | | cdn.formvue.com/v1/formvue-modal.js | window.FormVueModal | .button(target, options) | | cdn.formvue.com/v1/formvue-contact.js | window.FormVueContact | .render(target, options) | | cdn.formvue.com/v1/formvue-content.js | window.FormVueContent | .render(target, options) |

All globals also expose .destroy(target) and .update(target, options) for programmatic teardown / re-render.

Content Security Policy

The widget injects a <style> tag inside its Shadow DOM at mount time (Tailwind CSS). Sites with strict CSP need to allow style-src 'unsafe-inline' on the host page for the styles to apply.

Content-Security-Policy: style-src 'self' 'unsafe-inline'; script-src 'self' https://cdn.formvue.com;

A nonce-based mechanism is on the roadmap.

SSR safety

All components are safe to import from Server Components and SSR runtimes:

• The wrapper renders a plain <div ref> on the server — no DOM access.
• All widget mounting happens inside useEffect, which runs only on the client.
• The internal SDK guards window access with typeof window !== 'undefined' checks.
• Strict Mode double-mount is handled — useEffect cleanup tears down the Shadow DOM and re-mounts cleanly.

Bundle size

| Build | Size | Gzipped | |---|---|---| | dist/index.js (npm ESM) | ~220 KB | ~55 KB | | dist/cdn/formvue-inline.js (CDN IIFE) | ~62 KB | ~19 KB | | dist/cdn/formvue-modal.js (CDN IIFE) | ~102 KB | ~30 KB | | dist/cdn/formvue-contact.js (CDN IIFE) | ~94 KB | ~28 KB | | dist/cdn/formvue-content.js (CDN IIFE) | ~96 KB | ~29 KB |

The npm bundle ships all four components in one ESM module so tree-shaking is automatic — importing only FormVueInline won't drag in Modal / Contact / Content widget code (most of it; some shared chunks like config resolution are always included).

Browser support

• Chrome / Edge ≥ 90
• Safari ≥ 14
• Firefox ≥ 88
• Mobile Safari ≥ 14
• Chrome for Android ≥ 90

Requires native Shadow DOM (no polyfill). All modern browsers from 2021 onward.

License

MIT © FormVue