Introduction

@osforms/react is the official React SDK for OSForms. It renders forms designed in the dashboard’s Builder tab, or forms you define locally, in two modes:

Conversational: one field at a time, Typeform-style, with animated transitions
Classic: all fields on one page, standard form layout

Installation

npm install @osforms/react

Basic usage

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

export default function ContactPage() {
  return (
    <OSForm
      formId="your-form-slug"
      mode="conversational"
      fullScreen
      onComplete={() => console.log('submitted!')}
    />
  );
}

formId is the form’s slug. The schema is fetched from https://osforms.com/api/v1/f/{formId}/schema.

The form needs a schema saved in the Builder tab. For a form without one, the schema endpoint returns schema: null and OSForm renders nothing.

Local schema

Pass a schema directly. No schema fetch is needed:

import { OSForm } from '@osforms/react';
import type { FormSchema } from '@osforms/react';

const schema: FormSchema = {
  mode: 'classic',
  fields: [
    { id: 'email', type: 'email', label: 'Email', required: true },
    { id: 'message', type: 'textarea', label: 'Message', required: true },
  ],
};

export default function ContactPage() {
  return (
    <OSForm schema={schema} endpoint="https://osforms.com/api/v1/f/your-slug" />
  );
}

What’s included

Export	Description
`OSForm`	Main component. Fetches the schema and renders the form
`ConversationalRenderer`	Low-level conversational mode renderer
`ClassicRenderer`	Low-level classic mode renderer
`useFormState`	Core state hook: answers, navigation, submission
`useFormSchema`	Schema fetching hook
Types	`FormSchema`, `FormField`, `FieldType`, `FieldConfig`, `FieldOption`, `FieldValidation`, `ConditionalLogic`, `FormMode`, `FormTheme`, `WelcomeScreen`, `ThankYouScreen`, `OSFormProps`, `FormState`, `FormStateActions`

Modes overview

Conversational

<OSForm formId="abc123" mode="conversational" fullScreen />

One field displayed at a time
Enter to advance (Cmd/Ctrl+Enter in a textarea); ↑/↓ buttons to move back and forward
Animated field transitions (framer-motion, installed as a dependency)
Auto-advances on selection for radio, select, rating, and scale fields

Classic

<OSForm formId="abc123" mode="classic" />

All visible fields on one page
Standard form layout
Submit button at the bottom
Inline error under each invalid field

Both modes support welcome and thank-you screens. A stepped mode exists in the types but currently renders the conversational layout.

Overview

Components

Advanced

Installation

Basic usage

Local schema

What’s included

Modes overview

Conversational

Classic

​Installation

​Basic usage

​Local schema

​What’s included

​Modes overview

​Conversational

​Classic

Installation

Basic usage

Local schema

What’s included

Modes overview

Conversational

Classic