@tour-kit/surveysHooks
useSurvey
Access and control a single survey by id — show, hide, dismiss, snooze, answer questions, and navigate between steps
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.
Related
- useSurveys — Access the full context
- SurveysProvider — Configure fatigue rules
- SurveyState type — Full state shape