sf-reaction

Icon-based quick survey with three built-in reaction sets: expressive faces, thumbs up/down, and heart.

Features

• Three built-in sets: Expressive (five sentiment faces), Thumbs up/down, and Heart (favourite mode)
• Each page load or component mount starts a fresh response
• Keyboard navigable with ARIA labels and live regions
• Customizable via CSS Parts
• Responsive design
• Works with any framework

Installation

NPM

npm install @sensefolks/reaction

CDN (Script Tag)

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

Or via jsDelivr:

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

Usage

HTML

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

React

import '@sensefolks/reaction';

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

Vue

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

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

Angular

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

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

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

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/

How It Works

1. On load, the component fetches survey config from the embed API using the surveyKey.
2. It renders one of three built-in reaction sets based on reactionMode: Expressive faces (expressive), Thumbs up/down (thumbsUpDown), or Heart (favourite).
3. Tapping a reaction sends a POST for the currently mounted component.
4. Changing or deselecting before reload uses the in-memory edit token to PATCH the same response.
5. Reloading, revisiting, or changing context starts blank and creates a new response.

Reaction Sets and Modes

The human-facing sets are Expressive, Thumbs up/down, and Heart. The dashboard calls the Heart set Favourite, and its stable config value remains favourite.

| Dashboard label | Config value | Material Symbols and response values | | ------------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Expressive | expressive | sentiment_extremely_dissatisfied (veryDissatisfied), sentiment_dissatisfied (dissatisfied), sentiment_neutral (neutral), sentiment_satisfied (satisfied), sentiment_very_satisfied (verySatisfied) | | Thumbs up and down | thumbsUpDown | thumb_up (up), thumb_down (down) | | Favourite | favourite | favorite (favourite) |

Default reactions use Google Material Symbols in the listed left-to-right order. Unselected reactions use the outlined SVG and the selected reaction swaps to the filled SVG without changing size. Material Symbols are licensed under Apache License 2.0.

API

Properties

| Property | Attribute | Type | Default | Description | | ------------- | ------------ | -------- | ----------- | ---------------------------------------------------------------------------------- | | surveyKey | survey-key | string | undefined | UUID of the survey to load (required) | | sessionData | — | object | {} | Session data passed from the host app; must match the declared Session Data schema |

Events

| Event | Detail | Description | | ---------- | -------------------------------------------- | ---------------------------------------------------------------------------------- | | sfReady | { surveyKey, reactionMode, reactionCount } | Survey config loaded and reactions rendered | | sfSubmit | { surveyKey, selectedReaction, action } | Reaction created, updated, or deleted (action: create | update | delete) | | sfError | { surveyKey, errorType, errorMessage } | Error occurred (errorType: 'load' or 'submit') |

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 | Integration error text color | | --sf-error-bg | #fef2f2 | Integration error background | | --sf-error-border | #fecaca | Integration error border 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-reaction-icon-size | 32px | Size of reaction icons | | --sf-reaction-very-dissatisfied-color | #991b1b | Very dissatisfied icon color | | --sf-reaction-dissatisfied-color | #8a3a00 | Dissatisfied icon color | | --sf-reaction-neutral-color | #665700 | Neutral icon color | | --sf-reaction-satisfied-color | #256326 | Satisfied icon color | | --sf-reaction-very-satisfied-color | #14532d | Very satisfied icon color | | --sf-reaction-thumbs-color | #5b21b6 | Thumbs up and down icon color | | --sf-reaction-favourite-color | #991b1b | Heart icon color | | --sf-reaction-hover-bg | rgba(0, 0, 0, 0.05) | Reaction hover background | | --sf-reaction-count-color | #9ca3af | Reaction count text color |

CSS Shadow Parts

Style the component externally using ::part():

| Part | Description | | ------------------------------------ | ------------------------------------------ | | container | Host element wrapper | | reaction-container | Main reaction group wrapper | | reactions-row | Flex row of reaction buttons | | reaction-item | Individual reaction button | | reaction-item reaction-item-active | Active/selected reaction button (additive) | | reaction-icon | Icon wrapper (default and SVG types) | | reaction-label | Text label below each reaction | | button | Generic button base | | retry-button | "Try again" button on error | | message | Shared part on all status text | | loading-message | Loading state text | | error-message | Error state text | | error-container | Error wrapper with retry button | | troubleshooting-link | Troubleshooting link shown with integration errors | | branding | Branding container | | branding-link | Branding anchor | | branding-logo | Branding SVG logo | | announcements | Screen reader live region |

Styling Example

sf-reaction {
  --sf-primary: #7c3aed;
  --sf-text-secondary: #4b5563;
  --sf-reaction-icon-size: 40px;
  --sf-reaction-thumbs-color: #4c1d95;
  --sf-reaction-favourite-color: #7f1d1d;
}

sf-reaction::part(reaction-item) {
  padding: 0.75rem;
  border-radius: 12px;
}

sf-reaction::part(reaction-item-active) {
  background-color: rgba(124, 58, 237, 0.1);
}

sf-reaction::part(reaction-label) {
  font-weight: 500;
}

Agent Integration

{
  "component": "sf-reaction",
  "package": "@sensefolks/reaction",
  "tag": "sf-reaction",
  "cssParts": [
    "container",
    "reaction-container",
    "reactions-row",
    "reaction-item",
    "reaction-item-active",
    "reaction-icon",
    "reaction-label",
    "button",
    "retry-button",
    "message",
    "loading-message",
    "error-message",
    "error-container",
    "troubleshooting-link",
    "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-card-radius",
    "--sf-button-radius",
    "--sf-transition",
    "--sf-reaction-icon-size",
    "--sf-reaction-very-dissatisfied-color",
    "--sf-reaction-dissatisfied-color",
    "--sf-reaction-neutral-color",
    "--sf-reaction-satisfied-color",
    "--sf-reaction-very-satisfied-color",
    "--sf-reaction-thumbs-color",
    "--sf-reaction-favourite-color",
    "--sf-reaction-hover-bg",
    "--sf-reaction-count-color"
  ]
}

Privacy And Network Requirements

sf-reaction 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 selected reaction, 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. The component does not persist reaction state to localStorage or sessionStorage; it keeps the current edit token only in memory while mounted so changes and deselection before reload can update the same response. Edit tokens are sent only in the Authorization: Bearer … header of the fixed /v1/responses/edit endpoint and are never placed in a URL, query string, or request body.

Accessibility

• Reaction buttons use role="button" with aria-pressed to indicate selection state
• A live region (aria-live="polite") announces selection changes to screen readers
• Focus indicators are visible and enhanced in high-contrast mode
• Animations respect 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