The headless questionnaire
engine for the web.

useQuestionnaire hook

Every value in the returned object is reactive. Pass answer(value) directly to your input's onChange. Call next() to advance — it validates required fields first and populates errors if invalid.

import { useQuestionnaire } from '@questify/core/react';

const questions = [
  {
    id: 'age',
    text: 'How old are you?',
    type: 'number',
    required: true,
    validation: { min: 18, max: 99 },
  },
  {
    id: 'smoker',
    text: 'Do you currently smoke?',
    type: 'boolean',
    required: true,
  },
  // Only shown when age >= 50 AND smoker = true
  {
    id: 'chest_scan',
    text: 'Have you had a chest CT scan in the last 2 years?',
    type: 'boolean',
    showIf: {
      and: [
        { questionId: 'age',    value: 50, operator: 'gte' },
        { questionId: 'smoker', value: true },
      ],
    },
  },
];

export function HealthForm() {
  const {
    question,      // current Question object
    questionIndex, // 0-based step index
    totalQuestions,// total visible questions (conditional ones resolved)
    progress,      // 0–1 float for progress bar
    responses,     // { [questionId]: value }
    isComplete,    // all required visible questions answered
    errors,        // { [questionId]: errorMessage }
    canGoBack,
    canGoNext,
    answer,        // answer(value) — call on every input change
    next,          // advance (validates required before moving)
    back,
    reset,
  } = useQuestionnaire({ questions });

  return (
    <div>
      <progress value={progress} max={1} />
      <p>Step {questionIndex + 1} of {totalQuestions}</p>

      <h2>{question?.text}</h2>
      {/* Render your own input based on question.type */}

      <button onClick={back}  disabled={!canGoBack}>Back</button>
      {canGoNext
        ? <button onClick={next}>Next</button>
        : <button disabled={!isComplete}>Submit</button>
      }
    </div>
  );
}

Questionnaire class

The raw state machine. Framework adapters are thin wrappers around this. Subscribe to state changes with a callback — returns an unsubscribe function.

import { Questionnaire } from '@questify/core';

const q = new Questionnaire({ questions });

const unsubscribe = q.subscribe((state) => {
  console.log('Step:', state.questionIndex + 1, '/', state.totalQuestions);
  console.log('Current question:', state.question?.text);
  console.log('Visible questions:', state.visibleQuestions.length);
  console.log('Progress:', Math.round(state.progress * 100) + '%');
});

// Answer the current question
q.answer('Alice');

// Move forward (validates required fields first)
q.next();

// Jump to a specific step
q.jumpTo(3);

// Tear down
unsubscribe();

State shape

Everything returned by useQuestionnaire or emitted by subscribe().