How to Add Bug Reporting to Any Website in 60 Seconds

Most bug reporting tools require account creation, npm package installation, build configuration, or browser extensions. That friction means teams delay setting up proper feedback workflows — and keep relying on Slack messages and vague emails instead.

This tutorial shows you how to add a fully functional visual bug reporting widget to any website — static HTML, React, Next.js, WordPress, Shopify, or anything that serves HTML — using a single script tag. No build tools, no accounts, no dependencies.

What You Will Get

By the end of this tutorial, your website will have a floating feedback button that lets anyone:

• Take an annotated screenshot of the current page
• Draw, highlight, and add arrows to point out issues
• Type a description of the bug
• Automatically capture console errors, browser info, and viewport size
• Submit everything as a fully-formatted GitHub Issue with the screenshot attached

The entire report — screenshot, annotations, description, and technical metadata — lands in your GitHub repo as a structured issue, ready for triage.

Step 1: Get Your Project ID

Head to the Interactive Demo page. Enter your GitHub repository (e.g., your-org/your-repo) and a GitHub Personal Access Token with repo scope. The page generates a project ID and your complete embed snippet.

Your project ID looks something like proj_abc123. This is what connects the widget to your GitHub repository.

Step 2: Add the Script Tag

Paste the following snippet before the closing </body> tag of your HTML:

<script
  src="https://cdn.withcallout.com/widget.js"
  data-project="YOUR_PROJECT_ID"
  defer
></script>

That is it. One script tag. The widget loads asynchronously and will not block your page rendering.

Step 3: Customize (Optional)

You can configure the widget's appearance and behavior using the window.CalloutConfig object. Add it before the script tag:

<script>
  window.CalloutConfig = {
    position: "bottom-right",  // or "bottom-left"
    color: "#be185d",          // trigger button color
    title: "Report a Bug",     // modal title
    categories: ["bug", "feature", "other"],
    debug: false               // set true to see console logs
  };
</script>

The Interactive Demo page lets you customize all of these options visually and preview the result in real-time before copying your snippet.

Step 4: Test It

Open your site in a browser. You should see a small floating button in the bottom-right corner (or wherever you positioned it). Click it to open the feedback modal:

1. The widget captures a screenshot of the current page
2. You can annotate it — draw circles, arrows, or highlight areas
3. Type a description of the issue
4. Click submit

Check your GitHub repository. You should see a new issue with the title from the description, the annotated screenshot embedded in the issue body, and a metadata section listing the browser, OS, viewport size, current URL, and any console errors captured during the session.

What a Report Looks Like in GitHub

Each submitted report creates a GitHub Issue with a structured body that includes:

• Description: The user's own words about what went wrong
• Screenshot: An annotated screenshot uploaded to GitHub and embedded in the issue
• Environment: Browser name and version, operating system, viewport dimensions, device pixel ratio
• Console errors: Any JavaScript errors captured during the session, with stack traces
• Page URL: The exact page where the bug was reported
• Session replay link: If you use PostHog, LogRocket, Hotjar, or FullStory, Callout auto-detects the replay URL and includes it

This structure means developers can start debugging immediately without asking follow-up questions about browser versions or reproduction steps.

Framework-Specific Notes

React / Next.js

Add the script tag to your root layout.tsx or use Next.js <Script> component with strategy="lazyOnload". The widget uses Shadow DOM, so it will not conflict with your React styles or state.

WordPress

Add the snippet to your theme's footer.php before </body>, or use a plugin like "Insert Headers and Footers" to add it without editing theme files.

Static HTML / Hugo / Jekyll

Add the script tag to your base layout template. It works on any page that serves HTML — no JavaScript framework required.

Shopify

Go to Online Store → Themes → Edit code → theme.liquid. Paste the snippet before </body>.

Advanced: Identifying Users

If your app has authenticated users, you can pass their identity to the widget so reports include who filed them:

<script>
  window.CalloutConfig = {
    user: {
      name: "Jane Smith",
      email: "[email protected]"
    }
  };
</script>

This information appears in the GitHub Issue metadata, making it easy to follow up with the reporter if needed.

Wrapping Up

Adding bug reporting to your website should not take longer than the bugs themselves. With a single script tag, you get annotated screenshots, automatic console error capture, device metadata, and direct delivery to GitHub Issues — all for free.

Callout is designed for teams who want better bug reports without the overhead of expensive tools or complex setups. Try it on your site and see the difference that contextual bug reports make.