Awesome

@formio/react

A React library for rendering out forms based on the Form.io platform.

NOTE: The following documentation corresponds to version 6.x of @formio/react, which has not been released yet. For version-specific documentation, please see the relevant tag.

Example Application

To see an example application of how to implement all the components and modules in this library, see https://github.com/formio/react-app-starterkit

Install

npm

npm install @formio/react --save
npm install @formio/js --save

yarn

yarn add @formio/react @formio/js

Hooks

useFormioContext

A hook to supply global Formio contextual values to your React components. Components that call useFormioContext must be children of a <FormioProvider /> component.

Return Value

useFormioContext returns an object with the following parameters:

Examples

Use the authentication context provided by useFormioContext to evaluate the Form.io authentication of a user:

import { createRoot } from 'react-dom/client';
import { useFormioContext, FormGrid, FormioProvider } from '@formio/react';

const App = () => {
	const { isAuthenticated } = useFormioContext();

	return isAuthenticated ? (
		<Router>
			<Route path="/form">
				<FormGrid
					formQuery={{ type: 'form' }}
					onFormClick={(id) => setLocation(`/form/${id}`)}
				/>
			</Route>
			<Route path="/resource">
				<FormGrid
					formQuery={{ type: 'resource' }}
					onFormClick={(id) => setLocation(`/resource/${id}`)}
				/>
			</Route>
		</Router>
	) : (
		<Redirect to="/login" />
	);
};

const domNode = document.getElementById('root');
const root = createRoot(domNode);
root.render(
	<FormioProvider projectUrl="https://examples.form.io">
		<App />
	</FormioProvider>,
);

Use the Form.io SDK to interact with a Form.io server:

import { createRoot } from 'react-dom/client';
import { useEffect, useState } from 'react';
import {
	useFormioContext,
	FormioProvider,
	FormType,
	Form,
} from '@formio/react';

const FormsByUser = ({ userId }: { userId: string }) => {
	const { Formio, projectUrl } = useFormioContext();
	const [forms, setForms] = useState<FormType[]>([]);

	useEffect(() => {
		const fetchForms = async () => {
			const formio = new Formio(projectUrl);
			try {
				const forms = await formio.loadForms({
					params: { type: 'form', owner: userId },
				});
				setForms(forms);
			} catch (err) {
				console.log(
					`Error while loading forms for user ${userId}:`,
					err,
				);
			}
		};
		fetchForms();
	}, [Formio, projectUrl, userId]);

	return forms.map(function (form) {
		return (
			<>
				<Form src={form} />
				<div style={{ marginBottom: '10px' }} />
			</>
		);
	});
};

const domNode = document.getElementById('root');
const root = createRoot(domNode);
const root = createRoot();
root.render(
	<FormioProvider projectUrl="https://examples.form.io">
		<App />
	</FormioProvider>,
);

usePagination

A hook to supply limit/skip server pagination data and methods to your React components. Components that call usePagination must be children of a <FormioProvider /> component.

Props

Return Value

usePagination returns an object with the following parameters:

Examples

Paginate a set of forms:

import { createRoot } from 'react-dom/client';
import { useCallback } from 'react';
import {
	useFormioContext,
	FormioProvider,
	FormType,
	Form,
} from '@formio/react';

const FormsByUser = ({ userId }: { userId: string }) => {
	const { Formio, projectUrl } = useFormioContext();
	const fetchFunction = useCallback(
		(limit: number, skip: number) => {
			const formio = new Formio(`${projectUrl}/form`);
			return formio.loadForms({ params: { type: 'form', limit, skip } });
		},
		[Formio, projectUrl],
	);
	const { data, page, nextPage, prevPage, hasMore } = usePagination<FormType>(
		1,
		10,
		fetchFunction,
	);

	return (
		<div>
			<div>
				{data.map((form) => (
					<>
						<Form src={form} />
						<div style={{ marginBottom: '10px' }} />
					</>
				))}
			</div>
			<ul>
				<li
					onClick={prevPage}
					className={`${page === 1 ? 'disabled' : ''}`}
				>
					Prev
				</li>
				<li
					onClick={nextPage}
					className={`${hasMore ? '' : 'disabled'}`}
				>
					Next
				</li>
			</ul>
		</div>
	);
};

const domNode = document.getElementById('root');
const root = createRoot(domNode);
const root = createRoot();
root.render(
	<FormioProvider projectUrl="https://examples.form.io">
		<App />
	</FormioProvider>,
);

Components

FormioProvider

A React context provider component that is required when using some hooks and components from this library.

Props

Form

A React component wrapper around a Form.io form. Able to take a JSON form definition or a Form.io form URL and render the form in your React application.

Props

Examples

Render a simple form from the Form.io SaaS:

import { createRoot } from 'react-dom/client';
import { Form } from '@formio/react';

const domNode = document.getElementById('root');
const root = createRoot(domNode);

root.render(
	<Form src="https://example.form.io/example" onSubmit={console.log} />,
);

Render a simple form from a JSON form definition:

import { createRoot } from 'react-dom/client';
import { Form } from '@formio/react';

const domNode = document.getElementById('root');
const root = createRoot(domNode);

const formDefinition = {
	type: "form",
	display: "form",
	components: [
		{
			type: "textfield"
			key: "firstName",
			label: "First Name",
			input: true,
		},
		{
			type: "textfield"
			key: "firstName",
			label: "First Name",
			input: true,
		},
		{
			type: "button",
			key: "submit",
			label: "Submit",
			input: true
		}
	]
}

root.render(<Form src={formDefinition} />);

Access the underlying form instance (see here for details):

import { useRef } from 'react';
import { createRoot } from 'react-dom/client';
import { Form } from '@formio/react';

const domNode = document.getElementById('root');
const root = createRoot(domNode);

const formDefinition = {
	type: "form",
	display: "form",
	components: [
		{
			type: "textfield"
			key: "firstName",
			label: "First Name",
			input: true,
		},
		{
			type: "textfield"
			key: "firstName",
			label: "First Name",
			input: true,
		},
		{
			type: "button",
			key: "submit",
			label: "Submit",
			input: true
		}
	]
}

const App = () => {
	const formInstance = useRef(null);

	const handleFormReady = (instance) => {
		formInstance.current = instance;
	}

	const handleClick = () => {
		if (!formInstance.current) {
			console.log("Our form isn't quite ready yet.");
			return;
		}
		formInstance.current.getComponent('firstName')?.setValue('John');
		formInstance.current.getComponent('lastName')?.setValue('Smith');
	}

	return (
		<div>
			<Form src={formDefinition} onFormReady={handleFormReady} />
			<button type="button" onClick={handleClick}>Set Names</button>
		</div>
	);
}

root.render(<App />);

Usage in Next.js

A number of dependencies in the @formio/js rely on web APIs and browser-specific globals like window. Because Next.js includes a server-side rendering stage, this makes it difficult to import the Form component directly, even when used in client components. For this reason, we recommend dynamically importing the Form component using Next.js' dynamic API:

'use client';
import dynamic from 'next/dynamic';
import { Webform } from '@formio/js';

const Form = dynamic(
	() => import('@formio/react').then((module) => module.Form),
	{ ssr: false },
);

export default function Home() {
	const formInstance = useRef<Webform | null>(null);

	const handleClick = () => {
		if (!formInstance.current) {
			console.log("Our form isn't quite ready yet.");
			return;
		}
		formInstance.current.getComponent('firstName')?.setValue('John');
		formInstance.current.getComponent('lastName')?.setValue('Smith');
	};

	return (
		<main className={styles.main}>
			<Form
				form="https://examples.form.io/example"
				onFormReady={(instance) => {
					formInstance.current = instance;
				}}
			/>
			<button onClick={handleClick}>Set Names</button>
		</main>
	);
}

FormBuilder

A React component wrapper around a Form.io form builder. Able to render the form builder in your React application.

Props

Examples

Render a simple form builder with a blank form:

import { createRoot } from 'react-dom/client';
import { FormBuilder } from '@formio/react';

const domNode = document.getElementById('root');
const root = createRoot(domNode);

root.render(
	<FormBuilder />,
);

Render a builder with an initial form definition:

import { createRoot } from 'react-dom/client';
import { FormBuilder } from '@formio/react';

const domNode = document.getElementById('root');
const root = createRoot(domNode);

const formDefinition = {
	display: "form",
	components: [
		{
			type: "textfield"
			key: "firstName",
			label: "First Name",
			input: true,
		},
		{
			type: "textfield"
			key: "firstName",
			label: "First Name",
			input: true,
		},
		{
			type: "button",
			key: "submit",
			label: "Submit",
			input: true
		}
	]
}

root.render(<FormBuilder form={formDefinition} />);

Access the underlying form builder instance (see here for details):

import { useRef } from 'react';
import { createRoot } from 'react-dom/client';
import { FormBuilder } from '@formio/react';

const domNode = document.getElementById('root');
const root = createRoot(domNode);

const formDefinition = {
	display: "form",
	components: [
		{
			type: "textfield"
			key: "firstName",
			label: "First Name",
			input: true,
		},
		{
			type: "textfield"
			key: "firstName",
			label: "First Name",
			input: true,
		},
		{
			type: "button",
			key: "submit",
			label: "Submit",
			input: true
		}
	]
}

const App = () => {
	const formBuilderInstance = useRef(null);

	const handleFormReady = (instance) => {
		formBuilderInstance.current = instance;
	}

	const handleClick = () => {
		if (!formBuilderInstance.current) {
			console.log("Our form isn't quite ready yet.");
			return;
		}
		console.log("Here's our builder instance:", formBuilderInstance.current);
	}

	return (
		<div>
			<Form src={formDefinition} onFormReady={handleFormReady} />
			<button type="button" onClick={handleClick}>Log Our Builder</button>
		</div>
	);
}

root.render(<App />);

FormEdit

The FormEdit component wraps the FormBuilder component and adds a settings form, enabling direct interaction with forms to and from a Form.io server. The FormEdit component must be a child of a <FormioProvider /> component.

Props

Styling

FormEdit takes a components prop that contains each "element" of the FormEdit component, allowing you to inject your own markup and styling. Here is its type:

type ComponentProp<T = object> = (props: T) => JSX.Element;
type Components = {
	Container?: ComponentProp<{ children: ReactNode }>;
	SettingsFormContainer?: ComponentProp<{ children: ReactNode }>;
	BuilderContainer?: ComponentProp<{ children: ReactNode }>;
	SaveButtonContainer?: ComponentProp<{ children: ReactNode }>;
	SaveButton?: ComponentProp<{
		onClick: () => void;
	}>;
};

Examples

Load a simple FormEdit component that loads a form from a Form.io server:

import { createRoot } from 'react-dom/client';
import { useState, useEffect } from 'react';
import {
	FormGrid,
	FormioProvider,
	useFormioContext,
	FormType,
} from '@formio/react';

const App = () => {
	const { Formio, projectUrl } = useFormioContext();
	const [form, setForm] = useState<FormType | undefined>();

	useEffect(() => {
		const fetchForm = async () => {
			try {
				const formio = new Formio(`${projectUrl}/example`);
				const form = await formio.loadForm();
				setForm(form);
			} catch (err) {
				console.log('Error while fetching form:', err);
			}
		};
	}, [Formio, projectUrl]);

	return form ? (
		<FormEdit
			initialForm={form}
			onSaveForm={() => console.log('Form saved to my Form.io server!')}
		/>
	) : null;
};
const domNode = document.getElementById('root');
const root = createRoot(domNode);

root.render(
	<FormioProvider projectUrl="https://examples.form.io">
		<App />
	</FormioProvider>,
);

Inject your own markup and styling into constituent components:

import { createRoot } from 'react-dom/client';
import { useState, useEffect } from 'react';
import {
	FormEdit,
	FormioProvider,
	useFormioContext,
	FormType,
} from '@formio/react';

const App = ({ name }: { name: string }) => {
	const { Formio, projectUrl } = useFormioContext();
	const [form, setForm] = useState<FormType | undefined>();

	useEffect(() => {
		const fetchForm = async () => {
			try {
				const formio = new Formio(`${projectUrl}/example`);
				const form = await formio.loadForm();
				setForm(form);
			} catch (err) {
				console.log('Error while fetching form:', err);
			}
		};
	}, [Formio, projectUrl]);

	return form ? (
		<FormEdit
			initialForm={form}
			onSaveForm={() => console.log('Form saved to my Form.io server!')}
			components={{
				SaveButtonContainer: ({ children }) => (
					<div
						className="save-form-bar button-wrap"
						style={{ justifyContent: 'end' }}
					>
						{children}
					</div>
				),
				SaveButton: ({ onClick }) => (
					<button className="button save-form" onClick={onClick}>
						Save {name}
					</button>
				),
			}}
		/>
	) : null;
};
const domNode = document.getElementById('root');
const root = createRoot(domNode);

root.render(
	<FormioProvider projectUrl="https://examples.form.io">
		<App name="Form" />
	</FormioProvider>,
);

FormGrid

The FormGrid component can be used to render a list of forms with a set of actions on each row. The FormGrid component must be a child of a <FormioProvider /> component.

Props

Styling

FormGrid takes a components prop that contains each "element" of the FormGrid component, allowing you to inject your own markup and styling. Here is its type:

type ComponentProp<T = object> = (props: T) => JSX.Element;
type Components = {
	Container?: ComponentProp<{ children: ReactNode }>;
	FormContainer?: ComponentProp<{ children: ReactNode }>;
	FormNameContainer?: ComponentProp<{
		children: ReactNode;
		onClick?: () => void;
	}>;
	FormActionsContainer?: ComponentProp<{ children: ReactNode }>;
	FormActionButton?: ComponentProp<{
		action: Action;
		onClick: () => void;
	}>;
	PaginationContainer?: ComponentProp<{ children: ReactNode }>;
	PaginationButton?: ComponentProp<{
		children: ReactNode;
		isActive?: boolean;
		disabled?: boolean;
		onClick: () => void;
	}>;
};

Examples

Load a simple form grid that fetchs forms from a Form.io server (configured via the <FormioProvider /> component):

import { createRoot } from 'react-dom/client';
import { FormGrid, FormioProvider } from '@formio/react';

const domNode = document.getElementById('root');
const root = createRoot(domNode);

root.render(
	<FormioProvider projectUrl="https://examples.form.io">
		<FormGrid formQuery={{ type: 'form' }} />
	</FormioProvider>,
);

Inject your own markup and styling into constituent components:

import { FormGridProps, FormGrid } from '@formio/react';
import { createRoot } from 'react-dom/client';

const Container: FormGridComponentProps['Container'] = ({ children }) => (
	<div className="panel">{children}</div>
);

const FormContainer: FormGridComponentProps['FormContainer'] = ({
	children,
}) => (
	<div className={`item-wrap form`}>
		<button className="item">{children}</button>
	</div>
);

const FormNameContainer: FormGridComponentProps['FormNameContainer'] = ({
	children,
	onClick,
}) => {
	return (
		<div className="item-title" onClick={onClick}>
			<img src={`icon-form.svg`} alt={`${type} icon`} />
			{children}
		</div>
	);
};

const FormActionsContainer: FormGridComponentProps['FormActionsContainer'] = ({
	children,
}) => <div className="item-buttons">{children}</div>;

const FormActionButton: FormGridComponentProps['FormActionButton'] = ({
	action,
	onClick,
}) => (
	<a
		className={`btn ${action && action.name === 'Edit' ? 'edit' : 'trash'}`}
		onClick={onClick}
	>
		<i
			className={`${action && action.name === 'Edit' ? 'ri-edit-box-line' : 'ri-delete-bin-line'}`}
		></i> {action && action.name === 'Edit' ? 'Edit' : ''}
	</a>
);

const PaginationContainer: FormGridComponentProps['PaginationContainer'] = ({
	children,
}) => <div className="pagination-buttons">{children}</div>;

const PaginationButton: FormGridComponentProps['PaginationButton'] = ({
	isActive,
	disabled,
	children,
	onClick,
}) => (
	<a
		className={`pagination-btn${isActive ? ' active' : ''}${disabled ? ' disabled' : ''}`}
		onClick={onClick}
	>
		{children}
	</a>
);

export const MyFormGrid = () => {
	return (
		<FormGrid
			formQuery={{ type: 'form' }}
			onFormClick={(id) => console.log(`Form with id ${id} clicked!`)}
			components={{
				Container,
				FormContainer,
				FormNameContainer,
				FormActionsContainer,
				FormActionButton,
				PaginationContainer,
				PaginationButton,
			}}
		/>
	);
};

const domNode = document.getElementById('root');
const root = createRoot(domNode);

root.render(
	<FormioProvider projectUrl="https://examples.form.io">
		<MyFormGrid />
	</FormioProvider>,
);

SubmissionGrid

The SubmissionGrid component can be used to render a list of forms with a set of actions on each row. The SubmissionGrid component must be a child of a <FormioProvider /> component.

Props

Styling

SubmissionGrid takes a components prop that contains each constituent "element" of the SubmissionGrid component, allowing you to inject your own markup and styling. Here is its type:

type ComponentProp<T = object> = (props: T) => JSX.Element;
type Components = {
	Container?: ComponentProp<{ children: ReactNode }>;
	TableContainer?: ComponentProp<{ children: ReactNode }>;
	TableHeadContainer?: ComponentProp<{ children: ReactNode }>;
	TableHeadCell?: ComponentProp<{ children: ReactNode }>;
	TableBodyRowContainer?: ComponentProp<{
		children: ReactNode;
		onClick?: () => void;
	}>;
	TableHeaderRowContainer?: ComponentProp<{ children: ReactNode }>;
	TableBodyContainer?: ComponentProp<{ children: ReactNode }>;
	TableCell?: ComponentProp<{ children: ReactNode }>;
	PaginationContainer?: ComponentProp<{ children: ReactNode }>;
	PaginationButton?: ComponentProp<{
		children: ReactNode;
		isActive?: boolean;
		disabled?: boolean;
		onClick: () => void;
	}>;
};

Examples

Load a simple submission grid that fetchs forms from a Form.io server (configured via the <FormioProvider /> component):

import { createRoot } from 'react-dom/client';
import { SubmissionGrid, FormioProvider } from '@formio/react';

const domNode = document.getElementById('root');
const root = createRoot(domNode);

root.render(
	<FormioProvider projectUrl="https://examples.form.io">
		<SubmissionGrid formId="57aa1d2a5b7a477b002717fe" />
	</FormioProvider>,
);

Inject your own markup and styling into constituent components:

import { SubmissionGridProps, SubmissionGrid } from '@formio/react';
import { createRoot } from 'react-dom/client';

const components: SubmissionTableProps['components'] = {
	Container: ({ children }) => <div className="table-wrap">{children}</div>,
	TableContainer: ({ children }) => (
		<div className="table remember-focus-table">{children}</div>
	),
	TableHeadContainer: ({ children }) => <div>{children}</div>,
	TableHeaderRowContainer: ({ children }) => (
		<div className="trow heading">{children}</div>
	),
	TableHeadCell: ({ children }) => <div className="tcol">{children}</div>,
	TableBodyRowContainer: ({ children, onClick }) => (
		<div className="trow entry" onClick={onClick}>
			{children}
		</div>
	),
	TableBodyContainer: ({ children }) => <div>{children}</div>,
	TableCell: ({ children }) => <div className="tcol">{children}</div>,
	PaginationContainer: ({ children }) => (
		<div className="table-pagination">
			<div className="table-pagination-controls">{children}</div>
		</div>
	),
	PaginationButton: ({ children, isActive, onClick, disabled }) => (
		<a
			className={`pagination-btn${isActive ? ' active' : ''}${disabled ? ' disabled' : ''}`}
			onClick={onClick}
		>
			{children}
		</a>
	),
};

export const MySubmissionGrid = ({ id }: { id: string }) => {
	return (
		<SubmissionGrid
			onSubmissionClick={(id) =>
				console.log(`Submission with id ${id} clicked!`)
			}
			components={components}
			formId={id}
		/>
	);
};

const domNode = document.getElementById('root');
const root = createRoot(domNode);

root.render(
	<FormioProvider projectUrl="https://examples.form.io">
		<MySubmissionGrid id="57aa1d2a5b7a477b002717fe" />
	</FormioProvider>,
);

Modules

Modules contain Redux actions, reducers, constants and selectors to simplify the API requests made for form.io forms. Reducers, actions and selectors all have names. This provides namespaces so the same actions and reducers can be re-used within the same redux state.

root

The root module is the container for things shared by other modules such as the selectRoot selector.

Selectors

auth

The auth module is designed to make it easier to login, register and authenticate users within react using the form.io login system.

Reducers

Actions

form

The form module is for interacting with a single form.

Reducers

Actions

Selectors

forms

The forms module handles multiple forms like a list of forms.

Reducers

Actions

Selectors

submission

The submission module is for interacting with a single submission.

Reducers

Actions

Selectors

submissions

The submissions module handles multiple submissions within a form, like for a list of submissions.

Reducers

Actions

Selectors

License

Released under the MIT License.