useMemoryMonitor

useMemoryMonitor(options?)

A hook that monitors browser memory usage in real-time with leak detection and threshold alerts.

Parameters

Parameter	Type	Default	Description
options	UseMemoryMonitorOptions	{}	Configuration options (see below)

Options (UseMemoryMonitorOptions)

Option	Type	Default	Description
interval	number	5000	Polling interval in milliseconds
autoStart	boolean	true	Start monitoring automatically on mount
enabled	boolean	true	Enable/disable the hook
enableHistory	boolean	false	Record memory history into a circular buffer
historySize	number	50	Maximum number of history entries
thresholds	ThresholdOptions	See below	Warning/critical usage thresholds
leakDetection	LeakDetectionOptions	See below	Leak detection configuration
devMode	boolean	false	Enable development-mode features
trackDOMNodes	boolean	false	Track the document's DOM node count
trackEventListeners	boolean	false	Estimate the event listener count
logToConsole	boolean	false	Log updates to the console (with devMode)
disableInProduction	boolean	false	Disable monitoring in production builds
fallbackStrategy	FallbackStrategy	"dom-only"	Fallback for browsers without the heap API
onUpdate	(memory) => void	-	Called on each memory update
onWarning	(data) => void	-	Called when the warning threshold is exceeded
onCritical	(data) => void	-	Called when the critical threshold is exceeded
onLeakDetected	(analysis) => void	-	Called when a memory leak is detected
onUnsupported	(info) => void	-	Called when memory monitoring is not supported

Default Thresholds (ThresholdOptions)

{
  warning: 70,   // severity becomes "warning" at 70% of the heap limit
  critical: 90,  // severity becomes "critical" at 90% of the heap limit
}

Default Leak Detection (LeakDetectionOptions)

{
  enabled: false,         // opt in to enable leak analysis
  sensitivity: "medium",  // 'low' | 'medium' | 'high'
  windowSize: 20,         // number of recent samples to analyze
  threshold: undefined,   // optional custom growth threshold (bytes/sample)
}

Leak detection requires enableHistory: true so there are samples to analyze.

Returns UseMemoryMonitorReturn

Property	Type	Description
memory	MemoryInfo | null	Current memory information
heapUsed	number | null	Used heap size in bytes
heapTotal	number | null	Total heap size in bytes
heapLimit	number | null	Heap size limit in bytes
usagePercentage	number | null	Heap usage as a percentage of the limit
domNodes	number | null	DOM node count (when trackDOMNodes is enabled)
eventListeners	number | null	Estimated listener count (when tracking)
isSupported	boolean	Whether memory monitoring is supported
isMonitoring	boolean	Whether monitoring is currently active
isLeakDetected	boolean	Whether a memory leak is currently detected
severity	Severity	Current severity level
supportLevel	SupportLevel	'full' | 'partial' | 'none'
availableMetrics	readonly AvailableMetric[]	Metrics available in this browser
history	readonly MemoryInfo[]	Historical memory data (empty if history is off)
trend	Trend	Memory usage trend
leakProbability	number	Current leak probability (0–100)
formatted	FormattedMemory	Human-readable formatted values
start	() => void	Start monitoring
stop	() => void	Stop monitoring
takeSnapshot	(id: string) => MemorySnapshot | null	Take a named memory snapshot
compareSnapshots	(id1: string, id2: string) => SnapshotDiff | null	Compare two named snapshots
clearHistory	() => void	Clear the history buffer
requestGC	() => void	Request garbage collection (hint only)

Types

Severity

type Severity = "normal" | "warning" | "critical";

Trend

type Trend = "stable" | "increasing" | "decreasing";

MemoryInfo

interface MemoryInfo {
  /** Used JS heap size in bytes */
  heapUsed: number;
  /** Total JS heap size in bytes */
  heapTotal: number;
  /** JS heap size limit in bytes */
  heapLimit: number;
  /** Timestamp when this measurement was taken */
  timestamp: number;
}

SnapshotDiff

interface SnapshotDiff {
  /** Difference in heap usage (bytes) */
  heapDelta: number;
  /** Percentage change in heap usage */
  heapPercentChange: number;
  /** Difference in DOM node count (if tracked) */
  domNodesDelta?: number;
  /** Difference in event listener count (if tracked) */
  eventListenersDelta?: number;
  /** Time elapsed between snapshots (ms) */
  timeDelta: number;
}

FormattedMemory

interface FormattedMemory {
  heapUsed: string;
  heapTotal: string;
  heapLimit: string;
  domNodes?: string;
  eventListeners?: string;
}

---