Events

info

This feature is only available on the Professional and Unlimited plans. The widget checks the project's plan capabilities before emitting events, and that configuration is cached for up to 60 seconds, so a plan change can take a minute to take effect.

This guide explains how to listen for events emitted by the feedback widget and handle them with JavaScript.

Events overview

The feedback widget emits the following events:

• feedbackSent: Emitted when feedback is successfully submitted. See Feedback event object format for the payload shape.
• feedbackError: Emitted if there is an error during feedback submission.

By listening to these events, you can handle feedback dynamically, such as storing it in your database or performing any custom actions.

How to listen for events

You can listen for feedbackSent and feedbackError events globally by attaching event listeners directly to the document object. This approach captures events emitted anywhere in the DOM, making it convenient to handle feedback without needing direct access to the feedback widget.

Here’s how you can add event listeners to capture these events:

JavaScript

document.addEventListener('DOMContentLoaded', () => {
  document.addEventListener('feedbackSent', (event) => {
    const feedback = event.detail.feedback;
    console.log('Feedback submitted:', feedback);

    // Example custom action: store feedback in your database
    storeFeedbackInDatabase(feedback);
  });

  document.addEventListener('feedbackError', (event) => {
    const error = event.detail.error;
    console.error('Feedback submission error:', error);

    // Example custom action: show error message to the user
    showErrorToUser(error.message);
  });
});

React

import React, { useEffect } from 'react';

const FeedbackListener = () => {
  useEffect(() => {
    // Define the handler for feedbackSent
    const handleFeedbackSent = (event) => {
      const feedback = event.detail.feedback;
      console.log('Feedback submitted:', feedback);

      // Example custom action: store feedback in your database
      storeFeedbackInDatabase(feedback);
    };

    // Define the handler for feedbackError
    const handleFeedbackError = (event) => {
      const error = event.detail.error;
      console.error('Feedback submission error:', error);

      // Example custom action: show error message to the user
      showErrorToUser(error.message);
    };

    // Add event listeners
    document.addEventListener('feedbackSent', handleFeedbackSent);
    document.addEventListener('feedbackError', handleFeedbackError);

    // Cleanup event listeners on unmount
    return () => {
      document.removeEventListener('feedbackSent', handleFeedbackSent);
      document.removeEventListener('feedbackError', handleFeedbackError);
    };
  }, []); // Empty dependency array means this effect runs only on mount and unmount

  return <div>Listening for feedback events...</div>;
};

export default FeedbackListener;

Feedback event object format

The feedbackSent event includes a detail object whose feedback property has the following structure:

interface FeedbackSentDetail {
  feedback: {
    id: string;               // ID returned by the API
    url: string;              // Page where feedback was submitted
    message: string;          // Empty for rating-only submissions
    project: string;          // Project identifier
    rating: number;           // Rating, or -1 if no rating was selected
    ratingMode: string;       // Rating mode
    session: string;          // Session ID from localStorage
    metadata?: string;        // Metadata supplied to the widget
    email?: string;           // Included by the modal form
    screenshot?: string | null; // Screenshot data, when attached
    verification?: string;    // Modal form verification field
    recaptchaToken?: string;  // Included when reCAPTCHA is enabled
  };
}

Rating-only submissions from <feedback-button submit="true"> omit the modal form fields.

The feedbackError event also includes a detail object with the following structure:

interface FeedbackErrorDetail {
  error: {
    status: number;           // HTTP status, or 500 for client errors
    message: string | Error;  // Server response text or client error
  };
}