Types — API Reference

Complete TypeScript type reference for react-minimal-survey-builder. All types are exported from the main entry point.

Import

import type {
  SurveySchema, Page, Question, QuestionType,
  Option, AnswerValue, FileAnswer, SurveyAnswers,
  ValidationRule, ValidationRuleType, ValidationError,
  SurveySettings, SurveyOptions,
  QuestionComponentProps, QuestionComponents,
  SurveyPlugin, SurveyState, SurveyEvent,
  BuilderState, BuilderAction,
} from 'react-minimal-survey-builder';

SurveySchema

SurveySchematypescript

interface SurveySchema {
  id: string;
  title?: string;
  description?: string;
  pages: Page[];
  settings?: SurveySettings;
}

Page

Pagetypescript

interface Page {
  id: string;
  title?: string;
  description?: string;
  questions: Question[];
  visibleIf?: string;
}

Question

Questiontypescript

interface Question {
  id: string;
  type: QuestionType;
  label: string;
  description?: string;
  placeholder?: string;
  required?: boolean;
  defaultValue?: AnswerValue;
  options?: Option[];
  validation?: ValidationRule[];
  visibleIf?: string;
  meta?: Record<string, unknown>;
  // File upload
  accept?: string;
  maxFiles?: number;
  maxFileSize?: number;
  maxTotalSize?: number;
}

QuestionType

QuestionTypetypescript

type BuiltInQuestionType =
  | 'text'
  | 'textarea'
  | 'radio'
  | 'checkbox'
  | 'select'
  | 'number'
  | 'email'
  | 'phone'
  | 'url'
  | 'password'
  | 'date'
  | 'time'
  | 'datetime'
  | 'slider'
  | 'rating'
  | 'boolean'
  | 'file';

// Allows custom string types
type QuestionType = BuiltInQuestionType | (string & {});

Option

Optiontypescript

interface Option {
  label: string;
  value: string;
}

AnswerValue & SurveyAnswers

AnswerValue & SurveyAnswerstypescript

type AnswerValue =
  | string
  | string[]
  | number
  | boolean
  | FileAnswer[]
  | null
  | undefined;

type SurveyAnswers = Record<string, AnswerValue>;

FileAnswer

Returned as an array in AnswerValue when a question with type: 'file' is answered. The file property is the raw browser File object and is not JSON-serialisable.

FileAnswertypescript

interface FileAnswer {
  /** Original filename */
  name: string;
  /** File size in bytes */
  size: number;
  /** MIME type, e.g. "application/pdf" */
  type: string;
  /** Last-modified timestamp (ms since epoch) */
  lastModified: number;
  /** Raw browser File — upload in onSubmit, cannot be JSON-serialised */
  file: File;
}

Validation

Validation Typestypescript

type ValidationRuleType =
  | 'required'
  | 'minLength'
  | 'maxLength'
  | 'pattern'
  | 'min'
  | 'max'
  | 'email'
  | 'custom';

interface ValidationRule {
  type: ValidationRuleType;
  value?: string | number | RegExp;
  message?: string;
  validator?: (value: AnswerValue, question: Question, answers: SurveyAnswers) => boolean | string;
}

interface ValidationError {
  questionId: string;
  message: string;
  rule: ValidationRuleType;
}

SurveySettings

SurveySettingstypescript

interface SurveySettings {
  showProgress?: boolean;
  allowBack?: boolean;
  validateOnPageChange?: boolean;
  showQuestionNumbers?: boolean;
  submitText?: string;
  nextText?: string;
  prevText?: string;
}

SurveyOptions

SurveyOptionstypescript

interface SurveyOptions {
  initialAnswers?: SurveyAnswers;
  onChange?: (answers: SurveyAnswers, questionId: string) => void;
  onSubmit?: (answers: SurveyAnswers) => void | Promise<void>;
  onValidate?: (errors: ValidationError[]) => void;
  onPageChange?: (pageIndex: number) => void;
  validators?: Record<string, (value: AnswerValue, question: Question, answers: SurveyAnswers) => string | null>;
}

Component Types

Component Typestypescript

type QuestionComponentProps<V = AnswerValue> = {
  question: Question;
  value: V;
  onChange: (value: V) => void;
  error?: string;
  disabled?: boolean;
};

type QuestionComponents = Partial<
  Record<QuestionType, React.ComponentType<QuestionComponentProps>>
>;

SurveyPlugin

SurveyPlugintypescript

interface SurveyPlugin {
  name: string;
  questionTypes?: Record<string, React.ComponentType<QuestionComponentProps>>;
  validators?: Record<string, (value: AnswerValue, question: Question, answers: SurveyAnswers) => string | null>;
  middleware?: (event: SurveyEvent, next: () => void) => void;
}

Event Types

Event Typestypescript

type SurveyEventType =
  | 'answerChanged'
  | 'pageChanged'
  | 'validated'
  | 'submitted'
  | 'questionVisibilityChanged';

interface SurveyEvent<T = unknown> {
  type: SurveyEventType;
  payload: T;
  timestamp: number;
}

type SurveyEventHandler<T = unknown> = (event: SurveyEvent<T>) => void;

SurveyState

SurveyStatetypescript

interface SurveyState {
  answers: SurveyAnswers;
  currentPageIndex: number;
  errors: ValidationError[];
  isValid: boolean;
  isSubmitted: boolean;
  visibleQuestionIds: Set<string>;
}

Builder Types

Builder Typestypescript

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

type BuilderAction =
  | { type: 'ADD_PAGE'; payload?: Partial<Page> }
  | { type: 'REMOVE_PAGE'; payload: { pageId: string } }
  | { type: 'UPDATE_PAGE'; payload: { pageId: string; updates: Partial<Page> } }
  | { 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: 'REORDER_PAGES'; payload: { fromIndex: number; toIndex: number } }
  | { type: 'MOVE_QUESTION'; payload: { fromPageId: string; toPageId: string; fromIndex: number; toIndex: number } }
  | { type: 'SELECT_QUESTION'; payload: { questionId: string | null } }
  | { type: 'SELECT_PAGE'; payload: { pageId: string | null } }
  | { type: 'SET_SCHEMA'; payload: SurveySchema }
  | { type: 'SET_DRAGGING'; payload: boolean };