React Applications

Integrating the Enterprise Form Builder Module in a React application.

Within a React application, the Enterprise Form Builder Moduler provides a suite of components and hooks that enable form building within an application while using the enterprise features available in Form.io.

In keeping with React application building conventions, it is a collection of components and does not utilize any third party routing or state management. Those capabililites remain in the domain of the application using the components.

All of the core interaction with the Form.io server is separated into hooks, so they can be used independent of the the UI components provided.

To begin using the Enterprise Form Builder Module within a React application, complete the following steps:

Installation

To install the React Enterprise Form Builder package, use the following command:

npm install @formio/enterprise-form-builder-react

Required Peer Dependencies

This package relies on both @formio/react and @formio/js as peer dependencies. They must be installed in the project if they are not already present:

npm install @formio/react @formio/js

Make sure the versions of @formio/react and @formio/js meet the minimum requirements specified in the package's peerDependencies.

Setup

To use the Enterprise Form Builder in a React app, configure the required context providers at the top level of the application, just as in the react-efb-demo app.

The EnterpriseFormBuilderProvider must be a child of the FormioProvider in the application's component tree. Configure the Formio library with the license key and any additional client libraries.

Here is a minimal example of how to wrap an application:

import React from 'react';
import { EnterpriseFormBuilderProvider } from '@formio/enterprise-form-builder-react';
import { FormioProvider } from '@formio/react';

const licenseKey = 'YOUR_ENTERPRISE_LICENSE_KEY'; // Replace with your license key

function App() {
  return (
    <FormioProvider
      projectUrl="https://your-project.form.io"   // <-- Change to your Form.io project URL
      baseUrl="https://your-domain.form.io"        // <-- Change to your Form.io base URL
    >
      <EnterpriseFormBuilderProvider licenseKey={licenseKey} tag="common">
        {/* Your app content and routing here */}
      </EnterpriseFormBuilderProvider>
    </FormioProvider>
  );
}

export default App;

Notes:

• The FormioProvider sets up Form.io project context for all children.
• The EnterpriseFormBuilderProvider enables the enterprise builder features and requires a valid license key.
• The tag prop is used to group forms that are available to the Enterprise Form Builder. New forms will be added with this tag and only Forms with the tag will be displayed.
• Wrap your app's router or main content with these providers.

User Authentication

User authentication is required to support form management within a project.

These steps will configure the project to have a User role that will manage the forms:

1. From the Developer Portal, open the associated project.
2. Navigate to Access, then click New Role under the list of existing Project Roles.
3. Enter the title Form Builder and click Create Role. The screen should return to the Access page.

Refer to Roles documentation for additional information.

1. On the Access page, add the Form Builder role to the following Permission groups:

   1. Create All
   2. Read All
   3. Update All
   4. Delete All

1. Configure the Project to add these roles to the authenticated users group. Do this using the SSO configurations, or using Form.io Authentication. Either option requires modifying the User Login form to enable this authentication.

Once the Form.io project is appropriately configured, configure authentication within the host application. The documentation for setting up Authentication within an Angular application can be found at the Angular Authentication Documentation.

With this route in place, application users can authenticate into the app and subsequently be authenticated into the Form.io Project with the appropriate privileges.

Error Handling

There are two ways to handle errors that come from the Enterprise Form Builder components:

• Each component has an onError callback function to allow you to handle the error as needed.
• If the onError callback is not provided, the error will be thrown. This allows you to use a global error handler such as a React Error Boundary to catch and handle errors in your application.

Providers

The EnterpriseFormBuilderProvider is the context provider for enterprise form builder functionality. Refer to the React Context Providerreference for more information.

Components

The following components are available within React apps. Refer to the React Component Reference for more detailed information.

• CreateForms - Visual form builder interface for creating and editing forms
• FormList - Display and manage a list of forms with filtering
• FormViewer - Display a form for users to fill out and submit
• UseForm - Display a form with an existing submission for viewing or editing
• SubmissionList - Display a table of submissions for a form
• SubmissionViewer - View, edit, or delete a submission
• FormDelete - Confirmation dialog for deleting a form
• DeleteSubmission - Confirmation dialog for deleting a submission
• FormSettings - Edit form metadata (title, name, path, tags)

Hooks

All hooks provided by the Enterprise Form Builder follow a consistent pattern: each hook returns an action function (such as loadForm, saveForm, deleteForm, etc.) that performs the associated operation, along with state properties that allow you to track the progress and result of the operation. These state properties typically include:

• loading: boolean — Indicates if the operation is currently in progress.
• error: string | null — Holds any error message if the operation fails, otherwise null.
• success: boolean — (For actions such as save or delete) Indicates if the operation was successful.
• Data property: The returned data from the operation, if applicable (such as form, forms, submission, etc.).

This pattern allows you to call the action function as needed (for example, in response to a button click or effect), and use the returned state properties in your component’s UI to provide feedback, handle errors, or display loading indicators.

The list of available hooks are listed below. Refer to the React Hooks Reference for more information:

• useEnterpriseFormBuilder - Access the enterprise form builder context
• useLoadForm - Load a single form by ID
• useLoadForms - Load multiple forms with optional query parameters
• useSaveForm - Save forms with optional conflict resolution
• useDeleteForm - Delete a form by ID
• useLoadSubmission - Load a single submission by form ID and submission ID
• useSaveSubmission - Save a submission
• useDeleteSubmission - Delete a submission
• useLoadProject - Load Form.io project information