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 you begin, ensure the following:

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

Install the Userback package for React using the following command:

NPM Installation

npm i @userback/widget

Quickstart

Embed the Userback Widget in your React application using the example below:

Code Example

import Userback from '@userback/widget';

// identify your logged-in users (optional)
const options = {
  user_data: {
    id: "123456",
    info: {
      name: "someone",
      email: "[email protected]"
    }
  }
};

// initialize Userback
const userback = await Userback("**Userback Access Token**", options);

// Update user data
// Use it when user data changes or your user logs out and logs back in
userback.identify(user_id, {
    name: 'Jane Doe'
    email: '[email protected]'
});

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

// Optionally identify logged-in users
const options: UserbackOptions = {
  user_data: {
    id: "123456", // Unique user ID
    info: {
      name: "someone", // User's name
      email: "[email protected]" // User's email
    }
  }
};

// Initialize Userback with the access token and options
const userback:UserbackWidget = await Userback('**Userback Access Token**', options);

// Update user data
// Use it when user data changes or your user logs out and logs back in
userback.identify(user_id, {
    name: 'Jane Doe'
    email: '[email protected]'
});

Using Userback in React 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().

Examples:

Here are a few examples of how you can integrate and use Userback throughout your React app.

Example 1: Setting up a shared instance and use in a component

Create a simple module (eg: userbackClient.js) to manage the shared instance:

// userbackClient.js
import Userback from '@userback/widget';

let userbackInstance;

export async function initUserback(options) {
  userbackInstance = await Userback("**Userback Access Token**", options);
  return userbackInstance;
}

export function getUserback() {
  return userbackInstance;
}

Using in a Component

// FeedbackButton.jsx
import React from 'react';
import { getUserback } from './userbackClient';

export function FeedbackButton() {
  const handleClick = () => {
    const userback = getUserback();
    if (userback) userback.openForm('bug');
  };

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

Example 2: Using React Context

This pattern is great for larger apps that want to expose the Userback instance globally with React hooks.

Create Context Provider

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

const UserbackContext = createContext(null);

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

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

    init();
  }, []);

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

export const useUserback = () => useContext(UserbackContext);

Wrap Your App

// main.jsx or App.jsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import { UserbackProvider } from './UserbackProvider';

ReactDOM.createRoot(document.getElementById('root')).render(
  <UserbackProvider>
    <App />
  </UserbackProvider>
);

Use in Component

// FeedbackButton.jsx
import React from 'react';
import { useUserback } from './UserbackProvider';

export function FeedbackButton() {
  const userback = useUserback();

  const handleClick = () => {
    if (userback) {
      userback.openForm('bug');
    }
  };

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

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.