Next.js

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

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

📘
Before you start
You'll need a Next.js 13.4+ project and your Userback access token. Click the Code icon in the top-right corner of your workspace to find it.

Installation

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

npm i @userback/widget

Quickstart

You can initialize 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(() => {
    // Access token for embedding the Userback widget (not the API token).
		// Recommended: store it in an environment variable like NEXT_PUBLIC_USERBACK_TOKEN instead of hardcoding.
    const token = 'YOUR_ACCESS_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(() => {
    // Access token for embedding the Userback widget (not the API token).
		// Recommended: store it in an environment variable like NEXT_PUBLIC_USERBACK_TOKEN instead of hardcoding.
    const token: string = 'YOUR_ACCESS_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 your Next.js app

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

General approach

Initialize 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

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);

// Access token for embedding the Userback widget (not the API token).
// Recommended: store it in an environment variable like NEXT_PUBLIC_USERBACK_TOKEN instead of hardcoding.
const token = 'YOUR_ACCESS_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);

Add to your app layout

Modify your root layout file to wrap your app with UserbackProvider:

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>
  );
}

Use in any client component

'use client';

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

const FeedbackButton = () => {
  const userbackInstance = useUserback();
  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.

Need help? Visit the Help Center or use the chat bubble on this page to contact our support team.