SurveyJS Form Library Core

SurveyJS Form Library Core is a free and open-source, framework-independent package that provides the form model and core logic used by SurveyJS rendering packages.

The survey-core package handles form structure, validation, conditional logic, calculations, navigation, localization, response data, and other framework-independent behavior. It does not render the form UI itself. To display forms in an application, use it together with one of the framework-specific rendering packages below. Installing survey-core alone is the most common reason a survey never appears on the page.

A typical integration creates a form model from a SurveyJS JSON form definition with survey-core and passes that model to the appropriate rendering component. The renderer displays the form and stays synchronized with the model as users interact with it.

Use survey-core when you need to work directly with SurveyJS form models, form logic, response data, or shared functionality independently of a particular UI framework.

Installation

Install the UI package for your framework — survey-core comes with it as a dependency:

npm install survey-react-ui   # React
npm install survey-angular-ui # Angular
npm install survey-vue3-ui    # Vue 3
npm install survey-js-ui      # HTML/CSS/JavaScript

To add the model on its own (for example, in code shared between a UI layer and a Node.js service):

npm install survey-core

Usage

import { Model } from "survey-core";
import "survey-core/survey-core.css";

const surveyJson = {
  elements: [
    { name: "firstName", title: "Enter your first name:", type: "text" },
    { name: "satisfaction", title: "How satisfied are you?", type: "rating" }
  ]
};

const survey = new Model(surveyJson);
survey.onComplete.add((sender) => {
  console.log(JSON.stringify(sender.data, null, 2));
});

Pass the survey instance to the component from your UI package to render it — for example, <Survey model={survey} /> in React. See the Get Started tutorial for your framework in the table below.

survey-core/survey-core.css applies the Default theme; survey-core/survey-core.min.css is the minified build. Other predefined themes are imported from survey-core/themes — refer to Themes & Styles.

Theme Adapters

Themes are built on --sjs2-* CSS custom properties (design tokens). A theme adapter maps an existing design system's variables onto those tokens, so an embedded survey inherits the look of the host application instead of being restyled by hand. Adapters ship with survey-core as plain CSS — import one after the base style sheet:

import "survey-core/survey-core.css";
import "survey-core/themes/adapters/bootstrap-default.css";

Adapters are available for Bootstrap, Material UI (mui.css), shadcn/ui (shadcn-default.css, shadcn-new-york.css), and Tailwind CSS v4 (tailwind4.css). Bootstrap additionally ships Bootswatch variants — bootstrap-darkly.css, bootstrap-flatly.css, and others. Because adapters read the host system's live variables, any Bootstrap or Bootswatch build re-skins the survey automatically. Matching icon sets are optional side-effect imports:

import "survey-core/themes/adapters/icons/lucide"; // or ".../icons/mui"

Adapters are framework-independent and require no extra markup or configuration. See Theme Adapters.

Use on the Server (Node.js)

survey-core has no DOM dependency and imports cleanly in Node (both require and ESM import), so the same model that renders in the browser can run on the server. Use it to re-validate a submitted response, evaluate conditional logic, or inspect and transform a survey JSON definition — no UI package and no CSS import required.

const { Model } = require("survey-core");

const survey = new Model(surveyJson);
survey.data = submittedAnswers;

if (!survey.validate(true, false)) {
  const errors = survey.getAllQuestions()
    .filter((q) => q.errors.length > 0)
    .map((q) => ({ question: q.name, messages: q.errors.map((e) => e.getText()) }));
  // Reject the submission and return `errors` to the client.
}

Client-side validation can always be bypassed, so re-running it on the server with the same schema is the point: isRequired, validators, and visibleIf behave identically in both places. survey.getPlainData() gives a flat, display-ready view of the answers for storage, export, or reporting, and Serializer lets you inspect or modify the JSON definition programmatically.

To get validation messages in a specific locale, load it and set locale:

require("survey-core/i18n/french");
survey.locale = "fr";

Server-Side Rendering (SSR)

The same DOM-free design makes SSR work: a survey can be pre-rendered on the server with survey-react-ui and hydrated on the client. HTML id attributes are generated deterministically per survey instance, so the server and client produce matching markup. If you render multiple surveys on one page, assign a unique elementIdPrefix to each model so their id attributes don't collide.

Key Features

Core Form Model

• Framework-independent form model for SurveyJS Form Library
• Create and manage forms from SurveyJS JSON definitions
• Manage form structure, state, and response data

Logic and Validation

• Conditional visibility, branching, and calculated values
• Expression-based logic and custom functions
• Built-in and custom validation

Navigation and Localization

• Multi-page navigation and progress tracking
• Multi-language forms and runtime locale switching
• Right-to-left language support

Extensibility

• Event-driven API for custom form behavior
• Custom question types and properties
• Shared core for survey-react-ui, survey-angular-ui, survey-vue3-ui, and survey-js-ui

Related Packages

| Framework | UI package | Get Started | | --- | --- | --- | | React | survey-react-ui | Tutorial | | Angular | survey-angular-ui | Tutorial | | Vue 3 | survey-vue3-ui | Tutorial | | HTML/CSS/JavaScript | survey-js-ui | Tutorial |

Documentation

• Website
• Documentation
• Form Library Overview
• Form Library Demos
• Release Notes
• Roadmap
• What's New

For AI coding agents: https://surveyjs.io/llms.txt indexes the documentation. Any documentation page is also available as raw Markdown — append .md to its URL, for example https://surveyjs.io/form-library/documentation/overview.md.

SurveyJS Ecosystem

| Product | Purpose | License | | --- | --- | --- | | Form Library | Render dynamic forms from JSON (this package) | MIT | | Survey Creator | Drag-and-drop form builder UI | Commercial | | Dashboard | Visualize and analyze collected results | Commercial | | PDF Generator | Render forms and responses as PDF | Commercial | | AI Form Response Extractor | Extract responses from paper forms, PDFs, and images into a SurveyJS schema (ai-form-response-extractor) | MIT |

Build from Source

This monorepo does not use npm workspaces — each package installs and builds independently, but a root install is still required for the shared tooling (linting, Playwright).

1. Clone the repo and install shared dependencies

   git clone https://github.com/surveyjs/survey-library.git
   cd survey-library
   npm install

   Requires Node.js 20 or later — CI builds on Node 20.x and 22.x.

2. Install and build survey-core

   cd packages/survey-core
   npm install
   npm run build:all

   Build output goes to the build directory. npm run build produces the JS bundle alone; npm run build:all adds i18n, themes, icons, and adapters. Use npm run watch:dev while developing.

   Every UI package resolves survey-core from ../survey-core/build, so survey-core must be built before you build or test any UI package.

3. Run unit tests

   Unit tests use Vitest in a jsdom environment and live in packages/survey-core/tests.

   npm run test                          # whole suite
   npm run test:watch                    # watch mode
   npx vitest run tests/surveytests.ts   # a single file
   npx vitest run -t "visibleIf"         # tests whose name matches a substring

4. Run end-to-end tests

   E2E, visual-regression, and accessibility tests are Playwright suites shared by all UI packages and run from a UI package directory (after survey-core is built). Angular and Vue 3 additionally need their example app built first (npm run build:example:prod). Do not start an HTTP server yourself — the Playwright config starts its own.

   cd packages/survey-react-ui
   npm install
   npm run e2e:ci                        # e2e
   npm run e2e:ci -- --grep "TestName"   # a single test
   npm run scr:ci                        # visual regression
   npm run accessibility-tests:ci        # accessibility

5. Build a UI package

   • Angular Form Library
   • React Form Library
   • Vue Form Library
   • HTML/CSS/JS Form Library

Licensing

SurveyJS Form Library is distributed under the MIT license.