handhold-react

The Handhold help UI as React components — the exact look from the demo (the "PaidHR assistant" panel, guided-workflow cards, the on-page pulse indicator, and the "Do it for me" agent panel), wired to handhold-sdk.

Use this when your app is React and you want the polished UI verbatim, rather than the framework-agnostic default that ships inside handhold-sdk.

Install

npm i handhold-react handhold-sdk

react, react-dom and handhold-sdk are peer dependencies.

Use — one component

import HandHold from 'handhold-sdk';
import { HandholdWidget } from 'handhold-react';
import 'handhold-react/styles.css';

// Initialize the SDK as a headless engine (let React render the UI):
HandHold.init({
  apiKey: 'hh_pk_YOUR_SDK_KEY',
  baseUrl: 'https://help.yourapp.com',
  showHelpButton: false,     // this package renders the trigger
  showStepHighlight: false,  // this package renders the on-page pulse
  deferRestore: true,
}).then(() => HandHold.restoreSession());

// …then mount once, anywhere in your tree:
function App() {
  return (
    <>
      <YourApp />
      <HandholdWidget />
    </>
  );
}

HandholdWidget subscribes to the SDK's state (useSyncExternalStore) and drives it via the SDK's command methods — no props required. For full control you can also import the individual pieces: WidgetPanel, GuidancePanel, AgentRunPanel, PulseIndicator, WidgetTrigger.

Styling

The components are styled with Tailwind v4 tokens (the paidhr-blue palette lives in src/styles.css). Build the stylesheet once and import it (as shown above):

npm run build        # tailwind -> dist/handhold-react.css

If your app already runs Tailwind v4, you can instead add src/styles.css's @theme block to your own CSS and skip the prebuilt file.

The demo self-hosts the "Circular Std" typeface; it's omitted here (falls back to the system/Manrope stack). Add your own @font-face for the exact face.

Publish

Published on npm as handhold-react. To cut a new version:

cd handhold-react
npm install
npm version patch      # bump
npm run build          # prepublishOnly also runs this (dist/index.js + dist/handhold-react.css)
npm publish            # public (publishConfig.access = public)

Build pipeline

npm run build produces a self-contained dist/:

• build:js (tsup) bundles the components → dist/index.js (ESM), transpiling JSX and bundling in gsap / lottie-react (incl. the CJS lottie-web) / @phosphor-icons/react. Only react, react-dom and handhold-sdk stay external (peers / shared singleton).
• build:css (Tailwind v4) → dist/handhold-react.css.

This is what makes a plain npm i handhold-react work with zero bundler config — verified by installing the packed tarball into a clean Vite React app (no loader or interop tweaks needed). handhold-sdk is consumed via its ESM build (dist/handhold.esm.js, assets inlined), not source.