@formio/react

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

[!IMPORTANT] As of 2 September 2025, the master branch will be renamed master_old and the default branch will be called main. main will be based on the 6.1.x branch, which is the latest stable release. See here for more details about this change.

React Versions

This library supports many different React Versions. If you wish to use this library with your specific version of React, then you will need to install the following versions.

React Compatibility | @formio/react | React Version | formiojs* | |---------------------|---------------------|--------------| | 5.2.x | 17 | 4.x | | 5.3.x | 18 | 4.x | | 6.0.x | 18 | 5.x | | 6.1.x | 19 | 5.x |

*Note: The formiojs namespace changes from formiojs (4.x) to @formio/js (5.x)

Install

npm

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

yarn

yarn add @formio/react @formio/js

Usage with Vite (Note: When using frameworks like Next.js or Create React App, no extra Vite configuration is necessary)

When using @formio/react in a project built with Vite (especially for React 18 and 19), make sure you install the @vitejs/plugin-react package and configure it in your vite.config.js file.

Install Vite React Plugin

npm install --save-dev @vitejs/plugin-react

In your vite.config.js, add the React plugin:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
});

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:

| Name | Type | Description | | --------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | Formio | typeof Formio | The global Formio object. Useful for various static methods as well as SDK functions that are exposed when the new operator is used. | | baseUrl | string | The base url for a Form.io server. | | projectUrl | string | The base url for a Form.io enterprise project. | | logout | () => void | A convenience method to logout of a Form.io session by invalidating the token and removing it from local storage. | | token | string | The Form.io JWT-token (if the user is authenticated). | | isAuthenticated | boolean | A convenience value that is toggled when logging in or out of a Form.io session. |

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

| Name | Type | Description | | ------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | initialPage | number | The initial page to fetch. | | limit | string | The number of results per page. | | dataOrFetchFunction | T[] | (limit: number, skip: number) => Promise<T[]> | Either the complete set of data to be paginated or a function that returns data. If a function, must support limit and skip and be a stable reference. |

Return Value

usePagination returns an object with the following parameters:

| Name | Type | Description | | --------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | data | T[] | The data at the current page. | | total | number | undefined | If available, the total number of documents. | | page | number | The current page number. | | hasMore | boolean | A value that indicates whether more results are available from the server. Useful when no total document count is available. | | nextPage | () => void | A function that moves the data to the next available page. | | prevPage | () => void | A function that moves the data to the previous available page. | | fetchPage | (page: number) => void | A function that moves the data to a specified page. |

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

| Name | Type | Description