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>

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 | | sessionData | — | object | {} | Every schema field is required when a schema exists; schema-less surveys accept safe flat string, finite number, and boolean values | | enableEvents | enable-events | boolean | true | Whether to emit custom events (sfReady, sfStepChange, etc.) |

For schema-backed surveys, assign the complete sessionData object before setting surveyKey. Reassign a new object whenever Session Data values change; the component refetches after a meaningful reassignment.

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, otherChoiceText } | 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

Required respondent fields are indicated and keep Submit disabled until valid without showing required-field errors. Email format feedback starts only after @ is entered and the respondent pauses typing for 1.5 seconds.

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 | Compatibility hook for primary body text | | poll-heading | Poll question body text | | follow-up-heading | Follow-up question body text | | survey-fields-heading | Survey fields introductory text | | completion-heading | Compatibility hook for the completion message | | success-message | Green completion status message | | progress | Top progress header wrapper | | progress-indicator | Compatibility alias for the progress header | | progress-label | "Step 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 | | error-container | Wrapper for error state display | | error-message | Error message text | | survey-field-error-message | Inline email feedback shown after a 1.5-second idle delay | | troubleshooting-link | Troubleshooting link shown with integration errors | | message | All message elements (loading, error, success) | | 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-error-text | #991b1b | Error message text color | | --sf-error-bg | #fef2f2 | Error state background | | --sf-error-border | #fecaca | Error state border color | | --sf-success-text | #166534 | Success message text color | | --sf-success-bg | #f0fdf4 | Success state background | | --sf-success-border | #bbf7d0 | Success state border color | | --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-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 | | --sf-input-disabled-bg | #f9fafb | Disabled input background color |

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 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. Survey progress exists only in the component's in-memory state. This component does not use cookies, localStorage, sessionStorage, or IndexedDB, and every page reload starts a fresh response.

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+

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

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, otherChoiceText }",
      "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-error-text",
    "--sf-error-bg",
    "--sf-error-border",
    "--sf-success-text",
    "--sf-success-bg",
    "--sf-success-border",
    "--sf-card-bg",
    "--sf-card-border",
    "--sf-button-text",
    "--sf-card-radius",
    "--sf-button-radius",
    "--sf-transition",
    "--sf-progress-bg",
    "--sf-progress-fill",
    "--sf-followup-border",
    "--sf-choice-hover-bg",
    "--sf-input-disabled-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",
    "success-message",
    "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",
    "error-container",
    "error-message",
    "survey-field-error-message",
    "troubleshooting-link",
    "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