sf-openfeedback

Open-ended feedback survey web component for collecting qualitative user insights through free-text responses.

Features

• 📝 Open-ended text feedback collection
• ✅ Built-in form validation with accessible error messages
• 👤 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/openfeedback

CDN (Script Tag)

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

Or via jsDelivr:

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

Usage

HTML

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

React

import '@sensefolks/openfeedback';

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

Vue

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

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

Angular

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

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

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

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 } | Survey loaded and ready to display | | sfStepChange | { surveyKey, previousStep, currentStep, currentStepIndex } | User navigated between steps | | sfInput | { surveyKey, value, characterCount } | User typed in the feedback textarea | | sfSubmit | { surveyKey, feedback } | 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. Question — Open-ended textarea for feedback (always shown)
2. Respondent details — Collects user info like name, email, etc. (shown only when configured)
3. 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 after any non-empty input and the respondent pauses typing for 1.5 seconds.

CSS Custom Properties

Customize the component by setting CSS custom properties on the element or a parent:

| Property | Default | Description | | --------------------- | ------------ | -------------------------- | | --sf-primary | #005fcc | Primary brand color | | --sf-primary-hover | #0047a3 | Primary hover color | | --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 background color | | --sf-card-border | #d1d5db | Card border color | | --sf-button-text | #ffffff | Button text color | | --sf-card-radius | 8px | Card border radius | | --sf-button-radius | 6px | Button border radius | | --sf-transition | 150ms ease | Transition timing | | --sf-progress-bg | #e5e7eb | Progress track color | | --sf-progress-fill | primary | Progress fill color |

CSS Shadow Parts

Style the component externally using ::part():

| Part | Description | | ----------------------------- | ---------------------------------------------- | | container | Host element wrapper | | step | Any step container | | question-step | Question step | | survey-fields-step | Survey Fields step | | survey-fields-heading | Survey Fields introductory text | | survey-fields-container | Survey Fields form container | | completion-step | Completion step | | heading | Compatibility hook for primary body text | | question-heading | Question body text | | respondent-heading | Respondent details 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 | | input | All input elements | | textarea | Feedback textarea | | form-textarea | Feedback textarea (form alias) | | button-container | Button row wrapper | | button | All buttons | | next-button | Next/Submit button on question step | | back-button | Back button | | submit-button | Submit button on survey fields | | respondent-fields-container | Fields container | | form-container | Fields container (form alias) | | field | Form field wrapper | | form-field | Form field wrapper (form alias) | | field-error | Field in error state (additive with field) | | field-label | Field label | | form-label | Field label (form alias) | | required-indicator | Required asterisk | | form-input | Text/email/number inputs | | select | Select element | | form-select | Select element (form alias) | | hcaptcha-container | Wrapper for the hCaptcha widget (when enabled) | | radio-group | Radio group container | | radio-option | Radio option wrapper | | radio-input | Radio input | | radio-label | Radio label | | checkbox-group | Checkbox group container | | checkbox-option | Checkbox option wrapper | | checkbox-input | Checkbox input | | checkbox-label | Checkbox label | | error-message | Error text | | survey-field-error-message | Inline email feedback shown after a 1.5-second idle delay | | error-container | Error wrapper | | troubleshooting-link | Troubleshooting link shown with integration errors | | message | All status messages | | loading-message | Loading state text | | empty-message | No survey fields message | | branding | Branding container | | branding-link | Branding anchor | | branding-logo | Branding SVG logo | | announcements | Screen reader live region |

Styling Example

sf-openfeedback {
  --sf-primary: #7c3aed;
  --sf-error-color: #e11d48;
  --sf-card-radius: 12px;
  --sf-button-radius: 8px;
}

sf-openfeedback::part(textarea) {
  border: 1px solid var(--sf-card-border);
  border-radius: var(--sf-card-radius);
  padding: 0.75rem;
  font-size: 1rem;
}

sf-openfeedback::part(next-button) {
  background-color: var(--sf-primary);
  color: #ffffff;
  border-radius: var(--sf-button-radius);
  padding: 0.5rem 1.5rem;
}

sf-openfeedback::part(field-label) {
  font-weight: 600;
  color: var(--sf-text-primary);
}

Agent Integration

{
  "component": "sf-openfeedback",
  "package": "@sensefolks/openfeedback",
  "tag": "sf-openfeedback",
  "cssParts": [
    "container",
    "step",
    "question-step",
    "survey-fields-step",
    "survey-fields-heading",
    "survey-fields-container",
    "completion-step",
    "heading",
    "question-heading",
    "respondent-heading",
    "completion-heading",
    "success-message",
    "progress",
    "progress-indicator",
    "progress-label",
    "progress-text",
    "progress-track",
    "progress-bar",
    "progress-fill",
    "input",
    "textarea",
    "form-textarea",
    "button-container",
    "button",
    "next-button",
    "back-button",
    "submit-button",
    "respondent-fields-container",
    "form-container",
    "field",
    "form-field",
    "field-error",
    "field-label",
    "form-label",
    "required-indicator",
    "form-input",
    "select",
    "form-select",
    "radio-group",
    "radio-option",
    "radio-input",
    "radio-label",
    "checkbox-group",
    "checkbox-option",
    "checkbox-input",
    "checkbox-label",
    "error-message",
    "survey-field-error-message",
    "error-container",
    "troubleshooting-link",
    "message",
    "loading-message",
    "empty-message",
    "branding",
    "branding-link",
    "branding-logo",
    "announcements"
  ],
  "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"
  ]
}

Privacy And Network Requirements

sf-openfeedback 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. In-progress answers live only in the current component instance; reloading the page or creating a new instance always starts a blank 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 between fields, Enter to submit)
• ARIA aria-invalid and aria-describedby on fields with validation errors
• aria-live="polite" region for screen reader announcements on step changes and submissions
• 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.

License

MIT © SenseFolks