Reaction API Reference | Expressive, Thumbs, and Heart Surveys

Reaction captures one lightweight signal with expressive faces, thumbs up/down, or a heart. Use it when a quick response to content, design, or copy is more appropriate than a longer survey.

@sensefolks/reaction

What Reaction Records

Reaction shows one of three icon sets: five expressive faces, thumbs up and down, or a single heart. Users tap once to react and tap again to undo. Submission happens immediately.

Reaction state is kept only in memory while the component remains mounted. Refreshing or reloading the page starts a fresh response with no restored selection. Configure the mode in your dashboard.

When Reaction Is the Right Survey

Place it next to the item you want people to react to:

Blog posts and articles — Gauge reader sentiment
Feature announcements — Capture an immediate response
Help docs — Thumbs up/down for helpfulness
Product pages — Capture lightweight affinity with a heart
Release notes — Quick read on how updates land

Installation

CDN (Recommended)

html

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

NPM

bash

npm install @sensefolks/reaction

Embed Reaction

HTML

html

<sf-reaction 
  survey-key="your-survey-uuid"
  thank-you-message="Thanks for your feedback!">
</sf-reaction>

React

jsx

import '@sensefolks/reaction';

function App() {
  return (
    <sf-reaction 
      survey-key="your-survey-uuid"
      thank-you-message="Thanks for your feedback!">
    </sf-reaction>
  );
}

For Vue + Nuxt, Angular, Svelte, and Astro examples, see theEmbedding Tutorial.

API Reference

Properties

Property	Attribute	Type	Default	Description
`surveyKey`	`survey-key`	string	—	Required. UUID of the reaction survey from your dashboard
`thankYouMessage`	`thank-you-message`	string	—	Overrides the thank-you message shown after submission
`sessionData`	—	Record<string, string \| number \| boolean>	{}	Complete typed Session Data matching every field in the schema defined during survey creation

Events

Event	Detail	Description
`sfReady`	`{ surveyKey, reactionMode, reactionCount }`	Fired when the survey config has loaded
`sfSubmit`	`{ surveyKey, selectedReaction, action }`	Fired on create, update, or delete of a reaction
`sfError`	`{ surveyKey, errorType, errorMessage }`	Fired on load or submit errors

Reaction Modes

Configure the mode in your dashboard. Each mode offers a different level of granularity:

Dashboard label	Config value	Icons	Best for
Expressive	`expressive`	`sentiment_extremely_dissatisfied`,`sentiment_dissatisfied`,`sentiment_neutral`,`sentiment_satisfied`,`sentiment_very_satisfied`	Detailed sentiment on content or announcements
Favourite (heart)	`favourite`	`favorite`	Lightweight affinity or appreciation signal
Thumbs up and down	`thumbsUpDown`	`thumb_up`, `thumb_down`	Simple helpful/not helpful on docs or support content

Default reactions use Google Material Symbols in the displayed left-to-right order. Unselected reactions are outlined; selection swaps only that icon to its filled form. The default colors follow the SenseFolks palette: thumbs up is #43A047 and thumbs down is#F4511E. They can be overridden with the Reaction color properties below. Google Material Symbols are available under the Apache License 2.0.

Styling

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-reaction-icon-size`	`32px`	Size of reaction icons
`--sf-reaction-highlight-bg`	`rgba(0, 95, 204, 0.12)`	Background highlight for the selected reaction
`--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-thumb-up-color`	`#43A047`	Thumbs up icon color
`--sf-reaction-thumb-down-color`	`#F4511E`	Thumbs down icon color
`--sf-reaction-thumbs-color`	Not set	Deprecated shared override for both thumb icons; use the separate thumb color properties for new integrations
`--sf-reaction-favourite-color`	`#991b1b`	Heart icon color (`favourite` mode)

CSS 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-active`	Active/selected state (additive with reaction-item)
`reaction-icon`	Icon wrapper (default and SVG types)
`reaction-emoji`	Emoji or icon glyph inside each reaction
`reaction-emoji-highlight`	Highlight layer behind the selected reaction
`reaction-label`	Text label below each reaction
`message`	Shared part on all status text
`loading-message`	Loading state text
`completion-message`	Completion message shown after submission
`error-message`	Error state text
`error-container`	Error message wrapper
`branding`	Branding container
`branding-link`	Branding anchor
`branding-logo`	Branding SVG logo
`announcements`	Screen reader live region

Styling Example

css

sf-reaction {
  --sf-primary: #7c3aed;
  --sf-text-secondary: #4b5563;
  --sf-reaction-icon-size: 40px;
  --sf-reaction-highlight-bg: rgba(124, 58, 237, 0.12);
  --sf-reaction-thumb-up-color: #166534;
  --sf-reaction-thumb-down-color: #7f1d1d;
  --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;
}

Accessibility

Each reaction button uses aria-pressed to convey toggle state
Live region announces selection changes to screen readers
Keyboard accessible (Tab to navigate, Enter/Space to toggle)
Focus indicators and high contrast mode support
Respects prefers-reduced-motion

Browser Support

Browser	Version
Chrome	88+
Firefox	85+
Safari	14+
Edge	88+
IE11	Not supported