@sensefolks/userchoice

v4.0.1

Published

6 days ago

Deeply understand user preferences. Design better offerings or refine existing ones

0High
0Medium
0Low

survey choice userchoice ab-testing web-component stencil custom-element feedback questionnaire preference accessible wcag a11y sensefolks

@sensefolks/userchoice

A web component for running choice-based preference research surveys. Embed multi-task choice surveys to understand what users value and make better product decisions.

How it works

Each respondent sees a series of choice tasks. Each task presents product alternatives (each with a different combination of attribute values) plus a "None of these options" choice. After completing all tasks, the response data is submitted for analysis.

Step flow

The survey progresses through the following steps, matching the SurveyStep enum in the component source:

CHOICE_TASK — The respondent completes a series of choice tasks, selecting their preferred alternative in each task.
SURVEY_FIELDS — (Optional) If Survey Fields are configured, the respondent answers them before submission.
COMPLETION — A confirmation screen is shown with the saved survey thank-you message.

Installation

CDN

<!DOCTYPE html>
<html lang="en">
  <head>
    <script type="module" src="https://unpkg.com/@sensefolks/[email protected]/dist/sf-userchoice/sf-userchoice.esm.js"></script>
  </head>
  <body>
    <sf-userchoice survey-key="your-survey-uuid-here"></sf-userchoice>
  </body>
</html>

Or via jsDelivr:

<script type="module" src="https://cdn.jsdelivr.net/npm/@sensefolks/[email protected]/dist/sf-userchoice/sf-userchoice.esm.js"></script>

NPM

npm install @sensefolks/userchoice

Usage

Vanilla JS

<script type="module">
  import '@sensefolks/userchoice';
</script>

<sf-userchoice survey-key="a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"></sf-userchoice>

React

import '@sensefolks/userchoice';

export function SurveyPage() {
  return <sf-userchoice survey-key="a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" />;
}

Vue

<template>
  <sf-userchoice survey-key="a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" />
</template>

<script setup>
import '@sensefolks/userchoice';
</script>

Angular

In main.ts:

import '@sensefolks/userchoice';

In your component template:

<sf-userchoice survey-key="a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"></sf-userchoice>

In your AppModule:

import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

Framework Notes

React + Next.js: use the React snippet above. In Next.js, render surveys inside a 'use client' component.
Vue + Nuxt: use the Vue snippet above. In Nuxt pages that SSR, wrap the survey with <ClientOnly>.
Svelte: load the package inside onMount and render the same sf-* tag.
Astro: keep the sf-* tag in markup and load the package with a client-side module import.
Vanilla JS: use the HTML/CDN snippet or a module import in a <script type="module"> block.

For complete copy-paste examples, see: https://sensefolks.com/docs/tutorials/embedding-a-survey/

API Reference

Properties

| Property | Attribute | Type | Default | Required | Description | | ------------------- | -------------------- | -------- | -------------------------------- | -------- | ----------------------------------------------------------------------- | | surveyKey | survey-key | string | — | Yes | The survey's public key (UUID). Obtained from the SenseFolks dashboard. | | completionMessage | completion-message | string | "Thank you for your response!" | No | Fallback message shown after submission when the survey has no saved thank-you message. | | thankYouMessage | thank-you-message | string | — | No | Overrides the saved survey thank-you message. | | sessionData | — | object | {} | No | Session data passed from the host app; must match the declared Session Data schema. |

Events

| Event | Detail | Description | | --------- | -------------------------------------------- | ------------------------------------------ | | sfError | { surveyKey, errorType, errorMessage } | Load, submit, or validation error occurred |

CSS Shadow Parts

The component uses shadow DOM and exposes the following CSS parts for styling:

| Part | ---------------------------- | survey-container | step | choice-task-step | survey-fields-step | completion-step | heading | task-heading | survey-fields-heading | completion-heading | task-header | task-instructions | progress | progress-indicator | progress-label | progress-track | progress-bar | progress-fill | progress-text | concepts-container | concept | concept-selected | concept-unselected | none-option | concept-header | concept-radio | concept-title | concept-attributes | concept-attribute | attribute-label | attribute-value | button-container | button | back-button | next-button | submit-button | form-container | form-field | form-label | form-input | form-select | hcaptcha-container | input | select | required-indicator | radio-group | radio-option | radio-input | radio-label | checkbox-group | checkbox-option | checkbox-input | checkbox-label | completion-summary | summary-text | message | error-container | error-message | troubleshooting-link | loading-message | branding | branding-link | branding-logo | announcements | Description | | ------------------------------------------------------------------- | | Outer wrapper for the entire survey | | Wrapper for each step (choice task, survey fields, completion) | | Wrapper for the choice task step | | Wrapper for the survey fields step | | Wrapper for the completion step | | All <h2> headings | | The <h2> heading for each choice task | | The <h2> heading for the survey fields step | | The <h2> heading for the completion step | | Header area of the choice task (progress + heading + instructions) | | Instruction text above the alternatives | | Top progress header wrapper | | Legacy alias for the progress header | | "Task X of Y" label | | Continuous progress bar track | | Legacy alias for the progress bar track | | The filled portion of the progress bar | | "Task X of Y" text | | Wrapper for all alternative cards in a task | | An individual alternative card | | Applied to the currently selected alternative card | | Applied to unselected alternative cards | | The "None of these options" card | | Header area of an alternative card | | The hidden radio input inside an alternative card | | Title text within an alternative card | | Attribute list within an alternative card | | A single attribute row within a card | | The attribute name label | | The attribute variant value | | Wrapper for navigation buttons | | All buttons | | The "Previous" button | | The "Next Task" / "Next" button | | The "Submit" button on the survey fields step | | Wrapper for the survey fields form fields | | A single form field wrapper | | A form field label | | A text/email/number input field | | A dropdown select field | | Wrapper for the hCaptcha widget (when enabled) | | Text/email/number input (alias for form-input) | | Dropdown select (alias for form-select) | | The asterisk indicator for required fields | | Wrapper for a radio button group | | A single radio option row | | A radio input element | | A radio option label | | Wrapper for a checkbox group | | A single checkbox option row | | A checkbox input element | | A checkbox option label | | Wrapper for the completion summary content | | The summary text on the completion screen | | All message elements (loading, error) | | Wrapper shown when an error occurs | | The error message text | | Troubleshooting link shown with integration errors | | The loading state text | | SenseFolks branding footer (shown when enabled) | | The anchor link within the branding footer | | The SVG logo within the branding footer | | ARIA live region for screen reader announcements |

CSS Custom Properties

Override these on the component tag or a parent element to theme the survey:

| Property | Default | Description | | ------------------------ | ---------------------------------- | ----------------------------------- | | --sf-primary | #005fcc | Primary accent color | | --sf-primary-hover | #0047a3 | Primary color hover state | | --sf-selected-bg | #e8f0fe | Selected card background | | --sf-selected-border | #005fcc | Selected card border color | | --sf-selected-ring | rgba(0, 95, 204, 0.2) | Selected card focus ring | | --sf-card-bg | #ffffff | Card/container background | | --sf-card-border | #d1d5db | Card/container border color | | --sf-button-text | #ffffff | Button text color | | --sf-card-radius | 8px | Card/container border radius | | --sf-card-shadow | 0 1px 3px rgba(0, 0, 0, 0.1) | Card shadow | | --sf-card-shadow-hover | 0 4px 12px rgba(0, 0, 0, 0.15) | Card hover shadow | | --sf-none-bg | #f9fafb | "None of these options" background | | --sf-none-hover-bg | #f3f4f6 | "None of these options" hover background | | --sf-none-border | #9ca3af | "None of these options" border | | --sf-error-color | #dc2626 | Error state color | | --sf-error-text | #991b1b | Error message text color | | --sf-error-bg | #fef2f2 | Error state background | | --sf-error-border | #fecaca | Error state border color | | --sf-progress-bg | #e5e7eb | Progress track color | | --sf-progress-fill | #005fcc | Progress fill color | | --sf-text-primary | #111827 | Primary text color | | --sf-text-secondary | #6b7280 | Secondary/muted text color | | --sf-button-radius | 6px | Button border radius | | --sf-transition | 150ms ease | Default transition timing |

Styling example

sf-userchoice::part(concept) {
  border: 2px solid #e2e8f0;
  border-radius: 8px;
  padding: 16px;
  cursor: pointer;
}

sf-userchoice::part(concept-selected) {
  border-color: #3b82f6;
  background-color: #eff6ff;
}

sf-userchoice::part(next-button) {
  background-color: #3b82f6;
  color: white;
  border-radius: 6px;
  padding: 10px 24px;
}

Minimal working example

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Choice Survey</title>
    <script type="module" src="https://unpkg.com/@sensefolks/[email protected]/dist/sf-userchoice/sf-userchoice.esm.js"></script>
  </head>
  <body>
    <sf-userchoice survey-key="a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"></sf-userchoice>
  </body>
</html>

Privacy And Network Requirements

sf-userchoice loads survey configuration from the SenseFolks embed request endpoint and submits responses to the SenseFolks embed response endpoint. The survey-key value is validated as a UUID before requests are made and is URL encoded in request paths.

Submitted payloads can include the respondent's answers, configured survey fields, prepared session data values supplied by the host page, completion timing, and metadata including user-agent string, platform, language, cookie-enabled status, online status, screen resolution, color depth, timezone, and timestamp. This component does not use cookies, localStorage, sessionStorage, or IndexedDB. Answers and task progress exist only in the mounted component; reloading the page or mounting a new component always starts at the first task with no restored answers.

If hCaptcha is enabled by the survey config, allow hCaptcha in your CSP: script-src https://js.hcaptcha.com, frame-src https://hcaptcha.com https://*.hcaptcha.com, and a connect-src that includes your SenseFolks API origin plus the hCaptcha endpoints.

Accessibility

The component includes keyboard navigation support:

Arrow keys — move focus between alternative cards
Enter / Space — select the focused alternative
All interactive elements have appropriate role, aria-checked, aria-label, and tabindex attributes
A live region announces selections to screen readers

Browser support

| Browser | Version | | ------- | -------------- | | Chrome | 88+ | | Firefox | 85+ | | Safari | 14+ | | Edge | 88+ |

Internet Explorer 11 is not supported. The host browser must provide modern Web Component APIs, fetch, and AbortController.

Agent Integration

{
  "component": "sf-userchoice",
  "package": "@sensefolks/userchoice",
  "attributes": [
    {
      "name": "survey-key",
      "type": "string",
      "required": true,
      "description": "The survey's public key (UUID). Obtained from the SenseFolks dashboard."
    },
    {
      "name": "completion-message",
      "type": "string",
      "required": false,
      "description": "Fallback message shown after submission when the survey has no saved thank-you message. Defaults to \"Thank you for your response!\""
    }
  ],
  "events": [],
  "cssCustomProperties": [
    "--sf-primary",
    "--sf-primary-hover",
    "--sf-selected-bg",
    "--sf-selected-border",
    "--sf-selected-ring",
    "--sf-card-bg",
    "--sf-card-border",
    "--sf-button-text",
    "--sf-card-radius",
    "--sf-card-shadow",
    "--sf-card-shadow-hover",
    "--sf-none-bg",
    "--sf-none-hover-bg",
    "--sf-none-border",
    "--sf-error-color",
    "--sf-error-text",
    "--sf-error-bg",
    "--sf-error-border",
    "--sf-progress-bg",
    "--sf-progress-fill",
    "--sf-text-primary",
    "--sf-text-secondary",
    "--sf-button-radius",
    "--sf-transition"
  ],
  "cssParts": [
    "survey-container",
    "step",
    "choice-task-step",
    "survey-fields-step",
    "completion-step",
    "heading",
    "task-heading",
    "survey-fields-heading",
    "completion-heading",
    "task-header",
    "task-instructions",
    "progress",
    "progress-indicator",
    "progress-label",
    "progress-track",
    "progress-bar",
    "progress-fill",
    "progress-text",
    "concepts-container",
    "concept",
    "concept-selected",
    "concept-unselected",
    "none-option",
    "concept-header",
    "concept-radio",
    "concept-title",
    "concept-attributes",
    "concept-attribute",
    "attribute-label",
    "attribute-value",
    "button-container",
    "button",
    "back-button",
    "next-button",
    "submit-button",
    "form-container",
    "form-field",
    "form-label",
    "form-input",
    "input",
    "select",
    "form-select",
    "radio-group",
    "radio-option",
    "radio-input",
    "radio-label",
    "checkbox-group",
    "checkbox-option",
    "checkbox-input",
    "checkbox-label",
    "completion-summary",
    "summary-text",
    "message",
    "error-container",
    "error-message",
    "troubleshooting-link",
    "loading-message",
    "branding",
    "branding-link",
    "branding-logo",
    "announcements",
    "required-indicator"
  ]
}

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@sensefolks/userchoice

How it works

Step flow

Installation

CDN

NPM

Usage

Vanilla JS

React

Vue

Angular

Framework Notes

API Reference

Properties

Events

CSS Shadow Parts

CSS Custom Properties

Styling example

Minimal working example

Privacy And Network Requirements

Accessibility

Browser support

Agent Integration