Skip to main content

​
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

ParameterTypeDescription
schemaFormSchema | nullForm schema. Pass null while loading.
endpointstringSubmission URL (https://osforms.com/api/v1/f/{slug})
onComplete() => voidCalled after successful submission
onError(error: Error) => voidCalled when submission fails

​
FormState

FieldTypeDescription
answersRecord<string, unknown>Current field values keyed by field ID
currentIndexnumberIndex of the active field in visibleFields
direction'forward' | 'backward'Last navigation direction (use for slide animations)
errorsRecord<string, string>Validation errors per field ID. _form key holds submission errors.
isSubmittingbooleantrue while the POST is in flight
isCompletebooleantrue after successful submission
showWelcomebooleantrue when the welcome screen should be shown

​
FormStateActions

FieldTypeDescription
setAnswer(fieldId, value) => voidUpdate a field’s value and clear its error
advance(overrideValue?) => booleanValidate current field and advance. Returns false if validation failed.
back() => voidMove to the previous field
submit() => Promise<void>Validate all fields and POST to the endpoint
startForm() => voidDismiss the welcome screen
visibleFieldsFormField[]Fields visible based on current answers and conditional logic
currentFieldFormField | undefinedThe 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;

  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>}
      <button onClick={() => actions.advance()}>Next</button>
    </div>
  );
}

​
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

FieldTypeDescription
schemaFormSchema | nullParsed form schema. null while loading.
formNamestringDisplay name of the form
redirectUrlstringRedirect URL configured in form settings
loadingbooleantrue while the fetch is in flight
errorstring | nullError message if the fetch failed
Fetches from: {baseUrl}/api/v1/f/{formId}/schema