npm package: @pxlabz/tracey-react
Description: React SDK for Tracey feedback widgets and announcements
Latest version: 0.0.12

# @pxlabz/tracey-react

React SDK for Tracey feedback, announcements, and surveys.

## Version

Current SDK version: `0.0.12`

## Install

```bash
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`

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

const traceyUser = {
	id: "user_123",
	email: "jane@example.com",
	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)

```tsx
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)

```tsx
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:

```tsx
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:

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