Catch JavaScript errors with user-friendly error feedback

JavaScript errors (either vanilla or with Stimulus controllers) often happen silently in the browser, leaving your users confused about what went wrong. “Why did nothing happen?”. “I just did click the button!” “Let’s try again…”. Still nothing… Starts furiously clicking the button now.

This poor user experience can be frustrating and can lead to more support tickets that could have been prevented. In this article I want to show how to build a simple class that catches unhandled JavaScript errors and displays them to the user in a friendly banner. It’s a small but meaningful improvement to your app’s user experience.

As always, the code can be found on GitHub.

The silence of the errors

When a JavaScript error occurs and isn’t caught, it silently fails in the background. The user has no idea what happened. You as a developer might inspect the browser’s console, but you are not a normie. Did the request fail? Is the app broken? Should they refresh the page? Without feedback, they’re left guessing.

A simple error banner at the top of the page can help with this. It tells the user something went wrong and gives them the option to dismiss it or take action.

Hello noisy errors

The ErrorFeedback class is straightforward. It listens for unhandled errors and promise rejections, then displays them in a banner:

// app/javascript/error_feedback.js
export default class ErrorFeedback {
  #banner = null
  _timeout = null

  constructor(options = {}) {
    this.duration = options.duration ?? 5000
    this.message = options.message ?? "Something went wrong. Please try again."
    this.visibleClass = options.visibleClass ?? "is-visible"

    this.#setup()
  }

  static gottaCatchThemAll(options) {
    return new this(options)
  }

  #setup() {
    window.onerror = (msg, src, line, col, error) => {
      this.#show(msg || error?.message)

      return true
    }

    window.onunhandledrejection = (event) => {
      this.#show(event.reason?.message || event.reason)
    }
  }

  #show(text) {
    if (!this.#banner) this.#createBanner()

    this.#banner.querySelector("p").textContent = text || this.message
    this.#banner.classList.add(this.visibleClass)
    this.#scheduleDismiss()
  }

  #hide = () => {
    if (this.#banner) this.#banner.classList.remove(this.visibleClass)

    this.#clearSchedule()
  }

  #createBanner() {
    this.#banner = document.createElement("div")
    this.#banner.className = "error-feedback"
    this.#banner.innerHTML = `
      <p></p>

      <button type="button" aria-label="Dismiss">×</button>
    `
    this.#banner.querySelector("button").addEventListener("click", this.#hide)

    document.body.appendChild(this.#banner)
  }

  #scheduleDismiss() {
    this.#clearSchedule()

    if (this.duration > 0) this._timeout = setTimeout(this.#hide, this.duration)
  }

  #clearSchedule() {
    if (this._timeout) {
      clearTimeout(this._timeout)

      this._timeout = null
    }
  }
}

If above class is overwhelming to you, why not check out JavaScript for Rails Developers? It touches upon many of the syntax you see above.

The class catches two types of errors: synchronous errors via window.onerror and promise rejections via window.onunhandledrejection. When an error occurs, it extracts the error message and displays it in the banner.

The banner automatically dismisses after a (configurable) 5 seconds.

Enable the banner

Initialize the error feedback in your main application file:

// app/javascript/application.js
import "@hotwired/turbo-rails"
import "controllers"
import ErrorFeedback from "errors"

ErrorFeedback.gottaCatchThemAll() // I am too old to fully get this reference, but I think it is accurate enough

And that is it! The class is now listening for errors across your entire app.

Where to go from here

The banner can be easily extended with additional features. You could add a link to your documentation, a button to contact support or even integrate with error monitoring tools like Appsignal or Honeybadger.

For example, you could add a link to your support chat:

this.#banner.innerHTML = `
  <p></p>

  <div>
    <a href="https://example.com/chat">Chat with support</a>

    <button type="button" aria-label="Dismiss">×</button>
  </div>

Or extend the class to send errors to an external service:

#show(text) {
  if (!this.#banner) this.#createBanner()

  this.#banner.querySelector("p").textContent = text || this.message
  this.#banner.classList.add(this.visibleClass)
  this.#scheduleDismiss()

  // Send to error monitoring service
  this.#reportError(text)
}

#reportError(message) {
  // Send to Appsignal, Honeybadger, etc.
}

This simple class is not a replacement for proper error monitoring tools. Those tools provide detailed stack traces, user session replay and analytics that are super useful for debugging sessions. But this banner fills an important gap: it gives your users immediate feedback when something goes wrong, improving their experience and reducing confusion.