Feedback Widget
Add an optional feedback button that sends messages into your project feed.
Feedback Widget
The feedback widget adds a Feedback button and a dialog where visitors can send a message. Each submitted message becomes an event in your project's Feed, with category feedback and title User feedback by default.
Install
Version 0.2.0 includes the browser, server, and feedback entry points. Install it from npm:
npm install @getbutters/js@^0.2.0 Set up the widget
Create a publishable key from API → Publishable keys. Select the project that should receive messages. If you restrict allowed origins, include your website's origin. Use a pk_… key, never a secret ev_… key.
Import the optional entry point after your page's body exists:
import { createFeedbackWidget } from '@getbutters/js/feedback'
const feedback = createFeedbackWidget({ key: 'pk_YOUR_PUBLISHABLE_KEY' }) The widget appears at the bottom right of the page. Open Feedback, enter a message, and click Send feedback. A successful submission shows a thank you message. Open the project's Feed to see the event. Messages are trimmed and limited to 2,000 characters; empty messages are refused.
The dialog supports keyboard navigation and Escape to close. Focus returns to the control that opened it. Closing keeps unsent text. A failed send also keeps the text so you can retry.
Options
const feedback = createFeedbackWidget({
key: 'pk_YOUR_PUBLISHABLE_KEY',
host: 'https://app.getbutters.com',
category: 'feedback',
title: 'User feedback',
buttonLabel: 'Feedback',
heading: 'Send feedback',
includePageUrl: false,
}) The options above show the defaults. Page URL collection is off by default. When enabled, the event gets the current origin and pathname, with query parameters and fragments removed. If the browser SDK has stored an identified user ID, the widget attaches it to the event. It does not ask for a name or email, identify visitors, or enable pageview tracking.
The widget sends ordinary events: each message counts toward the team's monthly event allowance and the publishable key's rate limit. Messages do not request notification fan-out.
Open, close, and remove
feedback.open()
feedback.close()
feedback.destroy() destroy() removes the button and dialog and aborts any active request. Call it when unmounting a page component to avoid creating duplicate buttons. In Next.js, create the widget in a client effect and destroy it during cleanup. The widget has its own optional entry point and does not add UI to the default browser import or CDN script.
Astro without React
Create src/components/Feedback.astro and include <Feedback /> once in your shared layout. Put the publishable key in PUBLIC_BUTTERS_PUBLISHABLE_KEY in your site's .env:
<span data-butters-feedback-slot hidden></span>
<script>
import { createFeedbackWidget } from '@getbutters/js/feedback'
import type { FeedbackWidget } from '@getbutters/js/feedback'
let feedback: FeedbackWidget | undefined
function unmount() {
feedback?.destroy()
feedback = undefined
}
function mount() {
unmount()
const key = import.meta.env.PUBLIC_BUTTERS_PUBLISHABLE_KEY
if (key && document.querySelector('[data-butters-feedback-slot]')) {
feedback = createFeedbackWidget({ key })
}
}
mount()
document.addEventListener('astro:page-load', mount)
document.addEventListener('astro:before-swap', unmount)
</script> The processed <script> runs in the browser, so no React integration or hydration directive is required. The initial mount() supports full page loads. If you use Astro's ClientRouter, astro:before-swap removes the old widget and astro:page-load creates it on the new page. The marker prevents mounting on pages that do not include the component. Page URL collection stays off in this example.
See Astro's view transition lifecycle for the navigation events.
React and Next.js
Mount the widget once in a client component. Use a publishable key in the browser environment variable and return destroy() from the effect cleanup:
'use client'
import { useEffect } from 'react'
import { createFeedbackWidget } from '@getbutters/js/feedback'
export function Feedback() {
useEffect(() => {
const key = process.env.NEXT_PUBLIC_BUTTERS_PUBLISHABLE_KEY
if (!key) return
const feedback = createFeedbackWidget({ key, includePageUrl: true })
return () => feedback.destroy()
}, [])
return null
} Add <Feedback /> once to your application layout. This example enables page URL collection; omit includePageUrl to leave it off. React development mode may mount effects twice; cleanup removes the first widget before recreating it.
Use with browser identity
The widget works without calling browser init(). To attach your signed-in user's ID to feedback, initialize the browser SDK and identify the user:
import { init, identify, reset } from '@getbutters/js'
init({ key: 'pk_YOUR_PUBLISHABLE_KEY' })
identify('user_123')
// In your logout handler:
reset() Browser identity is unverified input. Use your server SDK for trusted profile properties. Creating the widget does not turn on automatic pageviews.
Troubleshooting
- Enter feedback of 2,000 characters or fewer: enter a non-empty message within the limit.
- Too many requests: wait before trying again. Feedback shares the publishable key's 60 requests/minute per client IP budget with other calls.
- Could not send feedback: check your connection, publishable key, allowed origins, and team's event allowance. Requests time out after 10 seconds. Writes are not automatically retried; if a response was lost, check the feed before sending again.
- The widget is missing: create it in browser code after the document body exists. If your site blocks inline styles with a Content Security Policy, the default widget styles need to be allowed by that policy.
See JavaScript SDK for identifying users and API Reference for publishable keys.