@tour-kit/surveys

pnpm add @tour-kit/surveys

npm install @tour-kit/surveys

yarn add @tour-kit/surveys

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

const npsConfig = {
  id: 'nps-q1',
  type: 'nps',
  displayMode: 'modal',
  title: 'How likely are you to recommend us?',
  questions: [
    {
      id: 'score',
      type: 'rating',
      text: 'On a scale of 0 to 10, how likely are you to recommend us to a friend or colleague?',
      ratingScale: { min: 0, max: 10, labels: { min: 'Not at all likely', max: 'Extremely likely' } },
    },
  ],
  onComplete: (responses) => {
    console.log('NPS score:', responses.get('score'));
  },
};

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

  return (
    <>
      <SurveyModal surveyId="nps-q1" />
      <button onClick={survey.show}>Give feedback</button>
    </>
  );
}

export function App() {
  return (
    <SurveysProvider surveys={[npsConfig]}>
      <NPSTrigger />
    </SurveysProvider>
  );
}

frequency?: FrequencyRule
// 'once'                          — shows exactly once per user
// 'session'                       — once per session
// 'always'                        — every time show() is called (ignores cooldown)
// { type: 'times', count: 3 }     — show up to N times total
// { type: 'interval', days: 30 }  — show at most once every N days

{
  id: 'reason',
  type: 'single-select',
  text: 'What is your main reason for leaving?',
  options: [
    { value: 'price', label: 'Price' },
    { value: 'features', label: 'Missing features' },
    { value: 'other', label: 'Other' },
  ],
  skipLogic: [
    {
      questionId: 'reason',
      condition: (answer) => answer !== 'other',
      skipTo: 'confirm',   // jump over the free-text follow-up
    },
  ],
}

SurveysProvider
├── Context (useReducer)
│   ├── surveys Map<id, SurveyState>
│   ├── activeSurvey string | null
│   ├── queue string[]
│   └── Gate stack (sampling → cooldown → session → snooze → frequency)
├── Display components
│   ├── SurveyModal, SurveySlideout, SurveyBanner, SurveyPopover, SurveyInline
│   └── Each reads isVisible from SurveyState via useSurvey()
├── Question components
│   ├── QuestionRating, QuestionText, QuestionSelect, QuestionBoolean
│   └── SurveyProgress
├── Headless variants
│   └── HeadlessSurvey, HeadlessQuestion*
└── Scoring utilities
    └── calculateNPS, calculateCSAT, calculateCES