@fasterfixes/widget

Documentation · Website

The FasterFixes feedback Widget for any website, with no framework required. Reviewers annotate elements on the page and submit visual feedback to your Project. It works on WordPress, Webflow, static HTML and apps built with any framework. React, Vue, Angular and Svelte applications can also use @fasterfixes/react, @fasterfixes/vue, @fasterfixes/angular and @fasterfixes/svelte.

The Widget ships no framework runtime and renders inside an open Shadow DOM, so your site's CSS does not affect it.

Script tag

Paste one tag into your site, replacing the Project ID with your own:

<script
  src="https://cdn.jsdelivr.net/npm/@fasterfixes/widget@1/dist/widget.iife.js"
  data-project-id="proj_your_project_id"
  defer
></script>

The tag works in the <head> with defer, at the end of the <body>, or injected after the page has loaded. The @1 channel serves every 1.x release: fixes arrive without editing the snippet, and a breaking change only ships under a new major version.

Attributes

labels cannot be set through attributes. To set them, or to pass the full option object, see Manual initialization below.

Manual initialization

Leave out data-project-id to load the script without mounting the Widget, then call window.FasterFixes.init yourself, for example from a framework's mount hook:

<script src="https://cdn.jsdelivr.net/npm/@fasterfixes/widget@1/dist/widget.iife.js"></script>
<script>
  window.FasterFixes.init({
    projectId: "proj_your_project_id",
    labels: { submitButton: "Send" },
  });
</script>

Calling init while a Widget is mounted destroys the previous instance first, so the Widget never mounts twice. After initialization, window.FasterFixes.instance holds the current instance.

npm

With a bundler, install the package and import init. The package ships an ESM entry with TypeScript types.

npm install @fasterfixes/widget

import { init } from "@fasterfixes/widget";

const widget = init({ projectId: "proj_your_project_id" });

window.FasterFixes is only defined by the script tag.

Visibility

The Widget mounts only for Reviewers: a Reviewer token must be present (from the ff_token URL parameter, then local storage) and the Project must have the Widget enabled. Public visitors see nothing, and no config request is sent without a token.

Options

init accepts one option object:

An unknown position, a projectId that is not a non-empty string, a labels value that is not an object or a customMetadata value that is neither an object nor a function prevents the Widget from mounting. Development builds log a console error naming the option.

customMetadata is shown to your team, in the agent API and in mirrored Issues, never to Reviewers. Pass an object, or a synchronous function called at each submission so a value such as a signed-in user ID stays current. Values are strings, numbers, booleans or null. At most 50 keys are kept, keys are truncated to 40 characters and values to 500, with a console warning in development. A function that throws never blocks a submission: the Feedback is sent without Custom metadata. It is sent whether or not captureDiagnostics or captureRecording is on.

Instance

init returns a Widget. Its members match the useFeedback hook of @fasterfixes/react, the useFeedback composable of @fasterfixes/vue, injectFeedback of @fasterfixes/angular and getFeedback of @fasterfixes/svelte:

<button type="button" onclick="window.FasterFixes.instance?.startAnnotation()">
  Report an issue
</button>

subscribe lets your own UI follow the Widget state without polling. The listener receives no arguments: read the values from the instance. destroy() removes every listener.

const widget = init({ projectId: "proj_your_project_id" });
const unsubscribe = widget.subscribe(() => {
  counter.textContent = String(widget.feedbackItems.length);
});

Labels

Every string the Widget displays or announces to screen readers comes from labels. Pass partial overrides; omitted keys keep their English default. pinAriaLabel is a function that receives an excerpt of the Feedback comment:

window.FasterFixes.init({
  projectId: "proj_your_project_id",
  labels: {
    submitButton: "Envoyer",
    cancelButton: "Annuler",
    textareaPlaceholder: "Décrivez le problème...",
    pinAriaLabel: (comment) => `Retour : ${comment}`,
  },
});

The full list of keys and defaults is in the Customization docs.

Theming

Theme the Widget with CSS custom properties on its [data-ff-widget] host:

[data-ff-widget] {
  --ff-background: #ffffff;
  --ff-foreground: #18181b;
}

--ff-accent is set inline from the color option, so prefer color to change it. Reach deeper elements with ::part(): button, overlay, popover, textarea, pin, list and list-item.

[data-ff-widget]::part(button) {
  box-shadow: none;
}

License

MIT