Qaid Get Started · Quests
Quests Embed ProtocolsSection 05
READY
> STEP-BY-STEP QUESTIONNAIRES // BRANCHING SUPPORTED

Install via npm

NPM
npm install @qaiddev/quests-embed
import { QaidQuests } from '@qaiddev/quests-embed';

new QaidQuests({
  endpoint: 'https://qaid.dev/api/quests/responses',
  apiKey: 'YOUR_API_KEY',
  configUrl: '/forms/intake.json',
  container: '#form',
});

Provide either configUrl (fetch the questionnaire JSON) or pass it inline via questionnaire.

Load via CDN

UNPKG
<!-- Load from unpkg CDN -->
<div id="form"></div>

<script
  src="https://unpkg.com/@qaiddev/quests-embed/dist/qaid-quests.umd.cjs"
  data-endpoint="https://qaid.dev/api/quests/responses"
  data-api-key="YOUR_API_KEY"
  data-config-url="/forms/intake.json"
  data-container="#form"
></script>

The script auto-initializes when it sees a data-endpoint attribute and either data-config-url or an inline JSON config tag.

Inline questionnaire

JSON CONFIG
<!-- Inline questionnaire — no extra fetch needed -->
<div id="form"></div>

<script type="application/json" data-quests-config>
{
  "endpoint": "https://qaid.dev/api/quests/responses",
  "apiKey": "YOUR_API_KEY",
  "container": "#form",
  "questionnaire": {
    "title": "Tell us about your project",
    "questions": [
      { "id": "name", "type": "text", "label": "Your name", "required": true },
      {
        "id": "stack",
        "type": "multiple-choice",
        "label": "Which stack are you using?",
        "options": [
          { "value": "react", "label": "React" },
          { "value": "vue",   "label": "Vue" },
          { "value": "svelte","label": "Svelte" }
        ]
      }
    ]
  }
}
</script>
<script src="https://unpkg.com/@qaiddev/quests-embed/dist/qaid-quests.umd.cjs"></script>

Question types: text, currency, range, date, multiple-choice. Answers autosave between steps.

Conditional follow-ups

BRANCHING

Questions can be gated on previous answers via visibleIf. Branching is purely declarative — no callbacks.

// Conditional follow-ups via `visibleIf` — questions that only
// appear when an earlier answer matches a predicate. Predicates may
// only reference questions that come EARLIER in the array.
{
  "questions": [
    {
      "id": "experience",
      "type": "multiple-choice",
      "label": "How was your experience?",
      "options": [
        { "value": "good", "label": "Good" },
        { "value": "bad",  "label": "Bad"  }
      ]
    },
    {
      "id": "what_went_wrong",
      "type": "text",
      "label": "Sorry to hear. What went wrong?",
      "visibleIf": { "questionId": "experience", "equals": "bad" }
    },
    {
      "id": "what_loved",
      "type": "text",
      "label": "What did you like most?",
      "visibleIf": { "questionId": "experience", "equals": "good" }
    }
  ]
}

AND / OR composition

ADVANCED
// Combine conditions with allOf (AND) / anyOf (OR).
// Operators: equals, notEquals, in, answered.
{
  "id": "deep_dive",
  "type": "text",
  "label": "Tell us more about the issue.",
  "visibleIf": {
    "allOf": [
      { "questionId": "experience", "equals": "bad" },
      { "questionId": "severity",   "in": ["high", "critical"] }
    ]
  }
}

Configuration Options

REFERENCE
OptionTypeDefaultDescription
endpointstring-Required. URL responses are POSTed/PATCHed to.
apiKeystring-API key sent as X-API-Key on every request.
configUrlstring-URL to fetch the questionnaire JSON (alternative to inline questionnaire).
questionnaireobject-Inline questionnaire definition (takes precedence over configUrl).
containerstring-CSS selector for inline container. If absent, opens as a centered modal.
colorsobject-Theme colors. Same names as thumbs-embed for theme reuse.
colors.positivestring"#10b981"Primary accent (progress / focus / submit).
colors.negativestring"#ef4444"Error / destructive color.
colors.markerstring"#6366f1"Selection / highlight color.
modalWidthnumber480Modal width in pixels (modal mode only).
backdropOpacitynumber0.4Backdrop opacity (0–1).
fontFamilystring"system-ui…"Font family for the embed UI.
fontSizenumber16Base font size in pixels.
autoAdvancebooleanfalseAdvance automatically on selection (single-choice + range).
saveDebounceMsnumber500Debounce for autosave on text + currency inputs.
progressPositionstring"top"Where the step counter / progress bar renders ("top" or "bottom").
cssstring-Custom CSS injected into the shadow root for theming.
Quests Online