Skip to content

Developer guide

How to Collect Feedback in React & Next.js

Add a feedback component that fits your app, handle real request outcomes, and confirm that the first response reaches your inbox.

The Pollenate Team8 min read

Add feedback to a React or Next.js app with the PollenateWidget component, a script tag, or your own UI calling /collect. This guide shows the component first, then a direct API implementation that handles both success and failure.

Before you start, create an inbox and an organization API key with only the collect scope. Copy the inbox key, not its display name. Personal keys and OAuth tokens are not accepted by /collect.

Use the React component

Install the package:

npm install @pollenate/react

In a Vite React app, set VITE_POLLENATE_INBOX_KEY and VITE_POLLENATE_COLLECT_KEY in your local environment, then render:

import { PollenateWidget } from '@pollenate/react';

export function FeatureFeedback() {
  return (
    <PollenateWidget
      inboxKey={import.meta.env.VITE_POLLENATE_INBOX_KEY}
      apiKey={import.meta.env.VITE_POLLENATE_COLLECT_KEY}
      type="thumbs"
      inline
      prompt="Was this feature useful?"
      theme="auto"
      stripQueryParams
      context={{ feature: 'report-export', version: 'v2' }}
      onSubmit={(event) => {
        console.log('Accepted feedback ID:', event.detail.id);
      }}
    />
  );
}

Mount it after the part of the workflow you want feedback on. Omit inline for a floating widget. The component supplies rating selection, an optional comment, loading/error states, and a success message. Avoid mounting several floating widgets at once.

Next.js App Router: use a Client Component

The widget is interactive. Put it behind a client boundary and use Next.js public environment variable names:

// app/components/FeatureFeedback.tsx
'use client';

import { PollenateWidget } from '@pollenate/react';
import { usePathname } from 'next/navigation';

export function FeatureFeedback() {
  const pathname = usePathname();
  const inboxKey = process.env.NEXT_PUBLIC_POLLENATE_INBOX_KEY;
  const apiKey = process.env.NEXT_PUBLIC_POLLENATE_COLLECT_KEY;

  if (!inboxKey || !apiKey) return null;

  return (
    <PollenateWidget
      key={pathname}
      inboxKey={inboxKey}
      apiKey={apiKey}
      type="thumbs"
      inline
      prompt="Was this page helpful?"
      theme="auto"
      stripQueryParams
      context={{ surface: 'docs', path: pathname }}
    />
  );
}

Render <FeatureFeedback /> beneath the content being rated. The key remounts the inline widget when the route changes, resetting its completed state for the next page. If you want one feedback opportunity across the whole session, choose that behavior explicitly instead.

A script-tag integration is also possible with Next.js Script. Use strategy="afterInteractive", the documented widget data-* attributes, and one stable mount location. Do not combine the script and React component for the same prompt.

Build your own feedback UI

Use a direct request if your design needs a different interaction. This example is a Client Component for Next.js; in Vite, replace process.env.NEXT_PUBLIC_* with the corresponding import.meta.env.VITE_* variables.

'use client';

import { useState } from 'react';

export function HelpfulButtons() {
  const [state, setState] = useState<'idle' | 'sending' | 'sent'>('idle');
  const [error, setError] = useState('');

  async function submit(score: 0 | 1) {
    const inboxKey = process.env.NEXT_PUBLIC_POLLENATE_INBOX_KEY;
    const apiKey = process.env.NEXT_PUBLIC_POLLENATE_COLLECT_KEY;
    if (!inboxKey || !apiKey) {
      setError('Feedback is not configured yet.');
      return;
    }
    setState('sending');
    setError('');
    try {
      const response = await fetch('https://api.pollenate.dev/collect', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-Pollenate-Key': apiKey,
        },
        body: JSON.stringify({
          inboxKey,
          type: 'thumbs',
          score,
          pageUrl: window.location.origin + window.location.pathname,
          context: { feature: 'quickstart', version: 'v2' },
        }),
      });
      if (!response.ok) throw new Error(`Submission failed (${response.status})`);
      setState('sent');
    } catch {
      setState('idle');
      setError('We could not send your feedback. Please try again.');
    }
  }

  if (state === 'sent') return <p role="status">Thanks for the feedback.</p>;

  return (
    <div>
      <p>Was this helpful?</p>
      <button disabled={state === 'sending'} onClick={() => submit(1)}>Yes</button>
      <button disabled={state === 'sending'} onClick={() => submit(0)}>No</button>
      {state === 'sending' && <p role="status">Sending…</p>}
      {error && <p role="alert">{error}</p>}
    </div>
  );
}

fetch does not throw for an HTTP 400 or 429. Checking response.ok prevents your interface from thanking someone for a response the server rejected. The custom metadata property is context, not meta.

Keys, navigation, and content security

Public environment variables are bundled into browser code. Treat the collect-only key as visible to visitors: restrict it to the required scope and brand. Keep read, write, administrative, and other privileged credentials on your server.

The widget captures the active page URL when submitting. Pass feature or release context yourself. Revisit the prompt when the route or task changes, and do not assume every context field becomes a dashboard filter.

For the React package, your policy must allow the API connection and the component’s styling. A script integration additionally needs https://pollenate.dev in its script policy. Inspect actual console errors and test your policy rather than assuming every failed request is a CSP problem.

Verify the complete flow

  1. Confirm the widget appears at the intended point on mobile and desktop.
  2. Submit a test rating and comment, then confirm HTTP 201.
  3. Verify the response, URL, and context in the destination inbox.
  4. Navigate between routes and check that the prompt behaves as intended.
  5. Exercise a failed request and confirm the UI allows a retry without showing success.

Create your collection key, explore the developer API, or use a shareable form when the question needs more space.

Frequently Asked Questions

How do I use Pollenate in the Next.js App Router?
Render PollenateWidget inside a Client Component with a use client directive. Use NEXT_PUBLIC environment variables for a collect-only key and inbox key, and choose whether the prompt should reset when the route changes.
Can a collection key appear in browser code?
A collect-only organization key is intended for a browser collector and is visible to visitors. Restrict it to the needed scope and brand. Never expose administrative, read, or other privileged credentials.
Why does my custom UI show success when the API failed?
Fetch resolves for HTTP errors such as 400 and 429. Check response.ok before showing success, keep an error state, and allow the user to retry.

Send your first feedback event

Create a collect-only key, connect your interface, and verify the response with its context.