React

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

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

📘
Before you start
You'll need your Userback access token. Click the Code icon in the top-right corner of your workspace to find it.

Installation

Install the Userback package for React using the following command.

npm i @userback/widget

Quickstart

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

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('YOUR_ACCESS_TOKEN', options);

// Update user data when it changes or your user logs out and logs back in
const user_id = '123456'; // replace with your user's unique ID
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('YOUR_ACCESS_TOKEN', options);

// Update user data when it changes or your user logs out and logs back in
const user_id = '123456'; // replace with your user's unique ID
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.

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('YOUR_ACCESS_TOKEN', options);
  return userbackInstance;
}

export function getUserback() {
  return userbackInstance;
}

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

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('YOUR_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>;
}

See the npm package docs for additional use cases including surveys, widget control, and custom events.

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