S
Documentation

SurveyBuilder

A visual, drag-and-drop survey editor that lets users create and edit surveys without writing JSON. It outputs a standard SurveySchema and includes a live preview and JSON editor.

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 */
  showPreview?: boolean;
  /** Show the JSON editor panel */
  showJson?: boolean;
  /** Customize builder layout */
  layout?: 'horizontal' | 'vertical';
}
value

The current survey schema. Makes the builder a controlled component.

onChange

Callback fired whenever the schema changes. Receives the updated SurveySchema.

className

CSS class applied to the root builder container.

showPreview

When true, a live preview tab renders the survey in real-time. Defaults to true.

showJson

When true, a JSON editor tab shows the raw schema. Useful for debugging. Defaults to false.

layout

Controls the panel layout. 'horizontal' places panels side-by-side; 'vertical' stacks them.

Basic Usage

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

function BuilderPage() {
  const [schema, setSchema] = useState<SurveySchema>({
    id: 'new-survey',
    pages: [{ id: 'page1', questions: [] }],
  });

  return (
    <SurveyBuilder
      value={schema}
      onChange={setSchema}
      showPreview
      showJson
    />
  );
}

Tabs

The builder provides up to three tabs that let users switch between different views:

Editor

The main editing interface. Users can add pages, add questions, configure question properties (label, type, options, validation, visibility), and reorder items via drag-and-drop.

Preview

A live preview that renders the survey using SurveyRenderer. Users can interact with the preview to test navigation, validation, and conditional logic. Enabled via showPreview.

JSON

A raw JSON editor showing the current schema. Changes in the JSON editor are synced back to the visual editor. Enabled via showJson.

Drag & Drop

The builder uses native HTML5 drag-and-drop for reordering questions within a page and moving questions between pages. See the Drag & Drop page for details.

Question Editor

Clicking a question in the editor opens a panel where users can configure:

PropertyDescription
LabelThe question text shown to respondents
Typetext, textarea, radio, checkbox, select, number, email, date, rating
RequiredWhether the question must be answered
PlaceholderHint text inside the input
DescriptionHelp text below the label
OptionsChoices for radio, checkbox, and select types
ValidationValidation rules (minLength, maxLength, pattern, etc.)
Visible IfCondition expression for conditional display

Exporting the Schema

Export Schematsx
function BuilderWithExport() {
  const [schema, setSchema] = useState<SurveySchema>({
    id: 'my-survey',
    pages: [{ id: 'page1', questions: [] }],
  });

  const handleExport = () => {
    const json = JSON.stringify(schema, null, 2);
    // Save to API, download as file, copy to clipboard, etc.
    navigator.clipboard.writeText(json);
    alert('Schema copied to clipboard!');
  };

  return (
    <div>
      <SurveyBuilder value={schema} onChange={setSchema} showPreview />
      <button onClick={handleExport}>Export JSON</button>
    </div>
  );
}

Layout Options

Layouttsx
// Side-by-side panels (default)
<SurveyBuilder value={schema} onChange={setSchema} layout="horizontal" />

// Stacked panels
<SurveyBuilder value={schema} onChange={setSchema} layout="vertical" />

What's Next?