Last updated:
This article explains how to embed Formcentric forms into a website.
As a first step, install the React component in your project:
If you want to use additional theme resources from the Formcentric client package, you can also install (optional):
If you want to include local SCSS files from a theme, you will also require SASS – e.g. with Vite:
Embedding uses the component FormcentricForm. The configuration is passed using props: data-fc-* attributes and a global initialisation call are not necessary for React integration.
A simple example:
Alongside the props on the individual FormcentricForm, React also supports two other levels for common defaults:
| Source | Scope | Priority | Description |
browser-global defaults via über configure(...) or window.formcentric |
Entire browser page | Low | Read as defaults by the underlying SDK mount |
FormcentricConfigProvider |
React subtree | Medium | Returns subtree-wide defaults for all FormcentricForm components underneath |
Props ON FormcentricForm |
Individual form | High | Override browser globals and provider defaults |
Note the following:
| Topic | Principle |
| Nested providers |
Multiple FormcentricConfigProvider are combined together. Inner providers override outer values. |
| Object values |
requestHeaders, themeVariables and configuration are combined together. If keys are identical, the nearer/local configuration wins. |
| Remount behaviour |
Changes to provider defaults or browser-global defaults do not automatically affect forms already running. For a running instance, remountKey must also be changed or the component must be re-mounted. |
| Static only |
dynamicInit is not a React prop and has no effect in the case of component-based mounts. |
The full list of the common keys and their semantics is given in the main Formcentric Client (General) documentation.
In particular, the following are not envisaged as common defaults: embedId, formDefinition, vars, params, refs, formName, instanceId, conflictBehavior, remountKey, containerProps, onReady and onError.
Example with FormcentricConfigProvider:
For browser-global defaults outside of React-specific code, configure(...) from @formcentric/client can also be used.
Theme resources can be integrated directly into the application as SCSS and JavaScript.
Please note that the application should be configured so that it can use SCSS. With Vite, all you need to do is install SASS:
Following this step, you import the styles for your selected theme into your own index.scss file:
You then import the theme files into your React application:
If you want to pass theme variables directly, you can set these as an extra prop:
The React component is envisaged as an integration bridge and not as a fully controlled React widget. Most props only take effect when the form is initialised.
If configuration values change at runtime, the form should be explicitly re-initialised. The prop remountKey is available for this purpose.
Example:
For simple integration projects, optional callbacks can be used:
onReady: is called after successful initialisationonError:is called after initialisation errors or runtime errorsExample:
onReady signals that the initialisation has been successfully completed. However, this is not a cast-iron guarantee of an “initial visible render timestamp” for the form.
