Buglet is a lightweight feedback widget that can be embedded into any website using a single script tag. Its purpose is to make it easy for users to report issues, share comments, and provide context-rich feedback directly from the page they are viewing.

1. Introduction

Buglet provides a small on-page widget that website visitors can use to send feedback to the site owner. When opened, the widget presents a simple form where users can:

Write a message describing a bug or suggestion
Include an optional email address, enabling follow-up communication
Capture a screenshot of the page as it appears on their device

Screenshots are especially useful for identifying visual bugs or layout issues, as they show exactly what the user sees at the moment of submitting feedback.

Feedback submitted through Buglet can be forwarded to:

An email address of your choice
A Slack channel via webhook
Buglet’s own dashboard, where all reports are stored by default

The widget itself is small, unobtrusive, and easy to integrate into any frontend stack.

2. Basic Setup

2.1 Registering a Domain

Before embedding Buglet on a live site, the domain must be registered in the Buglet dashboard. This helps ensure that only authorised websites can use your widget configuration.

localhost:3000 is automatically whitelisted.
You can use Buglet during local development without registering this domain.

When registering a domain, you can also specify:

Email address — Buglet will forward all feedback here
Slack webhook URL — reports can be pushed into any Slack channel
(Optional) other future integrations as they become available

Regardless of external notification settings, all feedback is always recorded in the Buglet dashboard.

After a domain is registered, Buglet provides a script-generation interface where the widget can be customised.
Current customisable fields include:

Position

left or right
Determines which bottom corner of the screen the Buglet trigger appears in.

Size

small | medium | large
Adjusts the size of the trigger button.

Color

A CSS hex value (e.g., #ff5500)
Controls the trigger’s background color.
If left empty, it defaults to Buglet’s brand red: #E52828.

Allowed paths

Determines which routes on your site should display the widget.
Supports simple patterns, such as:

/* — all pages
/dashboard — only the dashboard
/products/* — all product subpages

This allows you to restrict Buglet to only the areas you want feedback from.

2.3 Generated Script Tag

Once you configure the widget, Buglet will generate a script tag for you.
It will look something like this:

<script
  src="https://buglet.vercel.app/buglet.js"
  data-position="left"
  data-size="medium"
  data-primary-color="#e52828"
  data-secondary-color="#e52828"
  data-border-color=""
  data-arrow-color="white"
  data-allowed-paths="/*"
  data-config-id="xxx-xxx-xxx-xxx"
  defer
></script>

This script tag contains:

Your widget settings (as data-* attributes)
A unique config-id that links the script to your domain configuration
The Buglet runtime script

2.4 Embedding Buglet

Place the generated tag inside the of your website:

<head>
  <script
    src="https://buglet.vercel.app/buglet.js"
    data-position="left"
    data-size="medium"
    data-primary-color="#e52828"
    data-secondary-color="#e52828"
    data-border-color=""
    data-arrow-color="white"
    data-allowed-paths="/*"
    data-config-id="xxx-xxx-xxx-xxx"
    defer
  ></script>
</head>

Once included, Buglet will automatically:

Load in the correct position on every allowed page
Display the feedback trigger
Send feedback to the configured destinations
Store all submissions in your dashboard

No further setup is required.

3. Styling and Customisation

Buglet exposes several parts of the widget through the Web Components ::part() API.
This allows you to apply custom CSS from your host website without modifying the widget's internal code.

3.1 Exposed Parts

The following parts can be styled:

Part name	Description
`widget`	The entire Buglet widget container
`trigger`	The floating Buglet trigger button (bottom corner)
`triggerBackground`	The colored circular background behind the trigger icon
`triggerForeground`	The trigger icon (Buglet logo)
`modal`	The feedback modal that opens when the trigger is pressed
`modalBackground`	The background container inside the modal

Each part can be targeted using standard CSS via the ::part() selector.

3.2 Example: Changing the Trigger Background color

buglet-widget::part(triggerBackground) {
  background: #eeaeca;
  background: radial-gradient(circle, rgba(238, 174, 202, 1) 0%, rgba(148, 187, 233, 1) 100%);
}

buglet-widget::part(triggerForeground) {
  background: #e52828;
}

This overrides Buglet’s default trigger background color. Some examples of funky custom backgrounds can be seen below.

Custom examples screenshot

4. Using a Custom Button as the Buglet Trigger

In addition to the default floating trigger button, Buglet allows you to use any custom button or element on your website to open the feedback modal.

To make an element act as a Buglet trigger, simply add the class:

<Button size="lg" className="buglet-trigger">
  Try Buglet ✨
</Button>

This button will now open the Buglet feedback modal exactly like the default trigger.

4.1 Why Use a Custom Trigger?

Using your own trigger can be helpful when:
You want Buglet to integrate seamlessly into your site’s UI
You prefer a more prominent CTA (e.g., “Report an Issue”)
You want alternative behaviour at different screen sizes
You want to hide the default Buglet trigger entirely

4.2 Example: Hide the Default Trigger on Smaller Screens

You can combine a custom trigger with CSS to hide the default Buglet trigger on mobile/tablet:

@media (max-width: 1024px) {
  buglet-widget::part(trigger) {
    display: none !important;
  }
}

This would prevent the trigger from appearing on devices narrower than 1024px.

This ensures the widget is still fully functional while giving you full control over how users access it.

Buglet Documentation