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:

importReactfrom'react';import{logger,LogWindow}from'react-log-window';functionApp(){// Log directly using the global loggerconsthandleClick=()=>{logger.info("Button clicked");};return(<divclassName="app"><buttononClick={handleClick}>Log Something</button>{/* Display logs */}<LogWindow/></div>);}

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

importReactfrom'react';import{LoggerProvider,useLogger,LogWindow}from'react-log-window';functionApp(){return(<LoggerProvidermaxEntries={500}><YourApp/><LogWindow/></LoggerProvider>);}functionYourApp(){constlogger=useLogger();consthandleAction=()=>{logger.info("Action performed");};return(<div><buttononClick={handleAction}>Perform Action</button></div>);}

Logging from Components

importReactfrom'react';import{useLogger}from'react-log-window';functionUserDashboard(){constlogger=useLogger();consthandleAction=()=>{logger.info("User initiated action");try{// Do somethinglogger.debug("Action details",{id: 123,type: "update"});// Successlogger.info("Action completed successfully");}catch(error){logger.error("Action failed",error);}};return(<div><buttononClick={handleAction}>Perform Action</button></div>);}

Logging Outside React Components

import{logger}from'react-log-window';// In a utility function or servicefunctionapiService(){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

<LogWindowoverlay={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

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

Downloading Logs Programmatically

functionDebugPanel(){constlogger=useLogger();return(<div><buttononClick={()=>logger.download("application-logs.txt")}>
Download Logs
</button><buttononClick={()=>logger.clear()}>
Clear Logs
</button></div>);}

Subscribing to Log Changes

useEffect(()=>{constunsubscribe=logger.subscribe((logs)=>{// Do something with updated logsconsole.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:8px12px;
}
/* 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:

<LogWindowclassName="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