Hooks

useFormState

Core form state management hook. Used internally by OSForm — exposed for advanced custom renderers.

import { useFormState } from '@osforms/react';

const [state, actions] = useFormState(schema, endpoint, onComplete, onError);

Parameters

Parameter	Type	Description
`schema`	`FormSchema \| null`	Form schema. Pass `null` while loading.
`endpoint`	`string`	Submission URL (`https://osforms.com/api/v1/f/{slug}`)
`onComplete`	`() => void`	Called after successful submission
`onError`	`(error: Error) => void`	Called when submission fails

FormState

Field	Type	Description
`answers`	`Record<string, unknown>`	Current field values keyed by field ID
`currentIndex`	`number`	Index of the active field in `visibleFields`
`direction`	`'forward' \| 'backward'`	Last navigation direction (use for slide animations)
`errors`	`Record<string, string>`	Validation errors per field ID. `_form` key holds submission errors.
`isSubmitting`	`boolean`	`true` while the POST is in flight
`isComplete`	`boolean`	`true` after successful submission
`showWelcome`	`boolean`	`true` when the welcome screen should be shown

FormStateActions

Field	Type	Description
`setAnswer`	`(fieldId, value) => void`	Update a field’s value and clear its error
`advance`	`(overrideValue?) => boolean`	Validate the current field (or `overrideValue`) and move to the next one. Returns `false` if validation failed. On the last field it doesn’t submit; call `submit()`
`back`	`() => void`	Move to the previous field
`submit`	`() => Promise<void>`	Validate all visible fields and POST to the endpoint. On a validation error it moves `currentIndex` to the first invalid field
`startForm`	`() => void`	Dismiss the welcome screen
`visibleFields`	`FormField[]`	Fields visible based on current answers and conditional logic
`currentField`	`FormField \| undefined`	The field at `state.currentIndex`

Example: custom renderer

import { useFormState, useFormSchema } from '@osforms/react';

function MyForm({ formSlug }: { formSlug: string }) {
  const { schema, loading } = useFormSchema(formSlug);
  const [state, actions] = useFormState(
    schema,
    `https://osforms.com/api/v1/f/${formSlug}`,
    () => alert('Submitted!'),
    (err) => alert(err.message)
  );

  if (loading) return <p>Loading...</p>;
  if (state.isComplete) return <p>Thanks!</p>;

  const field = actions.currentField;
  if (!field) return null;

  const isLast = state.currentIndex === actions.visibleFields.length - 1;

  return (
    <div>
      <label>{field.label}</label>
      <input
        value={(state.answers[field.id] as string) ?? ''}
        onChange={(e) => actions.setAnswer(field.id, e.target.value)}
      />
      {state.errors[field.id] && <p>{state.errors[field.id]}</p>}
      {isLast ? (
        <button onClick={() => actions.submit()} disabled={state.isSubmitting}>
          Submit
        </button>
      ) : (
        <button onClick={() => actions.advance()}>Next</button>
      )}
    </div>
  );
}

showWelcome is set from the schema on the hook’s first render. If the schema loads later (as with useFormSchema), the welcome screen won’t show. Render the component that calls useFormState only once the schema has loaded if you need the welcome screen.

The submission is JSON keyed by field id, covering visible non-statement fields. Unanswered fields are sent as "", and settings.source (if set) is sent as _source.

useFormSchema

Fetches a form schema from the OSForms API.

import { useFormSchema } from '@osforms/react';

const { schema, formName, redirectUrl, loading, error } = useFormSchema(
  'your-form-slug',
  'https://osforms.com' // optional baseUrl override
);

Return value

Field	Type	Description
`schema`	`FormSchema \| null`	Parsed form schema. `null` while loading, and also for forms with no builder schema.
`formName`	`string`	Display name of the form
`redirectUrl`	`string \| null`	Redirect URL configured in form settings
`loading`	`boolean`	`true` while the fetch is in flight
`error`	`string \| null`	Error message if the fetch failed

Fetches from: {baseUrl}/api/v1/f/{formId}/schema. Passing an empty formId skips the fetch and leaves loading as true.

Overview

Components

Advanced

useFormState

Parameters

FormState

FormStateActions

Example: custom renderer

useFormSchema

Return value

​useFormState

​Parameters

​FormState

​FormStateActions

​Example: custom renderer

​useFormSchema

​Return value

useFormState

Parameters

FormState

FormStateActions

Example: custom renderer

useFormSchema

Return value