@posthog/react 1.6.0 → 1.7.0

package/dist/esm/surveys/index.js

@@ -0,0 +1,50 @@
+import { createContext, useContext, useState, useMemo, useRef, useCallback } from 'react';
+import posthogJs, { SurveyPosition, DisplaySurveyType } from 'posthog-js';
+
+var PostHogContext = createContext({
+    client: posthogJs,
+    bootstrap: undefined,
+});
+
+var usePostHog = function () {
+    var client = useContext(PostHogContext).client;
+    return client;
+};
+
+var TRIGGER_ATTR = 'data-ph-thumb-survey-trigger';
+function useThumbSurvey(_a) {
+    var surveyId = _a.surveyId, _b = _a.displayPosition, displayPosition = _b === void 0 ? SurveyPosition.NextToTrigger : _b, properties = _a.properties, onResponse = _a.onResponse;
+    var posthog = usePostHog();
+    var _c = useState(null), responded = _c[0], setResponded = _c[1];
+    var instanceId = useState(function () { return Math.random().toString(36).slice(2, 9); })[0];
+    var triggerValue = useMemo(function () { return "".concat(surveyId, "-").concat(instanceId); }, [surveyId, instanceId]);
+    var elementRef = useRef(null);
+    var triggerRef = useCallback(function (el) {
+        if (elementRef.current) {
+            elementRef.current.removeAttribute(TRIGGER_ATTR);
+        }
+        elementRef.current = el;
+        if (el) {
+            el.setAttribute(TRIGGER_ATTR, triggerValue);
+        }
+    }, [triggerValue]);
+    var respond = useCallback(function (value) {
+        if (!(posthog === null || posthog === void 0 ? void 0 : posthog.surveys) || responded)
+            return;
+        setResponded(value);
+        onResponse === null || onResponse === void 0 ? void 0 : onResponse(value);
+        posthog.surveys.displaySurvey(surveyId, {
+            displayType: DisplaySurveyType.Popover,
+            ignoreConditions: true,
+            ignoreDelay: true,
+            properties: properties,
+            initialResponses: { 0: value === 'up' ? 1 : 2 },
+            position: displayPosition,
+            selector: "[".concat(TRIGGER_ATTR, "=\"").concat(triggerValue, "\"]"),
+        });
+    }, [posthog, surveyId, displayPosition, properties, responded, onResponse, triggerValue]);
+    return { respond: respond, response: responded, triggerRef: triggerRef };
+}
+
+export { useThumbSurvey };
+//# sourceMappingURL=index.js.map

package/dist/esm/surveys/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/context/PostHogContext.ts","../../../src/hooks/usePostHog.ts","../../../src/hooks/useThumbSurvey.ts"],"sourcesContent":[null,null,null],"names":[],"mappings":"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"}

package/dist/types/surveys/index.d.ts

@@ -0,0 +1,17 @@
+import { RefCallback } from 'react';
+import { SurveyPosition } from 'posthog-js';
+
+interface UseThumbSurveyOptions {
+    surveyId: string;
+    displayPosition?: SurveyPosition;
+    properties?: Record<string, any>;
+    onResponse?: (response: 'up' | 'down') => void;
+}
+interface UseThumbSurveyResult {
+    respond: (value: 'up' | 'down') => void;
+    response: 'up' | 'down' | null;
+    triggerRef: RefCallback<HTMLElement>;
+}
+declare function useThumbSurvey({ surveyId, displayPosition, properties, onResponse, }: UseThumbSurveyOptions): UseThumbSurveyResult;
+
+export { type UseThumbSurveyOptions, type UseThumbSurveyResult, useThumbSurvey };

package/dist/umd/surveys/index.js

@@ -0,0 +1,59 @@
+(function (global, factory) {
+    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('react'), require('posthog-js')) :
+    typeof define === 'function' && define.amd ? define(['exports', 'react', 'posthog-js'], factory) :
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.PosthogReactSurveys = {}, global.React, global.posthog));
+})(this, (function (exports, React, posthogJs) { 'use strict';
+
+    function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+    var posthogJs__default = /*#__PURE__*/_interopDefaultLegacy(posthogJs);
+
+    var PostHogContext = React.createContext({
+        client: posthogJs__default["default"],
+        bootstrap: undefined,
+    });
+
+    var usePostHog = function () {
+        var client = React.useContext(PostHogContext).client;
+        return client;
+    };
+
+    var TRIGGER_ATTR = 'data-ph-thumb-survey-trigger';
+    function useThumbSurvey(_a) {
+        var surveyId = _a.surveyId, _b = _a.displayPosition, displayPosition = _b === void 0 ? posthogJs.SurveyPosition.NextToTrigger : _b, properties = _a.properties, onResponse = _a.onResponse;
+        var posthog = usePostHog();
+        var _c = React.useState(null), responded = _c[0], setResponded = _c[1];
+        var instanceId = React.useState(function () { return Math.random().toString(36).slice(2, 9); })[0];
+        var triggerValue = React.useMemo(function () { return "".concat(surveyId, "-").concat(instanceId); }, [surveyId, instanceId]);
+        var elementRef = React.useRef(null);
+        var triggerRef = React.useCallback(function (el) {
+            if (elementRef.current) {
+                elementRef.current.removeAttribute(TRIGGER_ATTR);
+            }
+            elementRef.current = el;
+            if (el) {
+                el.setAttribute(TRIGGER_ATTR, triggerValue);
+            }
+        }, [triggerValue]);
+        var respond = React.useCallback(function (value) {
+            if (!(posthog === null || posthog === void 0 ? void 0 : posthog.surveys) || responded)
+                return;
+            setResponded(value);
+            onResponse === null || onResponse === void 0 ? void 0 : onResponse(value);
+            posthog.surveys.displaySurvey(surveyId, {
+                displayType: posthogJs.DisplaySurveyType.Popover,
+                ignoreConditions: true,
+                ignoreDelay: true,
+                properties: properties,
+                initialResponses: { 0: value === 'up' ? 1 : 2 },
+                position: displayPosition,
+                selector: "[".concat(TRIGGER_ATTR, "=\"").concat(triggerValue, "\"]"),
+            });
+        }, [posthog, surveyId, displayPosition, properties, responded, onResponse, triggerValue]);
+        return { respond: respond, response: responded, triggerRef: triggerRef };
+    }
+
+    exports.useThumbSurvey = useThumbSurvey;
+
+}));
+//# sourceMappingURL=index.js.map

package/dist/umd/surveys/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/context/PostHogContext.ts","../../../src/hooks/usePostHog.ts","../../../src/hooks/useThumbSurvey.ts"],"sourcesContent":[null,null,null],"names":["createContext","posthogJs","useContext","SurveyPosition","useState","useMemo","useRef","useCallback","DisplaySurveyType"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/react",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Provides components and hooks for React integrations of PostHog.",
   "repository": {
     "type": "git",
@@ -15,7 +15,8 @@
   "types": "dist/types/index.d.ts",
   "files": [
     "dist",
-    "src"
+    "src",
+    "surveys"
   ],
   "peerDependencies": {
     "@types/react": ">=16.8.0",
@@ -47,7 +48,7 @@
     "tslib": "^2.5.0",
     "typescript": "5.8.2",
     "@posthog-tooling/rollup-utils": "1.1.1",
-    "posthog-js": "1.331.0"
+    "posthog-js": "1.332.0"
   },
   "scripts": {
     "clean": "rimraf dist",

package/src/hooks/useThumbSurvey.ts

@@ -0,0 +1,113 @@
+import { useState, useCallback, useRef, useMemo, type RefCallback } from 'react'
+import { usePostHog } from './usePostHog'
+import { DisplaySurveyType, SurveyPosition } from 'posthog-js'
+
+export interface UseThumbSurveyOptions {
+    /** ID of the target PostHog survey */
+    surveyId: string
+    /** Configure the position of the pop-up for followup questions, if applicable. Defaults to SurveyPosition.NextToTrigger */
+    displayPosition?: SurveyPosition
+    /** Custom event properties to pass with each survey result */
+    properties?: Record<string, any>
+    /** Callback on thumb button click */
+    onResponse?: (response: 'up' | 'down') => void
+}
+
+export interface UseThumbSurveyResult {
+    /** Call this to submit a survey response, with value 'up' or 'down' */
+    respond: (value: 'up' | 'down') => void
+    /** User's response value, available after submission */
+    response: 'up' | 'down' | null
+    /** Ref to attach to the trigger element for positioning the followup survey popup */
+    triggerRef: RefCallback<HTMLElement>
+}
+
+const TRIGGER_ATTR = 'data-ph-thumb-survey-trigger'
+
+/**
+ * Convenience hook for managing a "thumb" (1-2 rating scale) survey.
+ *
+ * Pre-requisites:
+ * 1) Ensure surveys are not disabled in your PostHog config (`disable_surveys: false`)
+ * 2) Ensure surveys are enabled in your PostHog project (Settings > Surveys > Enable surveys)
+ *
+ * How-to:
+ * 1) Create an API survey in PostHog (New survey > Presentation > API)
+ * 2) Set the first question to a thumb rating scale (Question type: Rating -> Display type: Emoji -> Scale: 1-2 (thumbs up/down))
+ * 3) Set the thumb question to "Automatically submit on selection"
+ * 4) Optionally add follow-up questions
+ * 5) Use the hook:
+ *
+ * ```typescript
+ * const { respond, response, triggerRef } = useThumbSurvey({
+ *  surveyId: 'my-survey-id',
+ *  properties: { foo: 'bar' }, // optional custom properties to pass along with the survey responses
+ *  onResponse: (response) => { console.log(response) }, // optional callback on submission
+ * })
+ *
+ * return (
+ *  <div ref={triggerRef}>
+ *      <button onClick={() => respond('up')} style={{ color: response === 'up' ? 'green' : undefined }}>👍</button>
+ *      <button onClick={() => respond('down')} style={{ color: response === 'down' ? 'red' : undefined }}>👎</button>
+ *  </div>
+ * )
+ * ```
+ *
+ * 6) If your survey has further questions, the survey will automatically display as a popover, either:
+ *  - [default] next to the triggerRef element,
+ *  - OR wherever you specify in options.position
+ *
+ * Notes:
+ * - The thumbs up/down response will ALWAYS be recorded, whether your survey is set to collect partial responses or not.
+ * - By default, followup questions will be displayed as a pop-up next to the triggerRef. Use options.position to change the position.
+ *
+ * @param options UseThumbSurveyOptions
+ * @returns UseThumbSurveyResult
+ */
+export function useThumbSurvey({
+    surveyId,
+    displayPosition = SurveyPosition.NextToTrigger,
+    properties,
+    onResponse,
+}: UseThumbSurveyOptions): UseThumbSurveyResult {
+    const posthog = usePostHog()
+    const [responded, setResponded] = useState<'up' | 'down' | null>(null)
+    const [instanceId] = useState(() => Math.random().toString(36).slice(2, 9))
+    const triggerValue = useMemo(() => `${surveyId}-${instanceId}`, [surveyId, instanceId])
+
+    const elementRef = useRef<HTMLElement | null>(null)
+    const triggerRef = useCallback(
+        (el: HTMLElement | null) => {
+            if (elementRef.current) {
+                elementRef.current.removeAttribute(TRIGGER_ATTR)
+            }
+            elementRef.current = el
+            if (el) {
+                el.setAttribute(TRIGGER_ATTR, triggerValue)
+            }
+        },
+        [triggerValue]
+    )
+
+    const respond = useCallback(
+        (value: 'up' | 'down') => {
+            if (!posthog?.surveys || responded) return
+
+            setResponded(value)
+            onResponse?.(value)
+
+            posthog.surveys.displaySurvey(surveyId, {
+                displayType: DisplaySurveyType.Popover,
+                ignoreConditions: true,
+                ignoreDelay: true,
+                properties,
+                initialResponses: { 0: value === 'up' ? 1 : 2 },
+                position: displayPosition,
+                selector: `[${TRIGGER_ATTR}="${triggerValue}"]`,
+            })
+        },
+        [posthog, surveyId, displayPosition, properties, responded, onResponse, triggerValue]
+    )
+
+    return { respond, response: responded, triggerRef }
+}

package/src/surveys/index.ts

@@ -0,0 +1 @@
+export * from '../hooks/useThumbSurvey'

package/surveys/package.json

@@ -0,0 +1,7 @@
+{
+    "name": "@posthog/react-surveys",
+    "private": true,
+    "main": "../dist/umd/surveys/index.js",
+    "module": "../dist/esm/surveys/index.js",
+    "types": "../dist/types/surveys/index.d.ts"
+}