Reaction API Reference | Expressive, Thumbs, and Heart Surveys

Reaction is an embeddable icon survey for quick responses to content, design, or copy.

@sensefolks/reaction

What Reaction Records

Choose five expressive faces, thumbs up/down, or a heart. A tap submits the reaction; tapping again undoes it.

Set the mode in your dashboard. Refreshing the page clears the current selection.

When should I use Reaction?

Place Reaction beside:

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

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

Choose one of three modes:

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

Reactions use Google Material Symbols under Apache License 2.0. Selecting an icon fills it. Default thumb colours are #43A047 for up and #F4511E for down; override them with the variables below.

Styling

CSS Custom Properties

Set theme variables on the component 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 exposed parts with ::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