---
title: Widget Installation Guide
description: Install the SupaFeedback widget with a single script tag. Covers triggers, the floating button, survey campaigns, user identification, screenshots, appearance, status-update emails, notifications, and the HTTP submit API.
---

# Widget Installation Guide

Learn how to integrate the SupaFeedback widget into your website or application.

## General Installation

### 1. Get Your Project ID

First, you need the unique ID for the project you want to embed.

- Navigate to the Projects page in your dashboard.
- Select the project you wish to install.
- Open the **Setup** page for that project.
- Your unique **Project ID** will be displayed there. Copy it.

### 2. Add the Script Tag

Paste the SupaFeedback script near the end of your HTML, before the closing body tag.

- Include `<script src="https://www.supafeedback.com/widget.js?pid=YOUR_PROJECT_ID" defer></script>`
- Replace `YOUR_PROJECT_ID` with the ID you copied.
- The script loads once, fetches your project trigger settings, and attaches handlers automatically.

### 3. Choose a Trigger (optional)

On the project Setup page, pick Click or Page load. You can also turn on a floating Feedback button.

- Click (default): visitors open the widget from a `data-sf` element.
- Page load: the popup appears when the page finishes loading, and is closable with ×.
- Page load options: Show once per day, Don't show after submit, and Exclude paths.
- Floating button (optional): inject a built-in chip so the script tag is enough.

### 4. Add a Trigger Button

Any element with the `data-sf` attribute opens the feedback widget. Required for Click mode unless the floating button is on; optional for Page load.

- Add `data-sf` to a button or link.
- Example: `<button data-sf>Give Feedback</button>`
- Click the element to open the widget and send feedback to your inbox.

## Trigger Options

Configure how the widget opens from your project Setup page. Settings are applied automatically by the embed — no snippet changes required.

### Click

Default behavior. Visitors open the widget by clicking any element with `data-sf`.

### Page load

The popup appears after the page finishes loading, in the corner chosen under Appearance. Visitors can close it with the × icon. Optional toggles:

- **Show once per day** — auto-show at most once per day in the same visitor's browser.
- **Don't show after submit** — stop auto-showing after a successful submission.
- **Exclude paths** — skip auto-show on specific routes. Add one path per line on Setup. Each path must start with `/`. A trailing `/*` excludes that path and its subpages, for example `/login` or `/supa-auth/*`. With no exclusions, the popup can appear on every page.

The once-per-day limit resets at midnight in the visitor's local time. Clearing browser data or using another browser may show the popup again.

Manual `data-sf` clicks and the floating button still work on excluded paths.

A published [survey campaign](#survey-campaigns) that matches the current page takes this auto-show slot instead. After that visitor has seen the survey, page-load feedback can appear again.

### Floating button

Optional. From Setup, turn on **Show a floating Feedback button** to inject a built-in chip. The script tag is then enough — you do not need a `data-sf` button.

- Set a short label (default **Feedback**, max 24 characters), or leave it blank for an icon-only button.
- The chip uses your widget primary color and the Widget position corner. It hides while the form is open and comes back after close.
- Works with Click and Page load. Page-load options still only control the auto-popup, not the chip.

Existing `data-sf` buttons keep working if you want both entry points.

## Survey Campaigns

Ask one 1–5 rating question at the right moment without replacing the feedback widget. Create a campaign from the project **Surveys** page. The installed script shows it automatically — no snippet changes required.

### Create and publish

- Set an internal name, the visitor-facing question, and labels for 1 and 5 (defaults **Very difficult** and **Very easy**).
- Save as a draft, then **Publish** when you want it live. Archive or delete a campaign to stop showing it.
- Surveys are their own popup, not a fourth tab on Issue, Idea, and Other.

### Target paths and delay

- Leave target paths blank to show the survey on every page.
- Add one path per line. Each path must start with `/`. A trailing `/*` includes that path and its subpages, for example `/setup` or `/onboarding/*`.
- Optional delay is 0–120 seconds after the page is ready. Use 0 to show immediately.

### How it appears

- A published survey can appear even when the widget is set to Click. You do not need Page load turned on.
- If a survey matches the current page, it takes the automatic slot instead of the page-load feedback popup for that visit.
- When more than one active survey matches, the newest campaign wins.
- Each visitor sees a campaign at most once in the same browser. Closing or submitting marks it seen, so it does not chain into another popup.
- After that visitor has seen the survey, page-load feedback can appear again if it is enabled.
- The floating button and `data-sf` still open Issue, Idea, and Other. Surveys use the same theme, primary color, and widget position as the feedback form.

### Responses and results

- Visitors tap 1–5 to submit, then can leave an optional comment.
- If you identify the visitor with `data-sf-name` or `identify()`, that name is stored with the response.
- Open **Results** on the Surveys page for shown count, conversion rate, average score, 1–5 mix, comments, page URL, and device context.

## User Identification

Attach a customer name and email to each submission so the inbox shows a real person you can reply to. Visitors without identity still appear with an auto-generated display name.

```html
<button
  data-sf
  data-sf-name="Ada Lovelace"
  data-sf-email="ada@example.com"
>
  Give Feedback
</button>
```

You can also set `data-sf-name` and `data-sf-email` on the `<html>` element for a site-wide default. Use that when visitors open the widget from the floating button, which has no host element of its own.

In a single-page app, call `identify()` after login instead of putting attributes on every button. Later calls merge — you can pass only `name` or only `email`. Call `identify(null)` on logout. Identity is remembered for the current tab.

```javascript
window.SupaFeedback.identify({
  name: currentUser.name,
  email: currentUser.email,
});
```

A `data-sf-name` or `data-sf-email` attribute on the trigger or `<html>` still wins over `identify()`. An attached email also opts the visitor in for status-update emails.

## Screenshots

Every feedback form includes an optional screenshot attachment. No extra embed options are required — capture and upload ship with the widget.

- **Capture current tab** — visitors can share their screen so you see exactly what they saw.
- **Upload a file** — PNG, JPEG, or WebP, one screenshot per submission.
- A compact thumbnail appears beside **Send feedback**, with preview and remove controls.
- Screenshots are private and only visible to the project owner in the dashboard inbox.

## Appearance

Customize how the widget looks from your project Setup page. Changes apply automatically — you do not need to update the script tag.

- **Title** — replace the default "What's on your mind?" heading from the Basics section on Setup.
- **Theme** — choose light or dark.
- **Primary color** — set buttons and accents with presets or a custom hex value.
- **Widget position** — choose **Bottom right** or **Bottom left**. That corner is used by the page-load popup, survey campaigns, the floating button if it is on, and any open with no `data-sf` host. A real `data-sf` click still opens next to that button.

## Notifications

When someone submits feedback, the project owner is notified so you can respond while the report is still fresh.

### For you (project owner)

- **In-app notifications** — a bell in the dashboard navbar with an unread indicator and live inbox updates.
- **Browser notifications** — optional alerts while a SupaFeedback tab is open in the background.
- **Email notifications** — a new-feedback email is sent to the project owner's account email. If the submission includes a visitor email, Reply opens a message to that address.

### For submitters (status updates)

Close the loop after someone sends feedback. Inbox statuses are New, Planned, In progress, and Done.

- Visitors identified with `data-sf-email` or `identify()` are notified automatically. The thank-you screen says we'll email them when this is updated.
- Anonymous visitors see **Get notified when this is updated** and can enter an email inline — no extra popup.
- Submitters get an email when their feedback moves to **In progress** or **Done**.
- The thank-you screen stays open until the visitor closes the widget, so they have time to opt in.

## Programmatic Triggers

Open the widget from your own UI without relying on a `data-sf` click.

```javascript
window.SupaFeedback.identify({
  name: currentUser.name,
  email: currentUser.email,
});

// Open the widget (optionally pass a trigger element)
window.SupaFeedback.open();

// Close the widget
window.SupaFeedback.close();
```

## Widget Control API

After the script loads, `window.SupaFeedback` exposes a small API:

| Method | Description |
| --- | --- |
| `open(el?)` | Opens the feedback dialog. Pass an optional trigger element for positioning and identity lookup. |
| `close()` | Closes the feedback dialog. |
| `identify(user?)` | Attach a display name and email to later submissions. Pass only `name` or only `email` to patch. Pass `null` to clear. Remembered for the current tab. |

## HTTP Submit API

Agents and server-side integrations can submit feedback without running `widget.js`. `POST /api/feedback` already powers the widget.

```http
POST /api/feedback
Content-Type: application/json
```

```json
{
  "projectId": "proj_...",
  "type": "issue",
  "message": "The checkout button does nothing",
  "userEmail": "ada@example.com",
  "userName": "Ada Lovelace",
  "pageUrl": "https://example.com/checkout"
}
```

Required fields:

- `projectId` — the project ID from Setup
- `type` — `issue`, `idea`, or `other`
- `message` — the report text (max 5000 characters)

Optional fields:

- `userEmail` — visitor email so you can reply, and so the visitor is emailed when you move the report to In progress or Done
- `userName` — display name (max 40 characters)
- `pageUrl` — `http` or `https` URL of the page being reported
- `screen` — viewport size such as `390x844`

A successful submit returns `{ "ok": true, "id": "...", "notifyToken": "..." }`. Unknown `projectId` values return 404.

The endpoint allows CORS (`Access-Control-Allow-Origin: *`) and is rate limited (30 requests per minute per IP, 60 per project). Screenshots are accepted only as `multipart/form-data` with a JSON `payload` field and a `screenshot` file, not as JSON.

## Framework Support

SupaFeedback is a plain script tag, so it works in any stack. Drop the snippet into your root layout or template:

- **Next.js / React** — add the script in your root layout, put `data-sf` on any button, and call `window.SupaFeedback.identify()` after the user signs in.
- **Vue** — load the script in `index.html` and bind the attribute on your trigger.
- **WordPress / HTML** — paste the snippet before `</body>`.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.