Overview

The official NPM module for embedding the Userback Widget into your React application.

Official NPM Package: @userback/widget
Official GitHub Repository: Userback Widget SDK

Prerequisites

Before starting, ensure you have:

A Next.js 13.4+ project
Userback Workspace: A workspace is needed to collect and manage feedback.
Access Token: Retrieve your token via the Code Icon in your workspace.
Plan Requirements: Available on all plans.

Installation

To install the Userback package and embed the widget in your application, use the following command:

NPM Installation

npm i @userback/widget

Quickstart

You can initialise the Userback widget globally in the top-level layout so that it’s available throughout your Next.js app.

'use client';

import { useEffect } from 'react';
import Userback from '@userback/widget';

const UserbackWidget = () => {
  useEffect(() => {
    const token = '**Userback Access Token**'; // Replace with your actual token
    const options = {
      user_data: {
        id: '123456',
        info: {
          name: 'someone',
          email: '[email protected]'
        }
      }
    };

    Userback(token, options).then((userback_instance) => {
      console.log('Userback widget loaded');
    });
  }, []);

  return null;
};

export default UserbackWidget;

'use client';

import { useEffect } from 'react';
import Userback from '@userback/widget';
import type { UserbackOptions, UserbackWidget } from '@userback/widget';

const UserbackWidget = () => {
  useEffect(() => {
    const token: string = '**Userback Access Token**'; // Replace with your actual token

    const options: UserbackOptions = {
      user_data: {
        id: '123456',
        info: {
          name: 'someone',
          email: '[email protected]'
        }
      }
    };

    Userback(token, options).then((userback_instance: UserbackWidget) => {
      console.log('Userback widget loaded');
    });
  }, []);

  return null;
};

export default UserbackWidget;

Using Userback in Next.js App

You can initialize Userback once and use the instance throughout your app.

General Approach

Initialise the Userback widget once — for example, in your root file or when the user logs in.
Store the instance (returned as a Promise) in a context, global store, or a simple module.
Use the instance in any component or hook to trigger actions like openForm(), identify(), or startSessionReplay().

Example:

Step 1: Create UserbackProvider.client.jsx

Create a new component in your app (e.g. components/UserbackProvider.client.jsx):

'use client';

import React, {
  createContext,
  useContext,
  useEffect,
  useState,
} from 'react';
import Userback from '@userback/widget';

// Create the context
const UserbackContext = createContext(null);

// Get token from environment or use fallback
const token = 'YOUR_USERBACK_TOKEN';

export const UserbackProvider = ({ children }) => {
  const [userback, setUserback] = useState(null);

  useEffect(() => {
    const init = async () => {
      const instance = await Userback(token, {
        user_data: {
          id: '123456',
          info: {
            name: 'Jane Doe',
            email: '[email protected]',
          },
        },
        autohide: false,
      });
      setUserback(instance);
    };

    init();
  }, []);

  return (
    <UserbackContext.Provider value={userback}>
      {children}
    </UserbackContext.Provider>
  );
};

// Custom hook to access Userback instance
export const useUserback = () => useContext(UserbackContext);

✅ Replace the access_token and user data with real values.

Step 2: Add to Your App Layout

Edit app/layout.jsx

Modify your layout file to include the UserbackWidget.

import './globals.css';
import { Inter } from 'next/font/google';
import UserbackProvider from '../components/UserbackProvider.client';

const inter = Inter({ subsets: ['latin'] });

export const metadata = {
  title: 'My App',
  description: 'App with Userback Integration',
};

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <UserbackProvider>
          {children}
        </UserbackProvider>
      </body>
    </html>
  );
}

Step 3: Use in any client component

'use client';

import { userbackInstance } from '../components/UserbackProvider.client';

const FeedbackButton = () => {
  const handleClick = () => {
    if (userbackInstance) {
      userbackInstance.openForm(); // or .show(), etc.
    } else {
      console.warn('Userback is not ready yet');
    }
  };

  return <button onClick={handleClick}>Open Feedback</button>;
};

export default FeedbackButton;

For more use cases, refer to the Userback Npm docs.

🛟 Support

Need help? Here’s how to get assistance:

Log in to your Userback workspace.
Click the Help Center icon in the top-right corner.
Select Contact us to start a chat with our support team.