@formcentric/client-vue

Vue component wrapper for the Formcentric SDK with safer lifecycle handling.

What it does

• exposes Formcentric SDK mounting via a Vue component API
• serializes mount/teardown lifecycle internally
• emits Vue events (ready, error)

Further information

For further Formcentric Client integration and development topics, see:

• Formcentric Developer Documentation

Themes

This package does not include a theme.

Use your own bundled theme assets (CSS + template script + variables) or runtime theme URLs.
For theme development/customization, see the Formcentric theme workspace:

• theme-customisation-workspace

Important semantics

This is a restart-based bridge, not a fully controlled Vue widget.

• Most Formcentric config props are init-time props.
• Changing them does not automatically update the running form.
• Reinitialize explicitly by changing remountKey.

Current built-in restart triggers:

• remountKey
• embedId
• formDefinition
• data-fc-watch is legacy-only and is ignored for SDK/component mounts
• if you rely on instance handoff semantics such as conflictBehavior='stop-existing', keep embedId stable

Warning (Framework semantics)

This package exposes a framework component API, but the embedded form runtime is still restart-based.

Treat it as an integration bridge, not like a native fully controlled Vue component.

Avoid:

• expecting most prop changes to update the running form automatically
• changing init-time props without also changing remountKey
• using a changing framework/component key on FormcentricForm to force reloads (use remountKey instead)
• passing fresh config objects every render and assuming they will be applied live
• rapidly unmounting/remounting the component subtree as part of unrelated UI state changes, if form continuity matters

Props / Events

• All Formcentric mount config keys are available as top-level props (except onReady and onError, which are exposed as Vue events).
• Use normal Vue attributes (class, style, id, aria-*, etc.) on the component to control the wrapper <div>.
• skip-theme-load and skip-templates-load are optional and are only applied when explicitly set.
• If your app bundles theme CSS/templates itself, set both to true to skip runtime design/theme loading.
• Events:
  • @ready
  • @error

Global defaults

Use provideFormcentricConfig(...) for subtree-wide defaults. Per-form props still win.

<script setup lang="ts">
import { provideFormcentricConfig, FormcentricForm } from '@formcentric/client-vue'

provideFormcentricConfig({
  srcUrl: 'https://form.formcentric.dev',
  requestHeaders: {
    'X-App': 'vue-app',
  },
})
</script>

<template>
  <FormcentricForm
    embed-id="your-embed-id"
    :request-headers="{ 'X-Form': 'contact' }"
  />
</template>

For non-Vue browser-global defaults, use configure(...) from @formcentric/client.

onReady / @ready

@ready fires after Formcentric initialization has completed successfully (runtime/assets/request/init flow finished and formapp.start(...) was called).

It does not guarantee a dedicated "first visible render" signal from Formapp.

Example (Local Theme Bundle)

<script setup lang="ts">
import { ref } from 'vue'
import { FormcentricForm } from '@formcentric/client-vue'
import './formcentric-theme/styles.css'
import './formcentric-theme/script.js'
import themeVariables from './formcentric-theme/_variables.json'

const language = ref('en')
const remountKey = ref(0)
const resolvedThemeVariables = (themeVariables || {}) as Record<string, unknown>

const toggleLanguage = () => {
  language.value = language.value === 'en' ? 'de' : 'en'
  remountKey.value += 1
}

const onReady = () => {
  // ready
}

const onError = (error: Error) => {
  console.error(error)
}
</script>

<template>
  <button @click="toggleLanguage">Toggle language</button>

  <FormcentricForm
    :remount-key="remountKey"
    embed-id="your-embed-id"
    src-url="https://form.formcentric.dev"
    :language="language"
    :theme-variables="resolvedThemeVariables"
    :style="{ minHeight: '400px' }"
    @ready="onReady"
    @error="onError"
  />
</template>