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>

<!-- Legacy browsers -->
<script nomodule src="https://unpkg.com/@sensefolks/[email protected]/dist/sf-openfeedback/sf-openfeedback.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 | | 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 } | 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, 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. 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

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-card-bg | #ffffff | Card background color | | --sf-card-border | #d1d5db | Card border 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 step heading | | survey-fields-container | Survey Fields form container | | completion-step | Completion step | | heading | All step headings | | question-heading | Question step heading | | respondent-heading | Respondent details heading | | completion-heading | Completion 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 | | 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 | | retry-button | Retry button on error | | 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 | | error-container | Error wrapper with retry button | | 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",
    "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",
    "retry-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",
    "error-container",
    "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-card-bg",
    "--sf-card-border",
    "--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 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 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+
• IE11 (with ES5 build)

License

MIT © SenseFolks