Error Tracking Components

3 Components

Pre-built React components for error handling, automatic error reporting, and user feedback collection.

Quick Start

All error components are available from the SDK. Wrap your app with SylphxProvider for automatic error context and reporting.
Installation
import {
  ErrorBoundary,
  SylphxErrorBoundary,
  FeedbackWidget,
} from '@sylphx/platform-sdk/react'

ErrorBoundary

A generic React error boundary that catches JavaScript errors in its child component tree and displays a customizable fallback UI. Use this for isolated error handling without automatic reporting.

Isolated Recovery
Reset Support
Basic Usage
import { ErrorBoundary } from '@sylphx/platform-sdk/react'

export default function DashboardPage() {
  return (
    <div className="p-8">
      <h1>Dashboard</h1>

      <ErrorBoundary
        fallback={
          <div className="p-4 border border-red-200 rounded-lg bg-red-50">
            <p className="text-red-800">Widget failed to load</p>
          </div>
        }
      >
        <AnalyticsWidget />
      </ErrorBoundary>

      <ErrorBoundary
        fallback={<p>Chart unavailable</p>}
      >
        <RevenueChart />
      </ErrorBoundary>
    </div>
  )
}

Props

PropertyTypeDescription
childrenrequiredReactNodeComponents to render inside the boundary
fallbackrequiredReactNode | FallbackRenderUI to display when an error occurs
onError(error: Error, errorInfo: ErrorInfo) => voidCallback fired when an error is caught
onReset() => voidCallback fired when the boundary resets
resetKeysunknown[]Values that trigger a reset when changed
resetOnPropsChangeboolean= falseReset when any prop changes

Fallback UI Examples

<ErrorBoundary
  fallback={
    <div className="text-center p-8">
      <AlertTriangle className="w-12 h-12 text-amber-500 mx-auto mb-4" />
      <h2 className="text-lg font-semibold">Something went wrong</h2>
      <p className="text-muted-foreground">Please refresh the page</p>
    </div>
  }
>
  <MyComponent />
</ErrorBoundary>

Fallback Render Function

When using a function as fallback, you receive error, errorInfo, and resetErrorBoundary as arguments for dynamic error handling.

SylphxErrorBoundary

An enhanced error boundary that automatically reports errors to Sylphx monitoring. Includes user context, stack traces, and optional user feedback collection.

Auto Reporting
User Context
Feedback Dialog
Basic Usage
import { SylphxErrorBoundary } from '@sylphx/platform-sdk/react'

export default function App() {
  return (
    <SylphxErrorBoundary
      onError={(error, errorInfo) => {
        // Error is automatically reported to Sylphx
        console.log('Error reported:', error.message)
      }}
    >
      <MyApplication />
    </SylphxErrorBoundary>
  )
}

Props

PropertyTypeDescription
childrenrequiredReactNodeComponents to render inside the boundary
fallbackReactNode | FallbackRenderCustom fallback UI (uses default if not provided)
onError(error: Error, errorInfo: ErrorInfo) => voidAdditional callback after error is reported
onReset() => voidCallback fired when the boundary resets
showFeedbackDialogboolean= trueShow feedback dialog in fallback UI
showStackTraceboolean= trueShow stack trace in development mode
reportToMonitoringboolean= trueReport errors to Sylphx monitoring
contextRecord<string, unknown>Additional context to include with error reports
tagsRecord<string, string>Tags for error categorization
level"fatal" | "error" | "warning"= "error"Error severity level
beforeReport(error: Error) => Error | nullTransform or filter errors before reporting
resetKeysunknown[]Values that trigger a reset when changed
themeThemeVariablesCustom theme for default fallback UI
classNamestringAdditional CSS classes

Integration Examples

<SylphxErrorBoundary
  context={{
    page: 'checkout',
    cartItems: cart.items.length,
    paymentMethod: selectedMethod,
  }}
  tags={{
    component: 'checkout-flow',
    severity: 'critical',
  }}
  level="fatal"
>
  <CheckoutForm />
</SylphxErrorBoundary>

Default Fallback UI

When no custom fallback is provided, SylphxErrorBoundary renders a polished error page with:

Error illustration and message
Retry button to reset boundary
Optional feedback dialog trigger
Error ID for support reference
Stack trace (development only)
Responsive design

Provider Required

SylphxErrorBoundary requires SylphxProvider to be an ancestor component for error reporting to work.

FeedbackWidget

A floating or embedded widget for collecting user feedback, bug reports, and feature requests. Includes screenshot capture, sentiment tracking, and integration with error reports.

Screenshot Capture
Sentiment Tracking
Themeable
Basic Usage
import { FeedbackWidget } from '@sylphx/platform-sdk/react'

export default function App() {
  return (
    <>
      <main>
        <YourApplication />
      </main>

      {/* Floating feedback button */}
      <FeedbackWidget
        position="bottom-right"
        onSubmit={(feedback) => {
          console.log('Feedback received:', feedback)
        }}
      />
    </>
  )
}

Props

PropertyTypeDescription
onSubmit(feedback: Feedback) => void | Promise<void>Callback when feedback is submitted
onOpen() => voidCallback when widget opens
onClose() => voidCallback when widget closes
position"bottom-right" | "bottom-left" | "top-right" | "top-left"= "bottom-right"Widget position for floating mode
mode"floating" | "inline" | "modal"= "floating"Widget display mode
showScreenshotButtonboolean= trueEnable screenshot capture
showSentimentboolean= trueShow sentiment (thumbs up/down) selector
showCategoryboolean= trueShow category selector
categoriesstring[]= ["Bug", "Feature", "Question", "Other"]Available feedback categories
placeholderstring= "What's on your mind?"Textarea placeholder text
titlestring= "Send Feedback"Widget title
submitLabelstring= "Send Feedback"Submit button text
successMessagestring= "Thanks for your feedback!"Message shown after submission
attachErrorReportboolean= trueAttach recent error report if available
collectEmailboolean= falseAsk for email (if user not authenticated)
triggerComponentReactNodeCustom trigger button/element
defaultOpenboolean= falseOpen widget by default
themeThemeVariablesCustom theme overrides
classNamestringAdditional CSS classes

Widget Modes

// Fixed position button that opens a popover
<FeedbackWidget
  mode="floating"
  position="bottom-right"
  showScreenshotButton={true}
  showSentiment={true}
  categories={['Bug', 'Feature Request', 'Question']}
  onSubmit={async (feedback) => {
    await submitFeedback(feedback)
    toast.success('Thanks for your feedback!')
  }}
/>

Feedback Data Structure

Feedback Type
interface Feedback {
  // User message
  message: string

  // Selected category
  category?: 'Bug' | 'Feature' | 'Question' | 'Other' | string

  // Sentiment indicator
  sentiment?: 'positive' | 'negative' | null

  // Base64 encoded screenshot
  screenshot?: string

  // User email (if collected)
  email?: string

  // Attached error report ID
  errorReportId?: string

  // Auto-collected context
  context: {
    url: string
    userAgent: string
    timestamp: string
    viewport: { width: number; height: number }
  }

  // User ID (if authenticated)
  userId?: string
}

Integration with Error Boundary

Error + Feedback Integration
import { SylphxErrorBoundary, FeedbackWidget } from '@sylphx/platform-sdk/react'

export function AppProviders({ children }) {
  return (
    <SylphxErrorBoundary
      showFeedbackDialog={false} // We'll use our own
      fallback={({ error, resetErrorBoundary, reportId }) => (
        <div className="min-h-screen flex items-center justify-center p-8">
          <div className="max-w-lg text-center">
            <Bug className="w-16 h-16 text-red-500 mx-auto mb-4" />
            <h1 className="text-2xl font-bold mb-2">Something went wrong</h1>
            <p className="text-muted-foreground mb-6">
              We've been notified and are looking into it.
            </p>

            {/* Inline feedback for errors */}
            <FeedbackWidget
              mode="inline"
              title="What were you trying to do?"
              placeholder="Describe what happened..."
              categories={['Page crashed', 'Button not working', 'Data not loading']}
              attachErrorReport={true}
              showScreenshotButton={false}
              onSubmit={async (feedback) => {
                await submitFeedback({ ...feedback, errorReportId: reportId })
                toast.success('Thanks! This helps us fix the issue faster.')
              }}
            />

            <button
              onClick={resetErrorBoundary}
              className="mt-4 px-6 py-2 border rounded-lg hover:bg-muted transition-colors"
            >
              Try Again
            </button>
          </div>
        </div>
      )}
    >
      {children}

      {/* Global floating feedback widget */}
      <FeedbackWidget position="bottom-right" />
    </SylphxErrorBoundary>
  )
}

Screenshot Permission

Screenshot capture uses the browser's native screen capture API. Users will see a permission prompt on first use. The screenshot only captures the current tab.

Best Practices

Use Nested Boundaries

Wrap different sections of your app in separate error boundaries to prevent one failure from taking down the entire page.

Add Context to Reports

Include relevant context like user actions, feature flags, and app state to make debugging easier.

Filter Sensitive Data

Use beforeReport to sanitize error messages and remove sensitive information before sending.

Enable User Feedback

Users often know what triggered the error. Collecting feedback provides valuable debugging context.

Need programmatic error handling?

Use the error tracking API for server-side errors and custom error capture.