sf-fastpoll

Fast poll survey web component for collecting user feedback with single/multiple choice options.

Features

• 🎯 Single and multiple choice polls
• 📝 Optional follow-up questions (triggered by specific choices)
• 👤 Optional survey fields collection (text, email, number, dropdown, radio, checkbox)
• ♿ Keyboard navigable with ARIA labels and live regions
• 🎨 Customizable via CSS Parts
• 📱 Responsive design
• 🌐 Works with any framework

Installation

NPM

npm install @sensefolks/fastpoll

CDN (Script Tag)

<!-- Modern browsers (ES modules) -->
<script type="module" src="https://unpkg.com/@sensefolks/[email protected]/dist/sf-fastpoll/sf-fastpoll.esm.js"></script>

<!-- Legacy browsers -->
<script nomodule src="https://unpkg.com/@sensefolks/[email protected]/dist/sf-fastpoll/sf-fastpoll.js"></script>

Or via jsDelivr:

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

Usage

HTML

<sf-fastpoll survey-key="your-survey-uuid"></sf-fastpoll>

React

import '@sensefolks/fastpoll';

function App() {
  return <sf-fastpoll survey-key="your-survey-uuid"></sf-fastpoll>;
}

Vue

<template>
  <sf-fastpoll survey-key="your-survey-uuid"></sf-fastpoll>
</template>

<script>
import '@sensefolks/fastpoll';
export default { name: 'App' };
</script>

Angular

// app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@sensefolks/fastpoll';

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

<!-- component.html -->
<sf-fastpoll survey-key="your-survey-uuid"></sf-fastpoll>

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

Properties

| Property | Attribute | Type | Default | Description | | ------------------- | -------------------- | --------- | -------------------------------- | --------------------------------------------------------------- | | surveyKey | survey-key | string | — | UUID of the survey to load (required) | | completionMessage | completion-message | string | 'Thank you for your response!' | Fallback message shown after submission when the survey has no saved thank-you message | | thankYouMessage | thank-you-message | string | — | Overrides the saved survey thank-you message | | embedContext | — | object | {} | Session data passed from the host app; must match the declared Embed Context schema | | enableEvents | enable-events | boolean | true | Whether to emit custom events (sfReady, sfStepChange, etc.) |

Events

All events are emitted when enableEvents is true (the default).

| Event | Detail | Description | | ---------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------- | | sfReady | { surveyKey, question, choiceType, choiceCount } | Survey loaded and ready to display | | sfStepChange | { surveyKey, previousStep, currentStep, currentStepIndex } | User navigated between steps | | sfChoiceSelect | { surveyKey, selectedChoices, choiceType, lastAction, lastChoice } | User selected or deselected a choice | | sfSubmit | { surveyKey, selectedChoices, followUpResponse, completionTimeSeconds } | Survey successfully submitted | | sfError | { surveyKey, errorType, errorMessage } | Error occurred (errorType: 'load', 'submit', or 'validation') |

Survey Steps

The component progresses through steps based on the survey configuration:

1. Poll — User selects choices (always shown)
2. Follow-up — Free-text response (shown only when selected choices match configured trigger choices)
3. Respondent details — Collects user info like name, email, etc. (shown only when configured)
4. Completion — Displays the completion message

CSS Shadow Parts

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

| Part | Description | | ---------------------------- | ------------------------------------------------ | | survey-container | Outer wrapper for the entire survey | | step | Wrapper for each survey step | | poll-step | Wrapper for the poll step | | follow-up-step | Wrapper for the follow-up step | | survey-fields-step | Wrapper for the survey fields step | | completion-step | Wrapper for the completion/thank-you screen | | heading | All heading elements | | poll-heading | The poll question heading | | follow-up-heading | The follow-up question heading | | survey-fields-heading | The survey fields heading | | completion-heading | The completion screen heading | | progress | Top progress header wrapper | | progress-indicator | Compatibility alias for the progress header | | progress-label | "Task X of Y" label | | progress-text | Compatibility alias for the progress label | | progress-track | Continuous progress bar track | | progress-bar | Compatibility alias for the progress bar track | | progress-fill | Filled portion of the progress bar | | choices-container | Wrapper for all choice options | | choice-option | A single choice option label | | choice-label | The text label for a choice option | | checkbox-input | A checkbox input element | | radio-input | A radio input element | | followup-input-container | Wrapper for the follow-up textarea | | textarea | The follow-up textarea element | | followup-textarea | The follow-up textarea (alias) | | other-choice-input | Input field for the "Other" choice option | | button-container | Wrapper for navigation buttons | | button | All buttons | | back-button | The "Back" navigation button | | next-button | The "Next" navigation button | | submit-button | The "Submit" action button | | retry-button | The retry button shown on error | | error-container | Wrapper for error state display | | error-message | Error message text | | message | All message elements (loading, error) | | loading-message | Loading state text | | form-container | Wrapper for survey fields form fields | | form-field | A single form field wrapper | | form-label | A form field label | | form-input | A text/email/number input field | | input | Input field (alias for form-input) | | form-select | A dropdown select field | | select | Dropdown select (alias for form-select) | | hcaptcha-container | Wrapper for the hCaptcha widget (when enabled) | | required-indicator | The asterisk indicator for required fields | | radio-group | Wrapper for a radio button group | | radio-option | A single radio option row | | radio-label | A radio option label | | checkbox-group | Wrapper for a checkbox group | | checkbox-option | A single checkbox option row | | checkbox-label | A checkbox option label | | branding | SenseFolks branding footer | | branding-link | The anchor link within the branding footer | | branding-logo | The SVG logo within the branding footer | | announcements | 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-text-primary | #111827 | Primary text color | | --sf-text-secondary | #6b7280 | Secondary/muted text color | | --sf-error-color | #dc2626 | Error state color | | --sf-card-bg | #ffffff | Card/container background | | --sf-card-border | #d1d5db | Card/container border color | | --sf-card-radius | 8px | Card/container border radius | | --sf-button-radius | 6px | Button border radius | | --sf-transition | 150ms ease | Default transition timing | | --sf-progress-bg | #e5e7eb | Progress track color | | --sf-progress-fill | primary | Progress fill color | | --sf-followup-border | #d1d5db | Border color for the follow-up textarea | | --sf-choice-hover-bg | #f3f4f6 | Background color on choice option hover |

Styling example

/* Theme with custom properties */
sf-fastpoll {
  --sf-primary: #7c3aed;
  --sf-primary-hover: #6d28d9;
  --sf-card-radius: 12px;
  --sf-button-radius: 8px;
  --sf-choice-hover-bg: #f5f3ff;
}

/* Style individual parts */
sf-fastpoll::part(survey-container) {
  max-width: 480px;
  padding: 24px;
  border: 1px solid var(--sf-card-border);
  border-radius: var(--sf-card-radius);
}

sf-fastpoll::part(poll-heading) {
  font-size: 1.25rem;
  font-weight: 600;
  color: var(--sf-text-primary);
  margin-bottom: 1rem;
}

sf-fastpoll::part(choice-option) {
  padding: 0.75rem 1rem;
  border-radius: var(--sf-card-radius);
  transition: background-color var(--sf-transition);
}

sf-fastpoll::part(submit-button) {
  background-color: var(--sf-primary);
  color: #ffffff;
  border: none;
  border-radius: var(--sf-button-radius);
  padding: 10px 24px;
  cursor: pointer;
}

sf-fastpoll::part(submit-button):hover {
  background-color: var(--sf-primary-hover);
}

sf-fastpoll::part(followup-textarea) {
  border-color: var(--sf-followup-border);
  border-radius: var(--sf-button-radius);
}

Privacy And Network Requirements

sf-fastpoll 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 embed context 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, or sessionStorage.

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

• Full keyboard navigation (Tab, Arrow keys, Enter/Space)
• ARIA role="radiogroup" / role="group" on choices depending on single/multi choice
• aria-invalid and aria-describedby on fields with validation errors
• aria-live="polite" region for screen reader announcements on step changes and selections
• Focus indicators (outline) on all interactive elements
• High contrast mode support via @media (prefers-contrast: high)
• Respects prefers-reduced-motion

Browser Support

• Chrome 88+
• Firefox 85+
• Safari 14+
• Edge 88+
• IE11 (with ES5 build)

Agent Integration

{
  "component": "sf-fastpoll",
  "package": "@sensefolks/fastpoll",
  "attributes": [
    {
      "name": "survey-key",
      "type": "string",
      "required": true,
      "description": "UUID of the survey to load."
    },
    {
      "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!\""
    },
    {
      "name": "enable-events",
      "type": "boolean",
      "required": false,
      "description": "Whether to emit custom events (sfReady, sfStepChange, sfChoiceSelect, sfSubmit, sfError). Defaults to true."
    }
  ],
  "events": [
    {
      "name": "sfReady",
      "detail": "{ surveyKey, question, choiceType, choiceCount }",
      "description": "Survey loaded and ready to display."
    },
    {
      "name": "sfStepChange",
      "detail": "{ surveyKey, previousStep, currentStep, currentStepIndex }",
      "description": "User navigated between steps."
    },
    {
      "name": "sfChoiceSelect",
      "detail": "{ surveyKey, selectedChoices, choiceType, lastAction, lastChoice }",
      "description": "User selected or deselected a choice."
    },
    {
      "name": "sfSubmit",
      "detail": "{ surveyKey, selectedChoices, followUpResponse, completionTimeSeconds }",
      "description": "Survey successfully submitted."
    },
    {
      "name": "sfError",
      "detail": "{ surveyKey, errorType, errorMessage }",
      "description": "Error occurred (errorType: 'load', 'submit', or 'validation')."
    }
  ],
  "cssCustomProperties": [
    "--sf-primary",
    "--sf-primary-hover",
    "--sf-text-primary",
    "--sf-text-secondary",
    "--sf-error-color",
    "--sf-card-bg",
    "--sf-card-border",
    "--sf-card-radius",
    "--sf-button-radius",
    "--sf-transition",
    "--sf-progress-bg",
    "--sf-progress-fill",
    "--sf-followup-border",
    "--sf-choice-hover-bg"
  ],
  "cssParts": [
    "survey-container",
    "step",
    "poll-step",
    "follow-up-step",
    "survey-fields-step",
    "completion-step",
    "heading",
    "poll-heading",
    "follow-up-heading",
    "survey-fields-heading",
    "completion-heading",
    "progress",
    "progress-indicator",
    "progress-label",
    "progress-text",
    "progress-track",
    "progress-bar",
    "progress-fill",
    "choices-container",
    "choice-option",
    "choice-label",
    "checkbox-input",
    "radio-input",
    "followup-input-container",
    "textarea",
    "followup-textarea",
    "button-container",
    "button",
    "back-button",
    "next-button",
    "submit-button",
    "retry-button",
    "error-container",
    "error-message",
    "message",
    "loading-message",
    "form-container",
    "form-field",
    "form-label",
    "form-input",
    "input",
    "form-select",
    "select",
    "required-indicator",
    "radio-group",
    "radio-option",
    "radio-label",
    "checkbox-group",
    "checkbox-option",
    "checkbox-label",
    "branding",
    "branding-link",
    "branding-logo",
    "announcements"
  ]
}

License

MIT © SenseFolks