@siteping/widget

Client feedback, pinned to the pixel.

A lightweight feedback widget that lets your clients annotate websites during development. Draw rectangles (or right-click), leave comments, track bugs — directly on the live site, anchored to the exact DOM element.

Part of SitePing — live demo · documentation.

Install

npm install @siteping/widget

Quick start

React (the hook survives StrictMode double-mounts and tears down on unmount):

"use client";
import { useSiteping } from "@siteping/widget/react";

export function Feedback() {
  useSiteping({ endpoint: "/api/siteping", projectName: "my-app" });
  return null;
}

Any other framework, or none:

import { initSiteping } from "@siteping/widget";

const widget = initSiteping({ endpoint: "/api/siteping", projectName: "my-app" });
// widget.open() / .close() / .refresh() / .focusFeedback(id) / .on(...) / .destroy()

No server? Pass store: new LocalStorageStore() (from @siteping/adapter-localstorage) instead of endpoint and the whole loop runs in the browser.

Highlights

• DOM-anchored annotations — CSS selector + XPath + text fallbacks; they survive deploys and layout changes
• Dev-only by default — hides in production builds (NODE_ENV); forceShow: true for staging. Renders at every width, with a phone layout (minViewportWidth keeps it off small screens)
• Opt-in extras — screenshots of the annotated area (with data-siteping-ignore="true" privacy masking), console/network diagnostics, instant right-click comments that never hijack keyboard or modifier-key menus
• Panel actions — your own buttons and links in the feedback detail view: create a ticket, hand a feedback to an agent, open it in your tracker
• Reliable — retry with backoff plus a localStorage queue; a flaky network never loses a comment
• Isolated & light — closed Shadow DOM, ~34 KB gzip (ESM); panel, screenshot engine, and non-English locales load on demand
• 9 built-in locales — en, fr, de, es, it, pt, ru, ja, ko (BCP-47 tags like fr-CA resolve automatically)

Documentation

Every option with its real default and behavior: siteping.dev/docs/widget/configuration — plus screenshots & masking, right-click comments, panel actions, and how anchoring works.

License

MIT