@pxlabz/tracey-react

React SDK for Tracey feedback, announcements, and surveys.

Version

Current SDK version: 0.0.12

Install

npm install @pxlabz/tracey-react

Peer dependencies:

• react (^18 || ^19)
• react-dom (^18 || ^19)

Screenshot capture is available out of the box with the SDK. The dedicated screenshot entrypoint lazy-loads the capture dependency so default consumers do not pay that cost eagerly.

Components available

Main package exports:

• TraceyLauncher
• FeedbackWidget
• FeedbackForm
• AnnouncementModal
• AnnouncementBell
• AnnouncementList
• SurveyWidget

Provider exports:

• TraceyProvider
• MockTraceyProvider

Headless exports (@pxlabz/tracey-react/headless):

• Feedback primitives: FeedbackRoot, FeedbackTrigger, FeedbackPortal, FeedbackContent, FeedbackFormPrimitive, FeedbackClose
• Announcement primitives: AnnouncementRoot, AnnouncementTrigger, AnnouncementPortal, AnnouncementContent, AnnouncementSlidePrimitive, AnnouncementNavigation, AnnouncementClose
• Launcher primitives: LauncherRoot, LauncherTrigger, LauncherMenu, LauncherMenuItem, LauncherBadge, LauncherPortal, LauncherPanel, LauncherTab, LauncherTabContent

Use in your app

1. Wrap your app with TraceyProvider

import { TraceyProvider, TraceyLauncher } from "@pxlabz/tracey-react";

const traceyUser = {
	id: "user_123",
	email: "[email protected]",
	name: "Jane Doe",
};

export function App() {
	return (
		<TraceyProvider
			apiKey={import.meta.env.VITE_TRACEY_API_KEY}
			user={traceyUser}
			announcementsFilter="all"
		>
			{/* Your app */}
			<TraceyLauncher position="bottom-right" />
		</TraceyProvider>
	);
}

Use announcementsFilter="all" to show old (already viewed) updates in the What's New experience. Omit it, or set announcementsFilter="unread", to keep the default unread-only behavior.

2. Add individual widgets (optional)

import {
	AnnouncementBell,
	FeedbackWidget,
	SurveyWidget,
} from "@pxlabz/tracey-react";

export function AppWidgets() {
	return (
		<>
			<FeedbackWidget position="bottom-right" />
			<AnnouncementBell position="top-right" />
			<SurveyWidget />
		</>
	);
}

3. Use headless primitives for fully custom UI (optional)

import {
	FeedbackRoot,
	FeedbackTrigger,
	FeedbackPortal,
	FeedbackContent,
	FeedbackFormPrimitive,
} from "@pxlabz/tracey-react/headless";

export function CustomFeedback() {
	return (
		<FeedbackRoot>
			<FeedbackTrigger>Open feedback</FeedbackTrigger>
			<FeedbackPortal>
				<FeedbackContent>
					<FeedbackFormPrimitive />
				</FeedbackContent>
			</FeedbackPortal>
		</FeedbackRoot>
	);
}

Notes

• TraceyProvider is required for components and hooks that talk to the Tracey API.
• TraceyProvider uses https://tracey.pxlabz.com by default when baseUrl is omitted. Pass baseUrl to target a different API host.
• TraceyProvider accepts announcementsFilter ("unread" | "all"). The default is "unread".
• The default entry imports SDK styles automatically. If your setup needs explicit CSS imports, use import "@pxlabz/tracey-react/styles.css";.
• Feedback forms support both full screenshot capture and region capture (Capture Area).
• Screenshot capture works out of the box after installing @pxlabz/tracey-react.
• Prefer importing screenshot helpers from @pxlabz/tracey-react/screenshot. Root and headless re-exports still work for now, but they are deprecated.
• Region capture uses html2canvas and captures webpage/app content only, not browser chrome or OS UI.
• Some pages with strict cross-origin content restrictions may prevent DOM-based screenshot rendering.
• Area capture stays in strict mode and does not automatically fall back to full screenshot capture.

Region Capture Troubleshooting

If area capture fails, the SDK now distinguishes common causes:

• Unable to capture selected area because cross-origin content blocked browser capture.
• Unable to capture selected area. Check browser support and try again.

Cross-origin/security failures are common when a page includes third-party iframes, assets, canvases, or videos that the browser prevents from being read during DOM rendering. Users can still continue reporting by uploading files manually.

What's New In 0.0.12

• Added @pxlabz/tracey-react/screenshot as the preferred import path for screenshot helpers.
• Screenshot capture now lazy-loads the underlying capture dependency, reducing default entrypoint cost.
• Root and headless screenshot helper re-exports remain available temporarily with deprecation guidance.

What's New In 0.0.10

• Chat-related improvements and fixes.

What's New In 0.0.9

• Improved region-capture failure classification for cross-origin/security-taint scenarios.
• Better user-facing error copy in feedback forms, including actionable guidance to use file upload when needed.
• Consistent capture error handling between the styled feedback form and embedded launcher feedback form.
• Bundling/dependency alignment for screenshot capture so behavior remains consistent across consuming applications.

What's New In 0.0.5

• Improved reliability for region screenshot capture to prevent accidental dialog closure after drag selection.
• Feedback form draft state now persists across dialog close/reopen within the same page session.
• Added explicit Clear action in the feedback form to discard draft content and attachments.
• Feedback attachments support multiple screenshots and file attachments up to the configured attachment limit.
• Users can remove individual screenshot/file attachments and add new ones in the same draft.

Screenshot Helpers

You can call screenshot helpers directly in custom or headless UI:

import {
	captureScreenshot,
	captureRegionScreenshot,
} from "@pxlabz/tracey-react/screenshot";

captureRegionScreenshot opens a drag-to-select overlay. It returns null when the user cancels.

The following imports are still supported temporarily, but are deprecated and will be removed in the planned breaking-cleanup phase:

import { captureScreenshot } from "@pxlabz/tracey-react";
import { captureScreenshot } from "@pxlabz/tracey-react/headless";