Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/formio/react
JSON powered forms for React.js
https://github.com/formio/react
formio forms json reactjs
Last synced: about 3 hours ago
JSON representation
JSON powered forms for React.js
- Host: GitHub
- URL: https://github.com/formio/react
- Owner: formio
- License: mit
- Created: 2015-09-23T21:51:26.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2024-12-06T10:17:02.000Z (8 days ago)
- Last Synced: 2024-12-07T01:04:55.210Z (7 days ago)
- Topics: formio, forms, json, reactjs
- Language: TypeScript
- Homepage: https://form.io
- Size: 13.2 MB
- Stars: 318
- Watchers: 24
- Forks: 269
- Open Issues: 29
-
Metadata Files:
- Readme: README.md
- Changelog: Changelog.md
- License: LICENSE
Awesome Lists containing this project
README
# @formio/react
A [React](http://facebook.github.io/react/) library for rendering out forms based on the [Form.io](https://www.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](https://github.com/formio/react-app-starterkit)
## Install
### npm
```bash
npm install @formio/react --save
npm install @formio/js --save
```
### yarn
```bash
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 `` 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:
```tsx
import { createRoot } from 'react-dom/client';
import { useFormioContext, FormGrid, FormioProvider } from '@formio/react';
const App = () => {
const { isAuthenticated } = useFormioContext();
return isAuthenticated ? (
setLocation(`/form/${id}`)}
/>
setLocation(`/resource/${id}`)}
/>
) : (
);
};
const domNode = document.getElementById('root');
const root = createRoot(domNode);
root.render(
,
);
```
Use the [Form.io SDK](https://help.form.io/developers/javascript-development/javascript-sdk) to interact with a Form.io server:
```tsx
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([]);
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 (
<>
>
);
});
};
const domNode = document.getElementById('root');
const root = createRoot(domNode);
const root = createRoot();
root.render(
,
);
```
### 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 `` 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 | 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:
```tsx
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(
1,
10,
fetchFunction,
);
return (
{data.map((form) => (
<>
>
))}
-
Prev
-
Next
);
};
const domNode = document.getElementById('root');
const root = createRoot(domNode);
const root = createRoot();
root.render(
,
);
```
## Components
### FormioProvider
A React context provider component that is required when using some hooks and components from this library.
#### Props
| Name | Type | Description |
| ---------- | ------ | ---------------------------------------- |
| baseUrl | string | The base url of a Form.io server. |
| projectUrl | string | The url of a Form.io enterprise project. |
### Form
A React component wrapper around [a Form.io form](https://help.form.io/developers/form-development/form-renderer#introduction). Able to take a JSON form definition or a Form.io form URL and render the form in your React application.
#### Props
| Name | Type | Default | Description |
| ------------------- | --------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `src` | `Webform \| string` | | The JSON form definition or the source URL. If a URL, commonly from a form.io server. |
| `url` | `string` | | The url of the form definition. Used in conjunction with a JSON form definition passed to `src`, this is used for file upload, OAuth, and other components or actions that need to know the URL of the Form.io form for further processing. The form will not be loaded from this url and the submission will not be saved here either. |
| `submission` | `JSON` | | Submission data to fill the form. You can either load a previous submission or create a submission with some pre-filled data. If you do not provide a submissions the form will initialize an empty submission using default values from the form. |
| `options` | `FormOptions` | | The form options. See [here](https://help.form.io/developers/form-development/form-renderer#form-renderer-options) for more details. |
| `onFormReady` | `(instance: Webform) => void` | | A callback function that gets called when the form has rendered. It is useful for accessing the underlying @formio/js Webform instance. |
| `onSubmit` | `(submission: JSON, saved?: boolean) => void` | | A callback function that gets called when the submission has started. If `src` is not a Form.io server URL, this will be the final submit event. |
| `onCancelSubmit` | `() => void` | | A callback function that gets called when the submission has been canceled. |
| `onSubmitDone` | `(submission: JSON) => void` | | A callback function that gets called when the submission has successfully been made to the server. This will only fire if `src` is set to a Form.io server URL. |
| `onChange` | `(value: any, flags: any, modified: any) => void` | | A callback function that gets called when a value in the submission has changed. |
| `onComponentChange` | `(changed: { instance: Webform; component: Component; value: any; flags: any}) => void` | | A callback function that gets called when a specific component changes. |
| `onError` | `(error: EventError \| false) => void` | | A callback function that gets called when an error occurs during submission (e.g. a validation error). |
| `onRender` | `(param: any) => void` | | A callback function that gets called when the form is finished rendering. `param` will depend on the form and display type. |
| `onCustomEvent` | `(event: { type: string; component: Component; data: JSON; event?: Event; }) => void` | | A callback function that is triggered from a button component configured with "Event" type. |
| `onPrevPage` | `(page: number, submission: JSON) => void` | | A callback function for Wizard forms that gets called when the "Previous" button is pressed. |
| `onNextPage` | `(page: number, submission: JSON) => void` | | A callback function for Wizard forms that gets called when the "Next" button is pressed. |
| `otherEvents` | `[event: string]: (...args: any[]) => void;` | | A "catch-all" prop for subscribing to other events (for a complete list, see [our documentation](https://help.form.io/developers/form-development/form-renderer#form-events)). |
#### Examples
Render a simple form from the Form.io SaaS:
```JSX
import { createRoot } from 'react-dom/client';
import { Form } from '@formio/react';
const domNode = document.getElementById('root');
const root = createRoot(domNode);
root.render(
,
);
```
Render a simple form from a JSON form definition:
```JSX
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();
```
Access the underlying form instance (see [here](https://help.form.io/developers/form-development/form-renderer#form-properties) for details):
```JSX
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 (
Set Names
);
}
root.render();
```
#### 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](https://nextjs.org/docs/app/building-your-application/rendering/client-components). For this reason, we recommend dynamically importing the Form component using Next.js' `dynamic` API:
```tsx
'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(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 (
{
formInstance.current = instance;
}}
/>
Set Names
);
}
```
### FormBuilder
A React component wrapper around [a Form.io form builder](https://help.form.io/developers/form-development/form-builder). Able to render the form builder in your React application.
#### Props
| Name | Type | Default | Description |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `initialForm` | `FormType` | | The JSON form definition of the initial form to be rendered in the builder. Oftentimes, this must be a stable reference; otherwise it may destroy and recreate the underlying builder instance and cause unexpected behavior. |
| `options` | `FormBuilderOptions` | | The form builder options. See [here](https://help.form.io/developers/form-development/form-builder#form-builder-options) for more details. |
| `onBuilderReady` | `(instance: FormBuilder) => void` | | A callback function that gets called when the form builder has rendered. It is useful for accessing the underlying @formio/js FormBuilder instance. |
| `onChange` | `(form: FormType) => void` | | A callback function that gets called when the form being built has changed. |
| `onSaveComponent` | `(component: Component, original: Component, parent: Component, path: string, index: number, isNew: boolean, originalComponentSchema: Component) => void;` | | A callback function that gets called when a component is saved in the builder. |
| `onEditComponent` | `(component: Component) => void` | | A callback function that gets called when a component is edited. |
| `onUpdateComponent` | `(component: Component) => void` | | A callback function that is called when a component is updated. |
| `onDeleteComponent` | `(component: Component, parent: Component, path: string, index: number) => void` | | A callback function that is called when a component is deleted. |
#### Examples
Render a simple form builder with a blank form:
```JSX
import { createRoot } from 'react-dom/client';
import { FormBuilder } from '@formio/react';
const domNode = document.getElementById('root');
const root = createRoot(domNode);
root.render(
,
);
```
Render a builder with an initial form definition:
```JSX
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();
```
Access the underlying form builder instance (see [here](https://help.form.io/developers/form-development/form-builder#form-builder-sdk) for details):
```JSX
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 (
Log Our Builder
);
}
root.render();
```
### 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 `` component.**
#### Props
| Name | Type | Default | Description |
| --------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `initialForm` | `FormType` | `{ title: '', name: '', path: '', display: 'form' as const, type: 'form' as const, components: [] }` | The form definition of the existing form that is to be modified. |
| `settingsForm` | `FormType` | `DEFAULT_SETTINGS_FORM` | The form definition for the "settings" form, which defaults to a form that defines the title, name, path, tags, and display of the form being edited. |
| `settingsFormOptions` | `FormOptions` | `{}` | The options passed to the settings form. |
| `onSettingsFormReady` | `(instance: Webform) => void` | | The `onFormReady` callback for the settings form. |
| `onBuilderReady` | `(instance: FormioBuilder) => void` | | The `onBuilderReady` callback for the form builder. |
| `builderOptions` | `FormBuilderOptions` | `{}` | The options to be passed to FormBuilder. |
| `saveFormFn` | `(form: FormType) => Promise` | | Defaults to using the Form.io SDK to save the form to a Form.io server configured by ``. |
| `onSaveForm` | `(form: FormType) => void` | | The callback that is called after `saveFormFn` is called (either the prop or the default). An optional function that replaces the default behavior of saving the form to a Form.io server. |
#### 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:
```ts
type ComponentProp = (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:
```tsx
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();
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 ? (
console.log('Form saved to my Form.io server!')}
/>
) : null;
};
const domNode = document.getElementById('root');
const root = createRoot(domNode);
root.render(
,
);
```
Inject your own markup and styling into constituent components:
```tsx
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();
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 ? (
console.log('Form saved to my Form.io server!')}
components={{
SaveButtonContainer: ({ children }) => (
{children}
),
SaveButton: ({ onClick }) => (
Save {name}
),
}}
/>
) : null;
};
const domNode = document.getElementById('root');
const root = createRoot(domNode);
root.render(
,
);
```
### 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 `` component.**
#### Props
| Name | Type | Default | Description |
| ------------- | ---------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `actions` | `Action[]` | `DEFAULT_ACTIONS` | An array of actions that correspond to buttons on each form grid row. Defaults to an Edit action (which will call the `onFormClick` function prop) and a Delete action (which will use the Form.io SDK to soft delete the form). |
| `forms` | `FormType[]` | | If you'd like to manage fetching yourself, you can pass an array of forms to `FormGrid`. |
| `formQuery` | `Record` | `{}` | If you don't pass the `forms` prop, `FormGrid` will use the Form.io SDK to fetch forms based on the `formQuery` prop. |
| `onFormClick` | `(id: string) => void` | | A callback function called when the `FormNameContainer` is clicked. |
| `limit` | `number` | `10` | The page size limit used by `usePagination`. |
| `components` | `Record>` | `{}` | The list of styleable components. See [Styling](#Styling) for details. |
#### 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:
```ts
type ComponentProp = (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 `` component):
```tsx
import { createRoot } from 'react-dom/client';
import { FormGrid, FormioProvider } from '@formio/react';
const domNode = document.getElementById('root');
const root = createRoot(domNode);
root.render(
,
);
```
Inject your own markup and styling into constituent components:
```tsx
import { FormGridProps, FormGrid } from '@formio/react';
import { createRoot } from 'react-dom/client';
const Container: FormGridComponentProps['Container'] = ({ children }) => (
{children}
);
const FormContainer: FormGridComponentProps['FormContainer'] = ({
children,
}) => (
{children}
);
const FormNameContainer: FormGridComponentProps['FormNameContainer'] = ({
children,
onClick,
}) => {
return (
{children}
);
};
const FormActionsContainer: FormGridComponentProps['FormActionsContainer'] = ({
children,
}) =>
{children};
const FormActionButton: FormGridComponentProps['FormActionButton'] = ({
action,
onClick,
}) => (
{action && action.name === 'Edit' ? 'Edit' : ''}
);
const PaginationContainer: FormGridComponentProps['PaginationContainer'] = ({
children,
}) =>
{children};
const PaginationButton: FormGridComponentProps['PaginationButton'] = ({
isActive,
disabled,
children,
onClick,
}) => (
{children}
);
export const MyFormGrid = () => {
return (
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(
,
);
```
### 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 `` component.**
#### Props
| Name | Type | Default | Description |
| ------------------- | ---------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `submissions` | `Submission[]` | | If you'd like to manage fetching yourself, you can pass an array of submissions to `SubmissionGrid`. |
| `formId` | `string` | | The id of the form whose submissions `SubmissionGrid` will fetch if the `submissions` prop is not provided. |
| `submissionQuery` | `Record` | `{}` | If you don't pass the `submissions` prop, `SubmissionsGrid` will use the Form.io SDK to fetch forms based on the `submissionQuery` prop. |
| `onSubmissionClick` | `(id: string) => void` | | A callback function called when the `TableBodyRowContainer` constituent component is clicked. |
| `limit` | `number` | `10` | The page size limit used by `usePagination`. |
| `components` | `Record>` | `{}` | The list of styleable components. See [Styling](#Styling) for details. |
#### 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:
```ts
type ComponentProp = (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 `` component):
```tsx
import { createRoot } from 'react-dom/client';
import { SubmissionGrid, FormioProvider } from '@formio/react';
const domNode = document.getElementById('root');
const root = createRoot(domNode);
root.render(
,
);
```
Inject your own markup and styling into constituent components:
```tsx
import { SubmissionGridProps, SubmissionGrid } from '@formio/react';
import { createRoot } from 'react-dom/client';
const components: SubmissionTableProps['components'] = {
Container: ({ children }) =>
{children},
TableContainer: ({ children }) => (
{children}
),
TableHeadContainer: ({ children }) => {children},
TableHeaderRowContainer: ({ children }) => (
{children}
),
TableHeadCell: ({ children }) => {children},
TableBodyRowContainer: ({ children, onClick }) => (
{children}
),
TableBodyContainer: ({ children }) => {children},
TableCell: ({ children }) => {children},
PaginationContainer: ({ children }) => (
{children}
),
PaginationButton: ({ children, isActive, onClick, disabled }) => (
{children}
),
};
export const MySubmissionGrid = ({ id }: { id: string }) => {
return (
console.log(`Submission with id ${id} clicked!`)
}
components={components}
formId={id}
/>
);
};
const domNode = document.getElementById('root');
const root = createRoot(domNode);
root.render(
,
);
```
## 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
| Name | Parameters | Description |
| ---------------- | --------------------------- | --------------------------------------- |
| `selectRoot` | name: string, state: object | Returns the state for a namespace. |
| `selectError` | name: string, state: object | Returns any errors for a namespace. |
| `selectIsActive` | name: string, state: object | Returns isActive state for a namespace. |
### 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
| Name | Parameters | Description |
| ------ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auth` | config: object | Mounts the user and access information to the state tree. Config is not currently used but is a placeholder to make it consistent to the other reducers. |
#### Actions
| Name | Parameters | Description |
| ---------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `initAuth` | | This is usually used at the start of an app code. It will check the localStorage for an existing user token and if found, log them in and fetch the needed information about the user. |
| `setUser` | user: object | When a user logs in, this will set the user and fetch the access information for that user. The user object is usually a submission from the login or register form. |
| `logout` | | This action will reset everything to the default state, including removing any localStorage information. |
### form
The form module is for interacting with a single form.
#### Reducers
| Name | Parameters | Description |
| ------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `form` | config: object | Mounts the form to the state tree. The config object should contain a name property defining a unique name for the redux state. |
#### Actions
| Name | Parameters | Description |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getForm` | name: string, id: string, done: function | Fetch a form from the server. If no id is provided, the name is used as the path. The `done` callback will be called when the action is complete. The first parameter is any errors and the second is the form definition. |
| `saveForm` | name: string, form: object, done: function | Save a form to the server. It will use the \_id property on the form to save it if it exists. Otherwise it will create a new form. The `done` callback will be called when the action is complete. The first parameter is any errors and the second is the form definition. |
| `deleteForm` | name: string, id: string, done: function | Delete the form on the server with the id. |
| `resetForm` | Reset this reducer back to its initial state. This is automatically called after delete but can be called other times as well. |
#### Selectors
| Name | Parameters | Description |
| ------------ | --------------------------- | ------------------------------------------ |
| `selectForm` | name: string, state: object | Select the form definition from the state. |
### forms
The forms module handles multiple forms like a list of forms.
#### Reducers
| Name | Parameters | Description |
| ------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `forms` | config: object | Mounts the forms to the state tree. The config object should contain a name property defining a unique name for the redux state. The config object can also contain a query property which is added to all requests for forms. For example: {tags: 'common'} would limit the lists of forms to only forms tagged with 'common'. |
#### Actions
| Name | Parameters | Description |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| `getForms` | name: string, page: integer, params: object | Fetch a list of forms from the server. `params` is a query object to filter the forms. |
| `resetForms` | Reset this reducer back to its initial state. This is automatically called after delete but can be called other times as well. |
#### Selectors
| Name | Parameters | Description |
| ------------- | --------------------------- | ---------------------------------------- |
| `selectForms` | name: string, state: object | Select the list of forms from the state. |
### submission
The submission module is for interacting with a single submission.
#### Reducers
| Name | Parameters | Description |
| ------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `submission` | config: object | Mounts the submission to the state tree. The config object should contain a name property defining a unique name for the redux state. |
#### Actions
| Name | Parameters | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getSubmission` | name: string, id: string, formId: string, done: function | Fetch a submission from the server. The `done` callback will be called when the action is complete. The first parameter is any errors and the second is the submission. |
| `saveSubmission` | name: string, submission: object, formId: string, done: function | Save a submission to the server. It will use the \_id property on the submission to save it if it exists. Otherwise it will create a new submission. The `done` callback will be called when the action is complete. The first parameter is any errors and the second is the submission. |
| `deleteSubmission` | name: string, id: string, formId: string, done: function | Delete the submission on the server with the id. |
| `resetSubmission` | Reset this reducer back to its initial state. This is automatically called after delete but can be called other times as well. |
#### Selectors
| Name | Parameters | Description |
| ------------------ | --------------------------- | ------------------------------------------ |
| `selectSubmission` | name: string, state: object | Select the submission data from the state. |
### submissions
The submissions module handles multiple submissions within a form, like for a list of submissions.
#### Reducers
| Name | Parameters | Description |
| ------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `submissions` | config: object | Mounts the submissions to the state tree. The config object should contain a name property defining a unique name for the redux state. |
#### Actions
| Name | Parameters | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `getSubmissions` | name: string, page: integer, params: object, formId: string | Fetch a list of submissions from the server. `params` is a query object to filter the submissions. |
| `resetSubmissions` | Reset this reducer back to its initial state. This is automatically called after delete but can be called other times as well. |
#### Selectors
| Name | Parameters | Description |
| ------------------- | --------------------------- | ---------------------------------------------- |
| `selectSubmissions` | name: string, state: object | Select the list of submissions from the state. |
## License
Released under the [MIT License](http://www.opensource.org/licenses/MIT).