react-log-window

A lightweight, customizable logging window for React applications that provides user-facing logs. This library helps you display application events, errors, and information to your users in a clean, filterable interface.

Features

• 📋 Display user-facing logs in a clean, filterable interface
• 🎨 Light, dark, and auto themes
• 🔍 Filter logs by severity level (debug, info, warn, error)
• 📱 Responsive design with customizable dimensions
• 🖱️ Optional draggable and resizable window
• 📥 Download logs as text files
• 🔄 Auto-scrolling with smart pause/resume
• 🧩 Works both inside and outside React components
• 🌐 Global singleton logger - use anywhere without providers
• 🎭 Fully customizable with CSS

Installation

npm install react-log-window
# or
yarn add react-log-window

Basic Usage

Option 1: Quick Start (No Provider Required)

You can start logging immediately without setting up a provider:

import React from 'react';
import { logger, LogWindow } from 'react-log-window';

function App() {
  // Log directly using the global logger
  const handleClick = () => {
    logger.info("Button clicked");
  };
  
  return (
    <div className="app">
      <button onClick={handleClick}>Log Something</button>
      
      {/* Display logs */}
      <LogWindow />
    </div>
  );
}

Option 2: With Provider (Recommended for Component-Specific Control)

import React from 'react';
import { LoggerProvider, useLogger, LogWindow } from 'react-log-window';

function App() {
  return (
    <LoggerProvider maxEntries={500}>
      <YourApp />
      <LogWindow />
    </LoggerProvider>
  );
}

function YourApp() {
  const logger = useLogger();
  
  const handleAction = () => {
    logger.info("Action performed");
  };
  
  return (
    <div>
      <button onClick={handleAction}>Perform Action</button>
    </div>
  );
}

Logging from Components

import React from 'react';
import { useLogger } from 'react-log-window';

function UserDashboard() {
  const logger = useLogger();
  
  const handleAction = () => {
    logger.info("User initiated action");
    
    try {
      // Do something
      logger.debug("Action details", { id: 123, type: "update" });
      
      // Success
      logger.info("Action completed successfully");
    } catch (error) {
      logger.error("Action failed", error);
    }
  };
  
  return (
    <div>
      <button onClick={handleAction}>Perform Action</button>
    </div>
  );
}

Logging Outside React Components

import { logger } from 'react-log-window';

// In a utility function or service
function apiService() {
  logger.info("API service initialized");
  
  return {
    makeRequest: (url) => {
      logger.debug(`Making request to ${url}`);
      // Request logic
    }
  };
}

Advanced Usage

Floating, Draggable Log Window without controls and timestamps

<LogWindow 
  overlay={true}
  draggable={true}
  resizable={true}
  height={400}
  width={600}
  showControls={false}
  showTimestamp={false}
  theme="auto"
  defaultFilter={['warn', 'error']}
/>

Provider vs. No Provider

The library allows you to:

• Use without Provider: Logs are stored in a global singleton accessible everywhere
• Use with Provider: Logs are stored in the given context. Note that the provider will also access and display the global singleton logs.

The useLogger() hook automatically falls back to the global logger when used outside a provider.

Customizing the LoggerProvider

<LoggerProvider maxEntries={1000}>
  <YourApp />
</LoggerProvider>

Downloading Logs Programmatically

function DebugPanel() {
  const logger = useLogger();
  
  return (
    <div>
      <button onClick={() => logger.download("application-logs.txt")}>
        Download Logs
      </button>
      <button onClick={() => logger.clear()}>
        Clear Logs
      </button>
    </div>
  );
}

Subscribing to Log Changes

useEffect(() => {
  const unsubscribe = logger.subscribe((logs) => {
    // Do something with updated logs
    console.log(`Log count: ${logs.length}`);
  });
  
  return () => unsubscribe();
}, []);

Styling and Customization

The library uses standard CSS classes that you can override for complete visual customization.

CSS Classes

Component	CSS Classes
Main Container	.log-window, .log-window-overlay, .log-window-theme-light, .log-window-theme-dark
Header	.log-window-header, .log-window-title
Controls	.log-window-controls, .log-window-filters, .log-window-actions
Filter Buttons	.log-window-filter-btn, .log-window-level-debug, .log-window-level-info, .log-window-level-warn, .log-window-level-error
Action Buttons	log-window-theme-select, .log-window-action-btn, log-window-download-btn, log-window-clear-btn
Content	.log-window-content, .log-window-empty
Log Entry	.log-window-entry, .log-window-timestamp, .log-window-level, log-window-message, .log-window-data
Auto-scroll	.log-window-auto-scroll-active, .log-window-auto-scroll-btn
Resize Handle	.log-window-resize-handle

See components.css for the default styling.

Custom Styling Example

/* Custom dark theme */
.log-window-theme-dark {
  background-color: #1a1a1a;
  color: #e0e0e0;
  border: 1px solid #333;
}

/* Custom styling for error logs */
.log-window-level-error {
  background-color: rgba(255, 0, 0, 0.1);
  border-left: 4px solid #ff3333;
}

/* Custom header */
.log-window-header {
  background-color: #2a2a2a;
  padding: 8px 12px;
}

/* Custom scrollbar */
.log-window-content::-webkit-scrollbar {
  width: 8px;
}

.log-window-content::-webkit-scrollbar-thumb {
  background-color: #555;
  border-radius: 4px;
}

Adding Custom Classes

You can also add your own classes using the className prop:

<LogWindow 
  className="my-custom-log-window"
  height={300}
/>

API Reference

LoggerProvider Props

Prop	Type	Default	Description
maxEntries	number	1000	Maximum number of log entries to retain
children	ReactNode		Child components

LogWindow Props

Prop	Type	Default	Description
theme	'light' | 'dark' | 'auto'	'auto'	Visual theme
height	number | string	300	Height of the log window
width	number | string	'100%'	Width of the log window
overlay	boolean	false	Whether to display as floating overlay
draggable	boolean	false	Whether window can be moved (requires overlay)
resizable	boolean	false	Whether window can be resized
maxEntries	number	1000	Maximum number of entries to display
defaultFilter	LogLevel[]	['debug', 'info', 'warn', 'error']	Default log levels to display
showTimestamp	boolean	true	Whether to show timestamps
showControls	boolean	true	Whether to show filter and action controls
className	string	''	Additional CSS class names

Logger Methods

Method	Parameters	Description
debug	(message: string, data?: any)	Log debug message
info	(message: string, data?: any)	Log info message
warn	(message: string, data?: any)	Log warning message
error	(message: string, data?: any)	Log error message
clear	()	Clear all logs
download	(filename?: string)	Download logs as text file
subscribe	(callback: (logs: LogEntry[]) => void)	Subscribe to log changes

Use Cases

This library was created specifically with the thought of showing the actual user what is going in the background. It was never intended to provide insight to the developer and thus does not offer an option to send the logs to a remote server.

However, in cases of small applications where remote logs might be an overkill or are not desired, this could also prove useful for developing and debugging.

The focus is on improving the user experience through transparency, not on developer-focused logging or telemetry.

License

MIT