SurveyJS React UI

Common errors

• TypeError: Objects are not valid as a React child (found: object with keys {text, value, isNew, locText, locValue, question, getBaseValue, isSelected, itemValue, selected, isDisabled, onPropertyChanged, getType, locManager, getType...})

  cause Attempting to render an instance of `Survey.Model` directly within JSX instead of passing it as a prop to the `Survey` React component.
  fix Ensure you pass the `Survey.Model` instance to the `model` prop of the `<Survey />` component: `<Survey model={mySurveyModel} />`. Do not try to render `{mySurveyModel}` directly.

• Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined. You likely forgot to export your component from the file it's defined in, or you might have mixed up default and named imports.

  cause This usually indicates that the `Survey` component was not imported correctly, often due to mixing CommonJS `require()` with ES Modules `import`, or an incorrect path.
  fix Use the correct ES Module named import: `import { Survey } from 'survey-react-ui';`. If using CommonJS, ensure your bundler handles it correctly, or use `const { Survey } = require('survey-react-ui');` (though ESM is recommended).

• Module not found: Error: Can't resolve 'survey-react-ui/styles/default.css'

  cause Incorrect or outdated path for the SurveyJS CSS theme import. Theme paths and names might change between major versions or be misspelled.
  fix Verify the exact path and filename for the desired SurveyJS theme. For v2, common paths are `survey-core/defaultV2.min.css` or `survey-core/modern.min.css`. Update your import statement accordingly.

Warnings

• breaking Upgrading from SurveyJS v1 (packages like `survey-react`) to v2 (`survey-react-ui`, `survey-core`) involves significant breaking changes to the JSON schema, API, and styling system. A direct upgrade without code modifications will lead to errors.
  Fix: Consult the official SurveyJS migration guides (e.g., 'Migrate from v1 to v2') for detailed instructions on updating your JSON, component usage, and custom logic.
• gotcha The `survey-react-ui` package is strictly for the React UI component. The core survey logic and model (`Model` class, `StylesManager`, etc.) reside in the `survey-core` package. Accidentally importing `Model` or `StylesManager` from `survey-react-ui` will result in runtime errors or incorrect behavior.
  Fix: Always import core classes like `Model` and `StylesManager` from `survey-core`. For example: `import { Model } from 'survey-core';`.
• gotcha The SurveyJS UI components require a CSS theme to be imported for proper rendering and styling. Without importing a theme, the survey will appear unstyled, often with misaligned elements.
  Fix: Ensure you import a SurveyJS theme stylesheet in your application, typically in your main component or entry file. For example: `import 'survey-core/defaultV2.min.css';` or `import 'survey-core/modern.min.css';`.
• gotcha The `survey-react-ui` package declares `react` and `react-dom` as peer dependencies. Incompatible versions of React in your project (outside the supported ranges like `^16.5.0 || ^17.0.1 || ^18.1.0 || ^19.0.0`) can lead to build failures or unexpected runtime issues.
  Fix: Verify that your project's `react` and `react-dom` versions satisfy the peer dependency requirements of `survey-react-ui`. Update your React versions if necessary, or consider using a compatible version of `survey-react-ui`.

Install

• npm install survey-react-ui npm
• yarn add survey-react-ui yarn
• pnpm add survey-react-ui pnpm

Imports

• Survey
  wrong:

  const Survey = require('survey-react-ui').Survey;

  correct:

  import { Survey } from 'survey-react-ui';

  This is the primary React component for rendering a survey. Prefer named import for ESM.
• Model
  wrong:

  import { Model } from 'survey-react-ui';

  correct:

  import { Model } from 'survey-core';

  The core survey model class is part of `survey-core`, not `survey-react-ui`. Importing from the wrong package is a common mistake.
• StylesManager
  wrong:

  import { StylesManager } from 'survey-react-ui';

  correct:

  import { StylesManager } from 'survey-core';

  Styling and theme management utility; like Model, it resides in `survey-core`. Users often confuse this with `survey-react-ui`.

Quickstart

This quickstart demonstrates how to initialize a SurveyJS `Model` from a JSON definition and render it using the `Survey` React component. It includes basic state management for displaying results after completion and highlights the necessary CSS import for styling.

import React, { useState, useEffect } from 'react';
import { Survey } from 'survey-react-ui';
import { Model } from 'survey-core';
import 'survey-core/defaultV2.min.css'; // Or 'survey-core/modern.min.css'

const surveyJson = {
  title: 'Sample Survey',
  description: 'Please answer the following questions.',
  pages: [
    {
      name: 'page1',
      elements: [
        {
          type: 'text',
          name: 'name',
          title: 'What is your name?',
          isRequired: true
        },
        {
          type: 'dropdown',
          name: 'country',
          title: 'Which country do you live in?',
          choices: ['USA', 'Canada', 'Mexico', 'Germany', 'France'],
          isRequired: true
        }
      ]
    },
    {
      name: 'page2',
      elements: [
        {
          type: 'comment',
          name: 'feedback',
          title: 'Any additional feedback?'
        }
      ]
    }
  ]
};

export default function MySurveyComponent() {
  const [surveyModel, setSurveyModel] = useState(null);
  const [surveyResults, setSurveyResults] = useState(null);

  useEffect(() => {
    const model = new Model(surveyJson);
    model.onComplete.add((sender, options) => {
      console.log('Survey results:', sender.data);
      setSurveyResults(sender.data);
      // In a real app, you would send sender.data to your backend
    });
    setSurveyModel(model);
  }, []);

  if (!surveyModel) {
    return <div>Loading survey...</div>;
  }

  return (
    <div>
      {surveyResults ? (
        <div>
          <h2>Thank you for completing the survey!</h2>
          <pre>{JSON.stringify(surveyResults, null, 2)}</pre>
        </div>
      ) : (
        <Survey model={surveyModel} />
      )}
    </div>
  );
}