# React Hook Reference

The following React Hooks are available:

* [useEnterpriseFormBuilder](#useenterpriseformbuilder) - Access the enterprise form builder context
* [useLoadForm](https://file+.vscode-resource.vscode-cdn.net/Users/mslavin/FormioCodebase/nirvana/packages/enterprise-form-builder-react/docs/hooks/useLoadForm.md) - Load a single form by ID
* [useLoadForms](#useloadforms) - Load multiple forms with optional query parameters
* [useSaveForm](#usesaveform) - Save forms with optional conflict resolution
* [useDeleteForm](https://file+.vscode-resource.vscode-cdn.net/Users/mslavin/FormioCodebase/nirvana/packages/enterprise-form-builder-react/docs/hooks/useDeleteForm.md) - Delete a form by ID
* [useLoadSubmission](#useloadsubmission) - Load a single submission by form ID and submission ID
* [useSaveSubmission](#usesavesubmission) - Save a submission
* [useDeleteSubmission](#usedeletesubmission) - Delete a submission
* [useLoadProject](#useloadproject) - Load Form.io project information

## useEnterpriseFormBuilder

A hook that provides access to the enterprise form builder context.

### Summary <a href="#summary" id="summary"></a>

The `useEnterpriseFormBuilder` hook returns the context value from `EnterpriseFormBuilderProvider`, including project information, Form.io instance, license key, roles, and a helper function for getting builder options.

### Returns <a href="#returns" id="returns"></a>

| Property            | Type                                   | Description                                        |
| ------------------- | -------------------------------------- | -------------------------------------------------- |
| `licenseKey`        | `string`                               | The enterprise license key                         |
| `tag`               | `string`                               | The tag used for filtering forms                   |
| `project`           | `any`                                  | The Form.io project object                         |
| `roles`             | `Record<string, any>`                  | User roles from the project                        |
| `Formio`            | `any`                                  | The Form.io class/constructor                      |
| `projectUrl`        | `string`                               | The project URL                                    |
| `isAuthenticated`   | `boolean`                              | Whether the user is authenticated                  |
| `error`             | `string \| null`                       | Any error that occurred loading the project        |
| `getBuilderOptions` | `(displayType: FormDisplay) => object` | Function to get builder options for a display type |

### Usage Example <a href="#usage-example" id="usage-example"></a>

```tsx
import { useEnterpriseFormBuilder } from '@formio/enterprise-form-builder-react';

function MyComponent() {
  const { 
    project, 
    Formio, 
    projectUrl, 
    getBuilderOptions 
  } = useEnterpriseFormBuilder();

  const builderOptions = getBuilderOptions('form');

  // Use the context values...
}
```

### Related <a href="#related" id="related"></a>

* [`EnterpriseFormBuilderProvider`](https://help.form.io/userguide/enterprise-form-builder-module/application-integration/react-applications/react-context-provider) - Provider that supplies this context

## useLoadForm

A hook for loading a single form by ID.

### Summary <a href="#summary" id="summary"></a>

The `useLoadForm` hook provides functionality to load a form by its ID. It manages loading and error states automatically.

### Returns <a href="#returns" id="returns"></a>

| Property   | Type                                | Description                                |
| ---------- | ----------------------------------- | ------------------------------------------ |
| `loadForm` | `(formId: string) => Promise<void>` | Function to load a form by ID              |
| `form`     | `Form \| null`                      | The loaded form object                     |
| `loading`  | `boolean`                           | Whether the form is currently being loaded |
| `error`    | `string \| null`                    | Any error that occurred loading the form   |

### Usage Example <a href="#usage-example" id="usage-example"></a>

```tsx
import { useLoadForm } from '@formio/enterprise-form-builder-react';
import { useEffect } from 'react';

function FormDetails({ formId }: { formId: string }) {
  const { loadForm, form, loading, error } = useLoadForm();

  useEffect(() => {
    loadForm(formId);
  }, [formId, loadForm]);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;
  if (!form) return <div>Form not found</div>;

  return <div>{form.title}</div>;
}
```

### Related Components <a href="#related-components" id="related-components"></a>

* [#createforms](https://help.form.io/userguide/enterprise-form-builder-module/application-integration/react-component-reference#createforms "mention")- Form builder component
* [#formviewer](https://help.form.io/userguide/enterprise-form-builder-module/application-integration/react-component-reference#formviewer "mention")- Form display component
* [#useform](https://help.form.io/userguide/enterprise-form-builder-module/application-integration/react-component-reference#useform "mention")- Form with submission component

## useLoadForms

A hook for loading multiple forms with optional query parameters.

### Summary <a href="#summary" id="summary"></a>

The `useLoadForms` hook provides functionality to load a list of forms. It supports query parameters for filtering, pagination, and sorting.

### Returns <a href="#returns" id="returns"></a>

| Property    | Type                                                     | Description                                           |
| ----------- | -------------------------------------------------------- | ----------------------------------------------------- |
| `loadForms` | `(queryParams?: Record<string, any>) => Promise<Form[]>` | Function to load forms with optional query parameters |
| `forms`     | `Form[] \| null`                                         | The loaded forms array                                |
| `loading`   | `boolean`                                                | Whether forms are currently being loaded              |
| `error`     | `string \| null`                                         | Any error that occurred loading forms                 |

### Query Parameters <a href="#query-parameters" id="query-parameters"></a>

The `loadForms` function accepts query parameters such as:

* `limit`: Number of forms to return (default: 10)
* `skip`: Number of forms to skip (for pagination)
* `tags`: Array of tags to filter by
* `type`: Form type (default: "form")

### Usage Example <a href="#usage-example" id="usage-example"></a>

```tsx
import { useLoadForms } from '@formio/enterprise-form-builder-react';
import { useEffect } from 'react';

function FormsList() {
  const { loadForms, forms, loading, error } = useLoadForms();

  useEffect(() => {
    loadForms({ limit: 20, tags: ['common'] });
  }, [loadForms]);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;

  return (
    <ul>
      {forms?.map(form => (
        <li key={form._id}>{form.title}</li>
      ))}
    </ul>
  );
}
```

### Related Components <a href="#related-components" id="related-components"></a>

* [#formlist](https://help.form.io/userguide/enterprise-form-builder-module/application-integration/react-component-reference#formlist "mention")- Form list display component

## useSaveForm

A hook for saving forms with optional conflict resolution.

### Summary <a href="#summary" id="summary"></a>

The `useSaveForm` hook provides functionality to save a form. It supports conflict resolution by merging changes when a conflict is detected.

### Returns <a href="#returns" id="returns"></a>

| Property     | Type                                                            | Description                                                           |
| ------------ | --------------------------------------------------------------- | --------------------------------------------------------------------- |
| `saveForm`   | `(formData: FormType, changes?: FormChange[]) => Promise<Form>` | Function to save a form with optional changes for conflict resolution |
| `savedForm`  | `Form \| null`                                                  | The saved form object                                                 |
| `loading`    | `boolean`                                                       | Whether the form is currently being saved                             |
| `error`      | `string \| null`                                                | Any error that occurred saving the form                               |
| `clearError` | `() => void`                                                    | Function to clear the error state                                     |

### Arguments <a href="#arguments" id="arguments"></a>

* `formData`: The form object to save
* `changes`: Optional array of `FormChange` objects for conflict resolution. If provided and a conflict occurs, the hook will attempt to merge changes automatically.

### Usage Example <a href="#usage-example" id="usage-example"></a>

```tsx
import { useSaveForm } from '@formio/enterprise-form-builder-react';

function SaveFormButton({ form }) {
  const { saveForm, loading, error } = useSaveForm();

  const handleSave = async () => {
    try {
      const saved = await saveForm(form);
      console.log('Form saved:', saved);
    } catch (err) {
      console.error('Save failed:', err);
    }
  };

  return (
    <button onClick={handleSave} disabled={loading}>
      {loading ? 'Saving...' : 'Save Form'}
    </button>
  );
}
```

### Related Components <a href="#related-components" id="related-components"></a>

* [#createforms](https://help.form.io/userguide/enterprise-form-builder-module/application-integration/react-component-reference#createforms "mention") - Form builder component
* [#formsettings](https://help.form.io/userguide/enterprise-form-builder-module/application-integration/react-component-reference#formsettings "mention")- Form settings component

## useDeleteForm

A hook for deleting a form.

### Summary

The `useDeleteForm` hook provides functionality to delete a form by its ID. It manages loading, error, and success states automatically.

### Returns

| Property     | Type                                               | Description                               |
| ------------ | -------------------------------------------------- | ----------------------------------------- |
| `deleteForm` | `(options: DeleteFormOptions) => Promise<boolean>` | Function to delete a form                 |
| `loading`    | `boolean`                                          | Whether the deletion is in progress       |
| `error`      | `string \| null`                                   | Any error that occurred deleting the form |
| `success`    | `boolean`                                          | Whether the deletion was successful       |

### Arguments

The `deleteForm` function accepts an object with:

* `formId`: The ID of the form to delete

### Usage Example

```tsx
import { useDeleteForm } from '@formio/enterprise-form-builder-react';

function DeleteFormButton({ formId }: { formId: string }) {
  const { deleteForm, loading, error, success } = useDeleteForm();

  const handleDelete = async () => {
    await deleteForm({ formId });
  };

  if (success) return <div>Form deleted successfully!</div>;
  if (error) return <div>Error: {error}</div>;

  return (
    <button onClick={handleDelete} disabled={loading}>
      {loading ? 'Deleting...' : 'Delete Form'}
    </button>
  );
}
```

### Related Components

* [#formdelete](https://help.form.io/userguide/enterprise-form-builder-module/application-integration/react-component-reference#formdelete "mention")- Delete confirmation component

## useLoadSubmission

A hook for loading a single submission by form ID and submission ID.

### Summary <a href="#summary" id="summary"></a>

The `useLoadSubmission` hook provides functionality to load a submission. It manages loading and error states automatically.

### Returns <a href="#returns" id="returns"></a>

| Property         | Type                                                      | Description                                      |
| ---------------- | --------------------------------------------------------- | ------------------------------------------------ |
| `loadSubmission` | `(formId: string, submissionId: string) => Promise<void>` | Function to load a submission                    |
| `submission`     | `Submission \| null`                                      | The loaded submission object                     |
| `loading`        | `boolean`                                                 | Whether the submission is currently being loaded |
| `error`          | `string \| null`                                          | Any error that occurred loading the submission   |

### Usage Example <a href="#usage-example" id="usage-example"></a>

```tsx
import { useLoadSubmission } from '@formio/enterprise-form-builder-react';
import { useEffect } from 'react';

function SubmissionDetails({ 
  formId, 
  submissionId 
}: { 
  formId: string; 
  submissionId: string;
}) {
  const { loadSubmission, submission, loading, error } = useLoadSubmission();

  useEffect(() => {
    loadSubmission(formId, submissionId);
  }, [formId, submissionId, loadSubmission]);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;
  if (!submission) return <div>Submission not found</div>;

  return <div>{JSON.stringify(submission.data)}</div>;
}
```

### Related Components <a href="#related-components" id="related-components"></a>

* [#submissionviewer](https://help.form.io/userguide/enterprise-form-builder-module/application-integration/react-component-reference#submissionviewer "mention")- Submission display component
* [#useform](https://help.form.io/userguide/enterprise-form-builder-module/application-integration/react-component-reference#useform "mention") - Form with submission component

## useSaveSubmission

A hook for saving a submission.

### Summary <a href="#summary" id="summary"></a>

The `useSaveSubmission` hook provides functionality to save a submission. It manages loading and error states automatically.

### Returns <a href="#returns" id="returns"></a>

| Property         | Type                                                        | Description                                     |
| ---------------- | ----------------------------------------------------------- | ----------------------------------------------- |
| `saveSubmission` | `(formId: string, submission: Submission) => Promise<void>` | Function to save a submission                   |
| `loading`        | `boolean`                                                   | Whether the submission is currently being saved |
| `error`          | `string \| null`                                            | Any error that occurred saving the submission   |

### Usage Example <a href="#usage-example" id="usage-example"></a>

```tsx
import { useSaveSubmission } from '@formio/enterprise-form-builder-react';

function SaveSubmissionButton({ 
  formId, 
  submission 
}: { 
  formId: string; 
  submission: Submission;
}) {
  const { saveSubmission, loading, error } = useSaveSubmission();

  const handleSave = async () => {
    try {
      await saveSubmission(formId, submission);
      console.log('Submission saved');
    } catch (err) {
      console.error('Save failed:', err);
    }
  };

  return (
    <button onClick={handleSave} disabled={loading}>
      {loading ? 'Saving...' : 'Save Submission'}
    </button>
  );
}
```

### Related Components <a href="#related-components" id="related-components"></a>

* [#submissionviewer](https://help.form.io/userguide/enterprise-form-builder-module/application-integration/react-component-reference#submissionviewer "mention")- Submission display component
* [#useform](https://help.form.io/userguide/enterprise-form-builder-module/application-integration/react-component-reference#useform "mention")- Form with submission component
* [#formviewer](https://help.form.io/userguide/enterprise-form-builder-module/application-integration/react-component-reference#formviewer "mention") - Form display component

## useDeleteSubmission

A hook for deleting a submission.

### Summary <a href="#summary" id="summary"></a>

The `useDeleteSubmission` hook provides functionality to delete a submission. It manages loading and error states automatically.

### Returns <a href="#returns" id="returns"></a>

| Property           | Type                                                        | Description                                     |
| ------------------ | ----------------------------------------------------------- | ----------------------------------------------- |
| `deleteSubmission` | `(formId: string, submission: Submission) => Promise<void>` | Function to delete a submission                 |
| `loading`          | `boolean`                                                   | Whether the deletion is in progress             |
| `error`            | `string \| null`                                            | Any error that occurred deleting the submission |

### Usage Example <a href="#usage-example" id="usage-example"></a>

```tsx
import { useDeleteSubmission } from '@formio/enterprise-form-builder-react';

function DeleteSubmissionButton({ 
  formId, 
  submission 
}: { 
  formId: string; 
  submission: Submission;
}) {
  const { deleteSubmission, loading, error } = useDeleteSubmission();

  const handleDelete = async () => {
    try {
      await deleteSubmission(formId, submission);
      console.log('Submission deleted');
    } catch (err) {
      console.error('Delete failed:', err);
    }
  };

  return (
    <button onClick={handleDelete} disabled={loading}>
      {loading ? 'Deleting...' : 'Delete Submission'}
    </button>
  );
}
```

### Related Components <a href="#related-components" id="related-components"></a>

* [#formdelete](https://help.form.io/userguide/enterprise-form-builder-module/application-integration/react-component-reference#formdelete "mention")- Delete confirmation component
* [#submissionviewer](https://help.form.io/userguide/enterprise-form-builder-module/application-integration/react-component-reference#submissionviewer "mention")- Submission display component

## useLoadProject

A hook for loading project information.

### Summary <a href="#summary" id="summary"></a>

The `useLoadProject` hook provides functionality to load the Form.io project information. It manages loading and error states automatically.

### Returns <a href="#returns" id="returns"></a>

| Property      | Type                  | Description                                   |
| ------------- | --------------------- | --------------------------------------------- |
| `loadProject` | `() => Promise<void>` | Function to load project information          |
| `project`     | `any`                 | The loaded project object                     |
| `loading`     | `boolean`             | Whether the project is currently being loaded |
| `error`       | `string \| null`      | Any error that occurred loading the project   |

### Usage Example <a href="#usage-example" id="usage-example"></a>

```tsx
import { useLoadProject } from '@formio/enterprise-form-builder-react';
import { useEffect } from 'react';

function ProjectInfo() {
  const { loadProject, project, loading, error } = useLoadProject();

  useEffect(() => {
    loadProject();
  }, [loadProject]);

  if (loading) return <div>Loading project...</div>;
  if (error) return <div>Error: {error}</div>;
  if (!project) return null;

  return <div>Project: {project.title}</div>;
}
```

### Related Components <a href="#related-components" id="related-components"></a>

* [#createforms](https://help.form.io/userguide/enterprise-form-builder-module/application-integration/react-component-reference#createforms "mention")- Form builder component