Add feedback to your Astro site, with enough context to act on it
Add a native Astro feedback component, clean it up during page transitions, and choose which page and user context to attach to messages in your Butters feed.
A visitor finds something confusing on your pricing page. They can leave, open a support ticket, or tell you while they're still looking at it. A small feedback button gives them that third option.
This guide adds the Butters feedback widget to an Astro site, keeps it working during client-side navigation, and explains which bits of context are worth collecting. It builds on putting useful events in your feed , with a message written by the person using the page.
Start with one project and one key
Open API in your Butters dashboard and create a key under Publishable keys. Choose the project that should receive feedback. If you limit allowed origins, include the origin of your site and your development site while testing.
The key starts with pk_. It's designed to appear in browser code and can write to its assigned project. Keep secret ev_ keys on your server. A feedback widget doesn't need one.
The widget sends an ordinary event. Its default category is feedback, its title is User feedback, and the visitor's message is the description. That means feedback can live alongside your application's other events instead of arriving in another inbox you forget to check.
Install the version that contains the widget
The pushed SDK source includes @getbutters/js/feedback. At the time this draft was checked, npm still served 0.1.0, which contains the browser SDK but not the feedback entry point. Until that release changes, build the source checkout:
git clone https://github.com/freekrai/getbutters-sdk.git
cd getbutters-sdk
git checkout e7cdc23444cf79ec52757c5aa1415d5dac8d17e4
bun install
bun run build From your Astro application directory, install the built checkout:
npm install /absolute/path/to/getbutters-sdk Replace that path with the checkout on your machine and keep it available while the app uses the local package. For a hosted build, your build pipeline also needs that built package. Once a published version exposes ./feedback, install that version from npm instead. The feedback documentation carries the setup details.
The widget is a separate import. Adding the usual browser SDK script tag doesn't add a feedback button, and you don't have to turn on pageviews to use it.
Add a native Astro component
Set a publishable key in your site's .env:
PUBLIC_BUTTERS_PUBLISHABLE_KEY=pk_YOUR_PUBLISHABLE_KEY Astro's PUBLIC_ prefix makes this variable available to browser code. That's appropriate for a publishable key. It would be the wrong place for a secret API key.
Create src/components/Feedback.astro:
<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> Import the component into your shared layout and render <Feedback /> once. A processed Astro script runs in the browser and can import the SDK package, so this component needs no React integration or hydration directive. It works on a static Astro site as well as one with server-rendered pages.
The hidden span marks pages where the widget should exist. The script creates the button after the page body exists, which is what the widget requires. If you leave the component out of a page, the marker check prevents the navigation handler from putting the button there anyway.
Handle navigation deliberately
A normal page load starts with mount(). When you use Astro's ClientRouter, a page swap doesn't behave like loading an entirely new browser document.
The astro:before-swap handler removes the old button and dialog. The astro:page-load handler mounts them after the next page is ready. Running cleanup before every mount prevents duplicate widgets, and destroy() aborts a request that's still active. Astro documents those events in its view transition lifecycle guide .
There's a tradeoff: destroying the widget discards its unsent draft. Closing its dialog preserves that text while you stay on the page, but navigating away through this component destroys it. Don't promise visitors that their draft follows them across your whole site.
Test both a direct load and a client-side navigation. Open a page with the component, move to another one, and check that only one Feedback button appears. Then visit a page without the component and check that the button is gone.
Collect context only when it helps
By default, the widget doesn't attach the page URL. To include it, change the creation call:
feedback = createFeedbackWidget({
key,
category: 'feedback',
title: 'Website feedback',
buttonLabel: 'Feedback',
heading: 'What could work better?',
includePageUrl: true,
}) The URL contains the current origin and pathname. Query parameters and fragments are removed, so a token in the query string isn't copied into the event's URL field. Paths can still contain personal information, and visitors can type anything into the message. Review your own URLs and tell people what you're collecting.
For a public marketing page, a message and a page path may be enough. For an authenticated application, attaching an existing user ID can save you a follow-up question. Neither requires collecting screen dimensions, a recording of the visit, or every click that led up to it.
Use an existing browser identity
The widget can read the user ID stored by the browser SDK. Initialize that SDK before calling identify():
import { init, identify, reset } from '@getbutters/js'
init({ key: 'pk_YOUR_PUBLISHABLE_KEY' })
identify('user_123')
// Call this from your logout handler:
reset() Use your application's own user ID rather than making an email address the identifier. Browser identity is unverified input: someone can alter browser code or send a forged request. Treat it as a clue for investigating feedback, not proof of who submitted it. Set trusted profile properties through your server.
The widget doesn't ask for a name or email, call identify() for you, or turn on automatic pageviews. If you've never identified the visitor, the message arrives without a user attached.
Check the submission experience
Open Feedback, type a short message, and select Send feedback. The widget disables the textarea and send button while the request is pending. A successful request shows Thank you. Your feedback was sent. Check the assigned project's Feed for the event.
Messages are trimmed and limited to 2,000 characters. Empty messages are refused. The dialog supports keyboard navigation, Escape to close, and restoring focus to the control that opened it. Check those behaviours on your actual page, especially if you already have floating buttons or dialogs near the same corner.
A failed send preserves the text. A request times out after ten seconds, and the widget doesn't automatically retry writes. If the connection drops after the server accepted the message, resubmitting can create another event. Check the feed before retrying an ambiguous test.
Each message counts toward the team's monthly event allowance. Feedback shares the publishable key's rate budget with browser tracking and identity calls: 60 requests per minute per key and client IP. The widget doesn't request notification fan-out.
Fix the common failures
If the button never appears, check the environment variable, make sure the component is rendered, and look for a package import error. Installing the browser-only npm release won't provide the widget import.
If sending fails, check the key's assigned project, allowed origins, your connection, and the team's event allowance. Too many requests means you need to wait before submitting again. Browser developer tools will show the HTTP response without requiring you to guess whether the form or the API failed.
If the dialog appears without its expected styling, check your Content Security Policy. The current widget adds its own style element inside a shadow root. Its API doesn't expose a style nonce, so a strict policy may need a deliberate integration change. Don't change your site's policy blindly just to hide an error.
A feedback button is useful when someone has something specific to tell you. Give them a short path from that moment to a message, keep the context modest, and read the feed where the messages arrive.