Quests Embed ProtocolsSection 05
READY> STEP-BY-STEP QUESTIONNAIRES // BRANCHING SUPPORTED
Install via npm
NPMnpm install @qaiddev/quests-embedimport { 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
BRANCHINGQuestions 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| Option | Type | Default | Description |
|---|---|---|---|
| endpoint | string | - | Required. URL responses are POSTed/PATCHed to. |
| apiKey | string | - | API key sent as X-API-Key on every request. |
| configUrl | string | - | URL to fetch the questionnaire JSON (alternative to inline questionnaire). |
| questionnaire | object | - | Inline questionnaire definition (takes precedence over configUrl). |
| container | string | - | CSS selector for inline container. If absent, opens as a centered modal. |
| colors | object | - | Theme colors. Same names as thumbs-embed for theme reuse. |
| colors.positive | string | "#10b981" | Primary accent (progress / focus / submit). |
| colors.negative | string | "#ef4444" | Error / destructive color. |
| colors.marker | string | "#6366f1" | Selection / highlight color. |
| modalWidth | number | 480 | Modal width in pixels (modal mode only). |
| backdropOpacity | number | 0.4 | Backdrop opacity (0–1). |
| fontFamily | string | "system-ui…" | Font family for the embed UI. |
| fontSize | number | 16 | Base font size in pixels. |
| autoAdvance | boolean | false | Advance automatically on selection (single-choice + range). |
| saveDebounceMs | number | 500 | Debounce for autosave on text + currency inputs. |
| progressPosition | string | "top" | Where the step counter / progress bar renders ("top" or "bottom"). |
| css | string | - | Custom CSS injected into the shadow root for theming. |
Quests Online