@faultlens/react

Beautiful, themeable React components for displaying API/HTTP error states with animated SVG icons.

Features

• 🎨 12 Error Codes — Built-in configs for 400, 401, 403, 404, 408, 429, 500, 502, 503, 504, network errors, and unknown errors
• ✨ 3 Icon Variants — Default (animated), Minimal (line-based), and Filled (bold shapes)
• 🎭 Themeable — Full theming system with per-error-code overrides, custom colors, and custom icons
• 📱 Compact Mode — Inline-friendly compact layout for notifications/toasts
• 🔧 Technical Details — Expandable panel with request ID, timestamp, stack trace, and copy-to-clipboard
• ⚡ Tree-Shakeable — Only import what you need
• 🔤 TypeScript — Full type definitions included
• ⚛️ Next.js Ready — "use client" directives included

Installation

npm install @faultlens/react

Peer Dependencies

npm install react react-dom lucide-react

The component uses Tailwind CSS classes for styling. If you're using Tailwind in your project, the styles will work automatically. Ensure your Tailwind config scans the package:

// tailwind.config.js
module.exports = {
  content: [
    // ... your paths
    './node_modules/@faultlens/react/dist/**/*.{js,mjs,cjs}',
  ],
};

Quick Start

import { ErrorDetail } from '@faultlens/react';

function MyErrorPage() {
  return (
    <ErrorDetail
      error={{ code: 404, message: 'Page not found' }}
      onGoHome={() => navigate('/')}
      onGoBack={() => navigate(-1)}
    />
  );
}

API Reference

<ErrorDetail />

| Prop | Type | Default | Description | |---|---|---|---| | error | ApiError | required | Error object with code and optional details | | onRetry | () => void | — | Handler for retry action | | onGoHome | () => void | — | Handler for go home action | | onGoBack | () => void | — | Handler for go back action | | onLogin | () => void | — | Handler for login action | | onContactSupport | () => void | — | Handler for contact support action | | onRefresh | () => void | — | Handler for refresh action | | showTechnicalDetails | boolean | true | Show expandable technical details panel | | compact | boolean | false | Use compact inline layout | | className | string | '' | Additional CSS classes | | theme | ErrorThemeConfig | — | Direct theme override (takes priority over context) |

ApiError

interface ApiError {
  code: number | string;    // HTTP status code or custom code
  message?: string;         // Custom error message
  details?: string;         // Additional details
  requestId?: string;       // Request tracking ID
  timestamp?: string;       // ISO timestamp
  stackTrace?: string;      // Stack trace for debugging
  url?: string;             // Request URL
}

Supported Error Codes

| Code | Title | Icon | Severity | |---|---|---|---| | 400 | Bad Request | Warning triangle | warning | | 401 | Unauthorized | Lock | warning | | 403 | Access Denied | Shield with X | critical | | 404 | Not Found | Magnifying glass | info | | 408 | Request Timeout | Clock | warning | | 429 | Too Many Requests | Speedometer | warning | | 500 | Internal Server Error | Server on fire | critical | | 502 | Bad Gateway | Broken chain | critical | | 503 | Service Unavailable | Gears | warning | | 504 | Gateway Timeout | Clock | warning | | network | Network Error | WiFi disconnected | critical | | unknown | Something Went Wrong | Sad face | info |

Compact Mode

For inline error display (toasts, notifications, sidebars):

<ErrorDetail
  error={{ code: 500, message: 'Server error' }}
  onRetry={() => refetch()}
  compact
/>

Theming

Using Theme Provider

Wrap your app or a section with ErrorThemeProvider:

import { ErrorDetail, ErrorThemeProvider } from '@faultlens/react';

const myTheme = {
  name: 'My Custom Theme',
  iconVariant: 'minimal',       // 'default' | 'minimal' | 'filled'
  borderRadius: '0.75rem',
  overrides: {
    404: {
      title: 'Oops! Page Missing',
      description: 'We couldn\'t find what you\'re looking for.',
      colors: {
        primary: '#6366F1',
        background: '#EEF2FF',
      },
    },
  },
};

function App() {
  return (
    <ErrorThemeProvider theme={myTheme}>
      <ErrorDetail error={{ code: 404 }} onGoHome={() => navigate('/')} />
    </ErrorThemeProvider>
  );
}

Direct Theme Prop

Pass a theme directly to a single instance:

<ErrorDetail
  error={{ code: 500 }}
  theme={{ iconVariant: 'filled', borderRadius: '2rem' }}
  onRetry={() => refetch()}
/>

Theme Override Options

interface ErrorCodeOverride {
  title?: string;
  description?: string;
  suggestion?: string;
  severity?: 'critical' | 'warning' | 'info';
  iconType?: string;
  customIcon?: React.ComponentType;
  colors?: {
    primary?: string;
    background?: string;
    backgroundEnd?: string;
    border?: string;
    text?: string;
    badgeBg?: string;
    badgeText?: string;
  };
  actions?: ErrorAction[];
}

Icon Variants

Default — Animated SVGs with CSS keyframe animations

Minimal — Clean line-based icons with subtle animations

Filled — Bold, filled shapes with vibrant colors

Switch globally via theme:

<ErrorThemeProvider theme={{ iconVariant: 'filled' }}>
  {/* All ErrorDetail instances use filled icons */}
</ErrorThemeProvider>

Using Icons Standalone

import { AnimatedErrorIcon, iconMap, minimalIconMap, filledIconMap } from '@faultlens/react';

// Convenience component
<AnimatedErrorIcon iconType="notFound" />

// Direct from map
const ServerErrorIcon = iconMap['serverError'];
<ServerErrorIcon />

Utilities

import { getErrorConfig, serializeTheme, parseTheme } from '@faultlens/react';

// Get default config for any error code
const config = getErrorConfig(404);
console.log(config.title); // "Not Found"

// Serialize/parse themes for storage
const json = serializeTheme(myTheme);
const theme = parseTheme(json);

License

MIT