IOptionalBrowserSettings

IOptionalBrowserSettings represents the optional settings of the Browser.

Signature

interface IOptionalBrowserSettings

Example

import { Browser } from "happy-dom";

const browser = new Browser({
    settings: {
        navigator: : {
           userAgent: "Mozilla/5.0 (X11; Linux x64) AppleWebKit/537.36 (KHTML, like Gecko) HappyDOM/2.0.0"
        }
    }
});

Properties

Property	Type	Default	Description
JavaScript Execution
enableJavaScriptEvaluation?	boolean	false	Enables JavaScript evaluation and script file loading. Security warning: VM contexts are not isolated; untrusted code risks RCE.
disableJavaScriptFileLoading?	boolean	false	Blocks external script loading while allowing inline scripts. Requires "enableJavaScriptEvaluation: true".
suppressInsecureJavaScriptEnvironmentWarning?	boolean	false	Suppresses security warning when running in insecure environment. Requires "enableJavaScriptEvaluation: true".
CSS
disableCSSFileLoading?	boolean	false	Blocks <link rel="stylesheet"> loading. Note: CSS loads by default.
disableComputedStyleRendering?	boolean	false	Disables computed style calculations (e.g. "rem" to "px").
Canvas
canvasAdapter?	ICanvasAdapter		Set an adapter for handling canvas rendering. Happy DOM provide with the package @happy-dom/node-canvas-adapter. Requires "enableImageFileLoading" to support loading images from URLs
Resource Loading
handleDisabledFileLoadingAsSuccess?	boolean	false	Fire load instead of error when file loading is disabled. Requires "disableJavaScriptFileLoading" or "disableCSSFileLoading" set to "true".
enableImageFileLoading?	boolean	false	Enables loading of image files (e.g. by using <img src="file.jpg" />)
Error Handling
errorCapture?	BrowserErrorCaptureEnum	"tryAndCatch"	Error capturing policy.
Navigation
navigation.disableMainFrameNavigation?	boolean	false	Prevents navigation in the main frame.
navigation.disableChildFrameNavigation?	boolean	false	Prevents navigation in child frames (e.g. frames).
navigation.disableChildPageNavigation?	boolean	false	Prevents navigation in child pages (popups).
navigation.disableFallbackToSetURL?	boolean	false	Disables setting URL as fallback when navigation is disabled.
navigation.crossOriginPolicy?	BrowserNavigationCrossOriginPolicyEnum	"anyOrigin"	Cross-origin navigation policy.
navigation.beforeContentCallback?	(window: BrowserWindow) => void		Hook triggered before content loads.
Browser Identity
navigator.userAgent?	string		Custom user agent string.
navigator.maxTouchPoints?	number	0	Maximum touch points.
Timers
timer.maxTimeout?	number	-1 (unlimited)	Max timeout duration in ms.
timer.maxIntervalTime?	number	-1 (unlimited)	Max interval duration in ms.
timer.maxIntervalIterations?	number	-1 (unlimited)	Max interval iterations.
timer.preventTimerLoops?	boolean	false	Prevents self-calling timer loops.
Device / Media Queries
device.prefersColorScheme?	string	"light"	Prefers color scheme.
device.mediaType?	string	"screen"	Media type.
device.prefersReducedMotion?	string	"no-preference"	Prefers reduced motion.
device.forcedColors?	string	"none"	Forced colors ("active" or "none")
Fetch / Network
fetch.disableSameOriginPolicy?	boolean	false	Disables same-origin restrictions.
fetch.disableStrictSSL?	boolean	false	Allows self-signed certificates.
fetch.interceptor?	IFetchInterceptor		Intercept fetch requests and responses using hooks.
fetch.requestHeaders?	IFetchRequestHeaders[]		Custom headers for matching URLs.
fetch.virtualServers?	IVirtualServer[]		Simulate HTTP servers from filesystem.
ECMAScript Modules (ESM)
module.resolveNodeModules?	IResolveNodeModules		Resolve node modules.
module.urlResolver?	(options: { url: string; parentURL: string; window: BrowserWindow }) => string		Adds a custom URL resolver.
module.disableCache?	boolean	false	Disables compiler cache.
Debugging
debug.traceWaitUntilComplete?	number	-1 (disabled)	Timeout for waitUntilComplete() tracing.
Viewport
viewport?	IOptionalBrowserPageViewport		Default viewport configuration.