SurveyBuilder — API Reference

Complete reference for the SurveyBuilder component — a visual survey editor with drag-and-drop, live preview, and JSON editing.

Import

import { SurveyBuilder } from 'react-minimal-survey-builder/builder';

Props

SurveyBuilderPropstypescript

interface SurveyBuilderProps {
  /** Current schema value (controlled) */
  value?: SurveySchema;
  /** Called when the schema changes */
  onChange?: (schema: SurveySchema) => void;
  /** Custom class name */
  className?: string;
  /** Show the live preview panel (default: true) */
  showPreview?: boolean;
  /** Show the JSON editor panel (default: false) */
  showJson?: boolean;
  /** Customize builder layout (default: 'horizontal') */
  layout?: 'horizontal' | 'vertical';
}

Props Detail

Prop	Type	Default	Description
`value`	`SurveySchema`	—	Controlled schema value
`onChange`	`(schema) => void`	—	Fires on every schema change
`className`	`string`	—	CSS class on root container
`showPreview`	`boolean`	true	Show the live preview tab
`showJson`	`boolean`	false	Show the JSON editor tab
`layout`	`'horizontal' \| 'vertical'`	'horizontal'	Panel arrangement

Internal State

BuilderStatetypescript

interface BuilderState {
  schema: SurveySchema;
  selectedQuestionId: string | null;
  selectedPageId: string | null;
  isDragging: boolean;
}

Builder Actions

BuilderActiontypescript

type BuilderAction =
  // Page management
  | { type: 'ADD_PAGE'; payload?: Partial<Page> }
  | { type: 'REMOVE_PAGE'; payload: { pageId: string } }
  | { type: 'UPDATE_PAGE'; payload: { pageId: string; updates: Partial<Page> } }
  | { type: 'REORDER_PAGES'; payload: { fromIndex: number; toIndex: number } }
  // Question management
  | { type: 'ADD_QUESTION'; payload: { pageId: string; question?: Partial<Question> } }
  | { type: 'REMOVE_QUESTION'; payload: { pageId: string; questionId: string } }
  | { type: 'UPDATE_QUESTION'; payload: { pageId: string; questionId: string; updates: Partial<Question> } }
  | { type: 'REORDER_QUESTIONS'; payload: { pageId: string; fromIndex: number; toIndex: number } }
  | { type: 'MOVE_QUESTION'; payload: { fromPageId: string; toPageId: string; fromIndex: number; toIndex: number } }
  // Selection
  | { type: 'SELECT_QUESTION'; payload: { questionId: string | null } }
  | { type: 'SELECT_PAGE'; payload: { pageId: string | null } }
  // Schema
  | { type: 'SET_SCHEMA'; payload: SurveySchema }
  | { type: 'SET_DRAGGING'; payload: boolean };

Tabs

Editor

The main visual editor. Add/remove pages and questions, configure properties, drag to reorder.

Preview

Live SurveyRenderer rendering the current schema. Controlled by showPreview prop.

JSON

Raw JSON view of the schema with editing capability. Controlled by showJson prop.

Controlled Usage

Controlled Usagetsx

import { useState } from 'react';
import { SurveyBuilder } from 'react-minimal-survey-builder/builder';
import type { SurveySchema } from 'react-minimal-survey-builder';

function App() {
  const [schema, setSchema] = useState<SurveySchema>({
    id: 'new-survey',
    title: 'My Survey',
    pages: [{ id: 'page1', title: 'Page 1', questions: [] }],
  });

  const handleSave = async () => {
    await fetch('/api/surveys', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(schema),
    });
  };

  return (
    <div>
      <SurveyBuilder
        value={schema}
        onChange={setSchema}
        showPreview
        showJson
        layout="horizontal"
      />
      <button onClick={handleSave}>Save Survey</button>
    </div>
  );
}

QuestionEditor

The QuestionEditor is an internal component used by the builder for the question configuration panel. It is also exported for advanced use cases:

QuestionEditortsx

import { QuestionEditor } from 'react-minimal-survey-builder/builder';

// Used internally to render the editing panel for a selected question.
// It handles label, type, required, placeholder, options, validation, and visibleIf editing.