@formcentric/client-react

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

What it does

• exposes Formcentric SDK mounting via a React component API
• serializes mount/teardown lifecycle internally
• keeps React callbacks (onReady, onError) current across rerenders

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 React 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 React component.

Avoid:

• expecting most prop changes to update the running form automatically
• changing init-time props without also changing remountKey
• using a changing React 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

• All Formcentric mount config keys are available as top-level props.
• containerProps controls the wrapper <div> attributes/events (className, style, id, aria-*, etc.).
• skipThemeLoad and skipTemplatesLoad 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.

Global defaults

Use FormcentricConfigProvider to provide subtree-wide defaults. Per-form props still win.

import { FormcentricConfigProvider, FormcentricForm } from '@formcentric/client-react'

export function Example() {
    return (
        <FormcentricConfigProvider
            value={{
                srcUrl: 'https://form.formcentric.dev',
                requestHeaders: {
                    'X-App': 'react-app',
                },
            }}
        >
            <FormcentricForm
                embedId="your-embed-id"
                requestHeaders={{ 'X-Form': 'contact' }}
            />
        </FormcentricConfigProvider>
    )
}

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

onReady

onReady 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)

import { useMemo, useState } from 'react'
import { FormcentricForm } from '@formcentric/client-react'
import './formcentric-theme/styles.css'
import './formcentric-theme/script.js'
import themeVariables from './formcentric-theme/_variables.json'

export function Example() {
    const [language, setLanguage] = useState('en')
    const [remountKey, setRemountKey] = useState(0)

    const resolvedThemeVariables = useMemo(() => (themeVariables || {}) as Record<string, unknown>, [])

    return (
        <>
            <button
                onClick={() => {
                    setLanguage(prev => (prev === 'en' ? 'de' : 'en'))
                    setRemountKey(prev => prev + 1)
                }}
            >
                Toggle language
            </button>

            <FormcentricForm
                remountKey={remountKey}
                embedId='your-embed-id'
                srcUrl='https://form.formcentric.dev'
                language={language}
                themeVariables={resolvedThemeVariables}
                containerProps={{ style: { minHeight: 400 } }}
            />
        </>
    )
}