React integration with useThumbSurvey

To quickly integrate with your React app, we provide a hook useThumbSurvey that exposes a method to submit survey responses, the user's response, and a ref to position followup question pop-ups.

Quickstart

Note: This hook requires @posthog/react 1.7.1+, which is bundled with posthog-js 1.345.1+

Initialize the hook with the following options:

typescript
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
    /** Disable automatically emitting `survey shown` on hook mount. Defaults to false. */
    disableAutoShownTracking?: boolean
}

It returns the following interface:

typescript
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. Not persisted across mounts. */
    response: 'up' | 'down' | null
    /** Ref to attach to the trigger element for positioning the followup survey popup */
    triggerRef: RefCallback<HTMLElement>
    /** Method to manually trigger a `survey shown` event. Only available when disableAutoShownTracking is true. */
    trackShown?: () => void
}

A simple usage of this hook, including a followup question pop-up, looks like this:

typescript
// requires @posthog/react 1.7.1+ (bundled with posthog-js 1.345.1+)
import { useThumbSurvey } from 'posthog-js/react/surveys'

function HedgehogBotResponse({ traceId }: { traceId: string }) {
  const { respond, response, triggerRef } = useThumbSurvey({
    surveyId: '019bb5a3-1677-0000-63dd-00f241c1710a', // ID for the survey you just created
    properties: {
      $ai_trace_id: traceId, // your generated trace ID
      // add any other custom properties here to be attached to `survey sent` and `survey shown` events
    },
  })

  return (
    <div>
      <ChatBubble>You're absolutely right! I should have been using PostHog all along.</ChatBubble>

      {/* PostHog followup pop-up anchors to triggerRef. If not provided, defaults to showing on the center of the page. */}
      <div ref={triggerRef}>
        <p>Was this response helpful?</p>
        <button onClick={() => respond('up')} >
          <ThumbsUpIcon className={response === 'up' ? 'active' : ''} />
        </button>
        <button onClick={() => respond('down')} >
          <ThumbsDownIcon className={response === 'down' ? 'active' : ''} />
        </button>
      </div>

    </div>
  )
}

Impression tracking

By default, the hook emits a survey shown (impression) event on mount.

Duplicate impression events will not impact your ability to see responses within LLM Analytics, but may skew metrics viewed directly from Surveys.

To disable this behavior, initialize the hook with disableAutoShownTracking: true and manually call trackShown() when you consider your survey to be "shown."

Response persistence

The hook's response value is not persisted across mounts. We plan to improve this soon, but in the meantime, you'll need to set up your own persistent response tracking if needed.

Question indices

The hook submits survey responses using the legacy index-based tracking for survey questions. If you add or re-order survey questions from the Surveys UI, you may experience unexpected behavior. See Implementing custom surveys for more information.

Survey compatibility

To use this hook, your survey must begin with a thumbs up/down question. All other surveys features are supported, such as followup questions and question branching.

For more information, see the hook source here on GitHub, or a real implementation in the PostHog codebase here.