react-sentiments

React hooks for detecting user frustration, confusion, and engagement signals in real time.

Most analytics tools tell you what users clicked. react-sentiments tells you how they felt frustrated, confused, hesitant, or engaged. So you can act on it in real time.

---

Installation

npm install react-sentiments
# or
yarn add react-sentiments
# or
pnpm add react-sentiments

Requirements: React 16.8+

---

Hooks

Hook	What it detects
useRageClick	Rapid repeated clicks => frustration
useHesitation	Long hover before click => uncertainty
useDeadClick	Clicks on non-interactive elements => broken UI
useExitIntent	Mouse heading to browser chrome => about to leave
useEngagementTime	Active time on page (tab focused + not idle)
useScrollDepth	How far down the page they actually scrolled
useInputHesitation	Types, pauses, deletes => unsure what to enter
useCopyIntent	Selects or copies text => content engagement
useReread	Scrolls back to re-read a section => confused or interested
useSessionFrustration	Aggregated frustration score (0–100) from all signals

---

Usage

useRageClick

Detects when a user clicks the same element rapidly, a classic sign of frustration.

import { useRageClick } from "react-sentiments";

function SubmitButton() {
  const { onClick } = useRageClick({
    threshold: 3,       // clicks needed to trigger
    timeWindow: 1000,   // within this many ms
    onRageClick: (count) => {
      console.log(`Rage clicked ${count} times!`);
      showHelpTooltip("Having trouble? Try refreshing the page.");
    },
  });

  return <button onClick={onClick}>Submit</button>;
}

Options

Option	Type	Default	Description
threshold	number	3	Clicks needed to trigger
timeWindow	number	1000	Time window in ms
onRageClick	(count: number) => void	required	Fired when threshold is reached

Returns: { onClick }

---

useHesitation

Detects when a user hovers over an element for too long before clicking, a signal of uncertainty.

import { useHesitation } from "react-sentiments";

function PricingButton() {
  const { onMouseEnter, onMouseLeave, onClick } = useHesitation({
    threshold: 2000, // ms of hover before it's hesitation
    onHesitation: (dwellTime) => {
      console.log(`User hesitated for ${dwellTime}ms`);
      showPricingTooltip("This is our most popular plan!");
    },
  });

  return (
    <button {...{ onMouseEnter, onMouseLeave, onClick }}>
      Buy Now — $49/mo
    </button>
  );
}

Options

Option	Type	Default	Description
threshold	number	2000	Dwell time in ms before hesitation
onHesitation	(dwellTime: number) => void	required	Fired on click if hovered too long

Returns: { onMouseEnter, onMouseLeave, onClick }

---

useDeadClick

Detects clicks on non-interactive elements, the user thinks something should be clickable but it isn't.

import { useDeadClick } from "react-sentiments";

function App() {
  useDeadClick({
    scope: "#main-content",  // only monitor this area
    onDeadClick: (element) => {
      console.log("Dead click on:", element.tagName, element.className);
      analytics.track("dead_click", { element: element.outerHTML });
    },
  });

  return <main id="main-content">...</main>;
}

Options

Option	Type	Default	Description
scope	string	"body"	CSS selector to scope monitoring
onDeadClick	(element: HTMLElement) => void	required	Fired on dead click

---

useExitIntent

Detects when the user moves their mouse toward the top of the viewport, they're about to leave.

import { useExitIntent } from "react-sentiments";

function Page() {
  useExitIntent({
    threshold: 20,  // px from top edge
    once: true,     // fire once per session
    onExitIntent: () => {
      showRetentionModal("Wait! Here's 10% off before you go.");
    },
  });

  return <div>...</div>;
}

Options

Option	Type	Default	Description
threshold	number	20	Distance from top in px to trigger
once	boolean	true	Fire only once per page load
onExitIntent	() => void	required	Fired when exit intent detected

---

useEngagementTime

Tracks how long a user is actively engaged, tab must be focused and user must not be idle.

import { useEngagementTime } from "react-sentiments";

function Article() {
  const { engagementTime, isActive } = useEngagementTime({
    idleTimeout: 30000, // stop counting after 30s of inactivity
  });

  // Send to analytics when user leaves
  useEffect(() => {
    return () => analytics.track("engagement", { seconds: engagementTime });
  }, [engagementTime]);

  return (
    <div>
      <article>...</article>
      <p>Active for {engagementTime}s {isActive ? "🟢" : "⚪"}</p>
    </div>
  );
}

Options

Option	Type	Default	Description
idleTimeout	number	30000	Inactivity ms before stopping the counter

Returns: { engagementTime, isActive }

---

useScrollDepth

Tracks the maximum scroll depth as a percentage, with optional milestone callbacks.

import { useScrollDepth } from "react-sentiments";

function BlogPost() {
  const { scrollDepth } = useScrollDepth({
    milestones: [25, 50, 75, 100],
    onMilestone: (pct) => {
      analytics.track("scroll_depth", { percentage: pct });
    },
  });

  return (
    <div>
      <article>...</article>
      <p>Read {scrollDepth}% of this post</p>
    </div>
  );
}

Options

Option	Type	Default	Description
milestones	number[]	[25, 50, 75, 100]	Percentages to fire callback at
onMilestone	(pct: number) => void	—	Fired when each milestone is crossed

Returns: { scrollDepth }

---

useInputHesitation

Detects uncertainty in form fields, user types, long pause, then deletes.

import { useInputHesitation } from "react-sentiments";

function SignupForm() {
  const { onChange } = useInputHesitation({
    pauseThreshold: 2000,
    onHesitation: ({ value, pauseDuration, deletedAfterPause }) => {
      if (deletedAfterPause) {
        showFieldHint("Not sure what to enter? Here's an example.");
      }
      analytics.track("input_hesitation", { field: "email", pauseDuration });
    },
  });

  return <input type="email" onChange={onChange} placeholder="Email" />;
}

Options

Option	Type	Default	Description
pauseThreshold	number	2000	Pause in ms before hesitation fires
onHesitation	(info: InputHesitationInfo) => void	required	Fired on hesitation

InputHesitationInfo

Field	Type	Description
value	string	Field value at time of hesitation
pauseDuration	number	How long the pause was in ms
deletedAfterPause	boolean	Whether user deleted text after pausing

Returns: { onChange }

---

useCopyIntent

Detects when a user selects text, and whether they followed through with an actual copy.

import { useCopyIntent } from "react-sentiments";

function CodeBlock({ code }: { code: string }) {
  const { onMouseUp, onCopy } = useCopyIntent({
    onSelect: (text) => analytics.track("text_selected", { text }),
    onCopy: (text) => analytics.track("text_copied", { text }),
  });

  return <pre onMouseUp={onMouseUp} onCopy={onCopy}>{code}</pre>;
}

Options

Option	Type	Default	Description
onSelect	(text: string) => void	—	Fired when user selects text
onCopy	(text: string) => void	—	Fired when user copies text

Returns: { onMouseUp, onCopy }

---

useReread

Detects when a user scrolls back to re-read a section, could mean confusion or high interest.

import { useReread } from "react-sentiments";

function ComplexSection() {
  const { ref, rereadCount } = useReread({
    threshold: 2,
    onReread: (count) => {
      if (count >= 2) showExplainerTooltip("Need a hand with this section?");
      analytics.track("section_reread", { count });
    },
  });

  return (
    <section ref={ref}>
      <h2>How our pricing works</h2>
      <p>...</p>
    </section>
  );
}

Options

Option	Type	Default	Description
threshold	number	2	Number of rereads before firing callback
onReread	(count: number) => void	—	Fired when threshold is crossed

Returns: { ref, rereadCount }

---

useSessionFrustration

Aggregates all frustration signals into a single score from 0–100. Use it alongside the other hooks.

import {
  useSessionFrustration,
  useRageClick,
  useExitIntent,
  useDeadClick,
} from "react-sentiments";

function App() {
  const { score, signals, addSignal, reset } = useSessionFrustration();

  useRageClick({ onRageClick: () => addSignal("rageClick") });
  useExitIntent({ onExitIntent: () => addSignal("exitIntent") });
  useDeadClick({ onDeadClick: () => addSignal("deadClick") });

  useEffect(() => {
    if (score >= 60) {
      openLiveChat("Looks like you're having trouble — can we help?");
    }
  }, [score]);

  return (
    <div>
      <p>Frustration score: {score}/100</p>
      <p>Signals: {signals.join(", ")}</p>
      <button onClick={reset}>Reset</button>
    </div>
  );
}

Signal weights

Signal	Weight
rageClick	25
exitIntent	20
deadClick	15
hesitation	10
inputHesitation	10
reread	5

Returns: { score, signals, addSignal, reset }

---

Real world example — putting it all together

import {
  useSessionFrustration,
  useRageClick,
  useExitIntent,
  useDeadClick,
  useScrollDepth,
  useEngagementTime,
} from "react-sentiments";

function CheckoutPage() {
  const { score, addSignal } = useSessionFrustration();
  const { engagementTime } = useEngagementTime();
  const { scrollDepth } = useScrollDepth({
    onMilestone: (pct) => analytics.track("scroll", { pct }),
  });

  useRageClick({
    onRageClick: (count) => {
      addSignal("rageClick");
      analytics.track("rage_click", { count });
    },
  });

  useExitIntent({
    onExitIntent: () => {
      addSignal("exitIntent");
      if (score > 40) showExitModal("Need help completing your order?");
    },
  });

  useDeadClick({
    scope: "#checkout-form",
    onDeadClick: (el) => {
      addSignal("deadClick");
      console.warn("Dead click on:", el);
    },
  });

  return (
    <div>
      <form id="checkout-form">...</form>
      {/* Debug panel — remove in production */}
      <pre>Score: {score} | Time: {engagementTime}s | Depth: {scrollDepth}%</pre>
    </div>
  );
}

---

TypeScript

All hooks are fully typed. You can import option and return types directly:

import type {
  UseRageClickOptions,
  UseHesitationOptions,
  InputHesitationInfo,
  FrustrationSignal,
} from "react-sentiments";

---

License

MIT