Skip to main content
userTourKit
@tour-kit/surveysHooks

useSurvey

Access and control a single survey by id — show, hide, dismiss, snooze, answer questions, and navigate between steps

domidex01Published Updated

The primary hook for working with a specific survey. Returns both the current state snapshot and all action functions for that survey.

Import

import { useSurvey } from '@tour-kit/surveys';

Usage

import { useSurvey, SurveyModal, QuestionRating } from '@tour-kit/surveys';

function NPSSurvey() {
  const survey = useSurvey('nps-q1');

  return (
    <>
      <button
        onClick={survey.show}
        disabled={!survey.canShow}
      >
        Share feedback
      </button>

      <SurveyModal surveyId="nps-q1">
        <QuestionRating
          id="score"
          label="How likely are you to recommend us?"
          min={0}
          max={10}
          value={survey.state?.responses.get('score') as number ?? null}
          onChange={(value) => {
            survey.answer('score', value);
            survey.complete();
          }}
        />
      </SurveyModal>
    </>
  );
}

Parameters

Prop

Type

Returns

Prop

Type

Examples

Show a survey programmatically

function PostCheckoutPrompt() {
  const survey = useSurvey('post-checkout-csat');

  useEffect(() => {
    // Only show if the gate stack allows it
    if (survey.canShow) {
      survey.show();
    }
  }, [survey]);

  return null;
}

Multi-step navigation

function SteppedSurvey() {
  const survey = useSurvey('onboarding-survey');
  const currentStep = survey.state?.currentStep ?? 0;
  const questions = survey.config?.questions ?? [];
  const question = questions[currentStep];

  if (!survey.state?.isVisible || !question) return null;

  return (
    <div>
      <p>{question.text}</p>

      <button
        onClick={survey.prevQuestion}
        disabled={currentStep === 0}
      >
        Back
      </button>

      {currentStep < questions.length - 1 ? (
        <button onClick={survey.nextQuestion}>Next</button>
      ) : (
        <button onClick={survey.complete}>Submit</button>
      )}
    </div>
  );
}

Dismissal with reason

function SurveyWithSnooze() {
  const survey = useSurvey('nps-q1');

  return (
    <div>
      {/* survey content */}
      <button onClick={() => survey.dismiss('close_button')}>Close</button>
      <button onClick={survey.snooze}>Remind me later</button>
    </div>
  );
}

answer() persists each response to storage immediately, not on complete(). If the user closes the browser mid-survey, their partial answers survive to the next session. Read state.responses on mount if you need to restore a partially completed survey.