@formvue/embed-astro

Native Astro component for embedding FormVue lead-capture widgets. It needs no React, Preact, Astro renderer integration, or handwritten browser initialization.

Install

pnpm add @formvue/embed-astro

Use

---
import { FormVueEmbed } from "@formvue/embed-astro";
---

<FormVueEmbed formId="your-form-id" />

inline is the default mode. The other FormVue modes use the same component:

<FormVueEmbed mode="modal" formId="your-form-id" id="embed-config-id" />
<FormVueEmbed mode="contact" formId="your-form-id" id="embed-config-id" />
<FormVueEmbed mode="content" formId="your-form-id" id="embed-config-id" />

The component loads the matching production SDK bundle from https://cdn.formvue.com/v1 once per mode per page, mounts it in an isolated Shadow DOM, and destroys it automatically when Astro removes the component. It also works with Astro client-side navigation because each <formvue-embed> instance owns its mount and cleanup lifecycle.

id is required for modal, contact, and content modes. The component rejects a missing or empty identifier during Astro rendering instead of shipping a widget that silently does nothing.

Common options

SDK options are regular component props:

<FormVueEmbed
  formId="your-form-id"
  text="Start Your Free Estimate"
  size="lg"
  width="full"
  attribution={{
    campaignSlug: "auto",
    passQueryParams: true,
  }}
/>

Use sdkBaseUrl="https://cdn.formvue.com/preview" to test preview SDK bundles. Each mode's SDK loads once per page: the first-loaded bundle wins, so a manual CDN <script> tag or a different sdkBaseUrl on another embed of the same mode is reused instead of loading again. When that happens, a console warning reports the requested URL that was ignored. Use fallbackUrl, fallbackText, and minHeight to customize the no-script or SDK-load failure state.

Browser events

The component emits bubbling DOM events so analytics can be added without a UI framework wrapper:

| Event | event.detail | |---|---| | formvue:ready | { formId, mode } | | formvue:submit | { phone } | | formvue:success | { data } | | formvue:error | { error, phase } | | formvue:preview-submit | { payload } |

<FormVueEmbed formId="your-form-id" class="estimate-form" />

<script>
  document.addEventListener("formvue:success", (event) => {
    const { data } = (event as CustomEvent).detail;
    (window as Window & { dataLayer?: unknown[] }).dataLayer?.push({
      event: "formvue_success",
      formVueData: data,
    });
  });
</script>

WordPress shell with Astro content

Place <FormVueEmbed> in the Astro-owned page or shared page template. It does not need to be added to a WordPress header, navigation, or plugin. FormVue's Shadow DOM prevents WordPress theme CSS from changing the widget.

If the site uses a Content Security Policy, allow https://cdn.formvue.com in script-src and the configured FormVue origins in connect-src and img-src.

Agent-assisted installation

This repository includes skills/formvue-astro-install, a portable Agent Skill that can install and verify the package in another Astro repository. Copy that folder to .agents/skills/ for Codex or .claude/skills/ for Claude Code, then ask the agent to install FormVue with the form ID and intended placement.