JavaScript API

BugDrop exposes a window.BugDrop API that gives you full programmatic control over the widget. Use it to open and close the feedback form, show and hide the button, and integrate BugDrop into your own UI elements.

API Reference

The window.BugDrop object is available after the widget initializes. It provides the following methods and properties:

Basic Usage

<script>
  // Open the feedback form
  window.BugDrop.open();

  // Close the feedback form
  window.BugDrop.close();

  // Hide the floating button
  window.BugDrop.hide();

  // Show the floating button
  window.BugDrop.show();

  // Check if the form is open
  if (window.BugDrop.isOpen()) {
    console.log('Form is currently open');
  }

  // Check if the button is visible
  if (window.BugDrop.isButtonVisible()) {
    console.log('Button is visible');
  }
</script>

API-Only Mode

When you want to trigger BugDrop entirely from your own UI -- such as a menu item, button, or keyboard shortcut -- set data-button="false" to hide the default floating button:

<script
  src="https://bugdrop.neonwatty.workers.dev/widget.js"
  data-repo="owner/repo"
  data-button="false"
></script>

In this mode, the widget loads and initializes but no floating button appears on the page. The feedback form is only accessible through window.BugDrop.open().

Custom Trigger Button

Here is a complete example of using API-only mode with your own button:

<!-- Your custom button -->
<button onclick="window.BugDrop.open()" class="my-feedback-btn">
  Report a Bug
</button>

<!-- BugDrop in API-only mode -->
<script
  src="https://bugdrop.neonwatty.workers.dev/widget.js"
  data-repo="owner/repo"
  data-button="false"
></script>

Menu Item Integration

A common pattern is integrating BugDrop into your application's navigation or help menu. The key is waiting for BugDrop to be ready before wiring up your UI.

Using the bugdrop:ready Event

BugDrop dispatches a non-bubbling bugdrop:ready event on window when it finishes initialization. This is the recommended way to set up integrations:

<nav>
  <ul>
    <li><a href="/dashboard">Dashboard</a></li>
    <li><a href="/settings">Settings</a></li>
    <li>
      <a href="#" id="report-bug-link" style="display:none">
        Report a Bug
      </a>
    </li>
  </ul>
</nav>

<script
  src="https://bugdrop.neonwatty.workers.dev/widget.js"
  data-repo="owner/repo"
  data-button="false"
></script>

<script>
  window.addEventListener('bugdrop:ready', function () {
    const link = document.getElementById('report-bug-link');
    link.style.display = '';
    link.addEventListener('click', function (e) {
      e.preventDefault();
      window.BugDrop.open();
    });
  });
</script>

This pattern ensures:

1. The "Report a Bug" link is hidden until BugDrop is ready
2. Once the widget initializes, the link becomes visible
3. Clicking the link opens the feedback form
4. The default floating button is hidden (data-button="false")

Synchronous Check

If your code runs after the page is fully loaded and you want to check whether BugDrop is already available, you can do a synchronous check:

<script>
  if (window.BugDrop) {
    // BugDrop is already initialized
    window.BugDrop.open();
  } else {
    // Wait for it
    window.addEventListener('bugdrop:ready', function () {
      window.BugDrop.open();
    });
  }
</script>

This "check first, listen second" pattern is useful in single-page applications where your code might run at various points in the page lifecycle.

Configurable Variants

Use a registered variant for a focused feedback experience while reusing BugDrop's validation, metadata, auth, Worker policy, and GitHub Issue creation. Registration validates synchronously and stores an immutable copy. The variant sidecar does no DOM, listener, observer, storage, or ID work until a variant is mounted or submitted.

const review = window.BugDrop.registerVariant({
  id: 'export-review',
  presentation: { kind: 'inline' },
  content: { title: 'How was this export?' },
  fields: [
    { id: 'rating', type: 'rating', label: 'Rating', required: true, scale: 5 },
    { id: 'message', type: 'longText', label: 'Anything else?', maxLength: 1000 },
  ],
  issue: {
    classification: 'feedback',
    title: '[Export review] {{rating}}/5',
    sections: [
      { heading: 'Rating', field: 'rating', format: 'stars' },
      { heading: 'Comment', field: 'message', omitWhenEmpty: true },
    ],
  },
});

const mountedReview = review.mount(document.querySelector('#export-review-slot'), {
  context: { surface: 'export-complete' },
});

// Later, restore the form to its initial state or remove this instance only.
mountedReview.reset();
mountedReview.unmount();

The inline renderer provides accessible short-text, long-text, and rating controls. Choosing a star changes only local form state; it never submits. A GitHub Issue is created only after the explicit Submit button succeeds.

For a host-owned CTA, register a modal variant and call its handle instead of the legacy BugDrop.open() method:

const providerQuestion = window.BugDrop.registerVariant({
  id: 'cloud-provider-question',
  presentation: { kind: 'modal', size: 'compact' },
  content: {
    title: 'Which cloud provider should we support next?',
    description: 'Tell us what would fit your workflow.',
    submitLabel: 'Send idea',
    cancelLabel: 'Not now',
  },
  fields: [
    {
      id: 'response',
      type: 'longText',
      label: 'Your answer',
      required: true,
      minLength: 2,
      maxLength: 1000,
    },
  ],
  issue: {
    classification: 'feature',
    title: 'Cloud provider request — {{response}}',
    sections: [{ heading: 'Requested provider or workflow', field: 'response' }],
  },
});

document.querySelector('#provider-cta').addEventListener('click', () => {
  const opened = providerQuestion.open({ context: { surface: 'studio-upload' } });
  opened.result.then(outcome => console.log(outcome.status));
});

The modal traps focus, closes on Escape, restores focus and page scrolling, and settles its result as submitted, closed, or busy. A variant requested while the legacy wizard is active returns busy. Opening the legacy wizard while a variant modal is active closes the variant first. The legacy BugDrop.close() method remains legacy-scoped.

BugDrop's merge-queue preview checks render both this CTA modal and the inline star review from the exact deployed widget bytes. They assert each normalized draft without creating Issues, followed by one zero-retry rendered CTA canary that creates, independently verifies, closes, and sweeps one real GitHub Issue through the existing GitHub App.

If your application owns the UI, the same immutable handle also supports headless submission:

const result = await review.submit(
  { rating: 5, message: 'Fast and clear.' },
  { context: { surface: 'export-complete' } }
);
console.log(result.issueNumber, result.issueUrl);

TypeScript consumers can import VariantConfig, VariantHandle, MountedVariant, and related declarations from the bugdrop package.

Keyboard Shortcut Example

You can bind BugDrop to a keyboard shortcut for power users:

<script>
  document.addEventListener('keydown', function (e) {
    // Ctrl+Shift+B (or Cmd+Shift+B on Mac) to toggle bug report
    if ((e.ctrlKey || e.metaKey) && e.shiftKey && e.key === 'B') {
      e.preventDefault();
      if (window.BugDrop && window.BugDrop.isOpen()) {
        window.BugDrop.close();
      } else if (window.BugDrop) {
        window.BugDrop.open();
      }
    }
  });
</script>

React Integration Example

In a React application, you can create a wrapper component:

import { useEffect, useState } from 'react';

function ReportBugButton() {
  const [ready, setReady] = useState(false);

  useEffect(() => {
    if (window.BugDrop) {
      setReady(true);
    } else {
      const handler = () => setReady(true);
      document.addEventListener('bugdrop:ready', handler);
      return () => document.removeEventListener('bugdrop:ready', handler);
    }
  }, []);

  if (!ready) return null;

  return (
    <button onClick={() => window.BugDrop.open()}>
      Report a Bug
    </button>
  );
}

Combining API with Visible Button

You do not have to choose between the floating button and the API. You can use both:

<!-- Show the floating button AND use the API -->
<script
  src="https://bugdrop.neonwatty.workers.dev/widget.js"
  data-repo="owner/repo"
></script>

<!-- Your custom trigger in the nav -->
<a href="#" onclick="event.preventDefault(); window.BugDrop.open()">
  Report a Bug
</a>

In this setup, users can either click the floating button or your navigation link to open the form. Both approaches open the same feedback form.

Programmatic Show/Hide

The show() and hide() methods let you control the floating button's visibility. This is useful for contexts where the button should only appear on certain pages or under certain conditions:

<script>
  document.addEventListener('bugdrop:ready', function () {
    // Hide the button on the checkout page
    if (window.location.pathname.startsWith('/checkout')) {
      window.BugDrop.hide();
    }

    // Show the button when user opens the help section
    document.getElementById('help-tab').addEventListener('click', function () {
      window.BugDrop.show();
    });
  });
</script>

Next Steps

• Configure the widget with data attributes
• Style the widget to match your site design
• Test your integration with Playwright