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/openfeedback@3.0.1/dist/sf-openfeedback/sf-openfeedback.esm.js"></script>

<!-- Legacy browsers -->
<script nomodule src="https://unpkg.com/@sensefolks/openfeedback@3.0.1/dist/sf-openfeedback/sf-openfeedback.js"></script>

Or via jsDelivr:

<script type="module" src="https://cdn.jsdelivr.net/npm/@sensefolks/openfeedback@3.0.1/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

Events

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

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:

CSS Shadow Parts

Style the component externally using ::part():

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",
    "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-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, 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