Introduction

@osforms/react is the official React SDK for osforms. It renders forms fetched from the osforms API — 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!')}
    />
  );
}

The formId prop fetches the form schema automatically from https://osforms.com/api/v1/f/{formId}/schema.

Headless usage

Pass a schema directly — no API fetch required:

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 — renders full form with schema fetch
`ConversationalRenderer`	Low-level conversational mode renderer
`ClassicRenderer`	Low-level classic mode renderer
`useFormState`	Core state hook — answers, navigation, submission
`useFormSchema`	Schema fetching hook
All types from `@osforms/types`	`FormSchema`, `FormField`, `FormTheme`, etc.

Modes overview

Conversational

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

One field displayed at a time
Keyboard navigation (Enter to advance, Backspace to go back)
Animated field transitions (framer-motion, bundled as a dependency)
Auto-advances on selection for radio, rating, and scale fields (configurable)
Welcome and thank-you screens supported

Classic

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

All visible fields on one page
Standard form layout
Submit button at the bottom
Scrolls to first error on validation failure

Overview

Components

Advanced

Installation

Basic usage

Headless usage

What’s included

Modes overview

Conversational

Classic

​Installation

​Basic usage

​Headless usage

​What’s included

​Modes overview

​Conversational

​Classic

Installation

Basic usage

Headless usage

What’s included

Modes overview

Conversational

Classic