What Is the no-large-media Switch in uBlock Origin? Per-Site Media Blocking Explained

The no-large-media switch is a per-site privacy control in uBlock Origin that blocks media elements—including images, video, and audio—whose decoded size exceeds a user-defined threshold, allowing users to reduce bandwidth usage and eliminate heavyweight content on specific websites without affecting global browsing settings.

The no-large-media switch operates as part of uBlock Origin's hostname-specific privacy controls. When activated for a particular site, the extension prevents media elements larger than the Large Media Size setting (default approximately 50 KB) from rendering, while leaving media on other domains untouched.

How the no-large-media Switch Works Internally

When you enable the no-large-media toggle in the uBlock Origin popup, the extension executes a coordinated sequence across its internal modules to enforce size-based filtering.

Popup UI Synchronization

The visual state of the switch is managed in src/popup-fenix.html and controlled by src/js/popup-fenix.js. The button element carries the ID #no-large-media, and its active state is synchronized via:

dom.cl.toggle('#no-large-media', 'on', popupData.noLargeMedia === true);

This line at src/js/popup-fenix.js:580 ensures the button appearance matches the current per-site setting stored in the session.

Session and Permanent State Management

The core logic for toggling the switch resides in src/js/ublock.js. When you change the setting via µb.changeUserSettings('noLargeMedia', true), the extension performs two critical operations:

1. Session switch update: sessionSwitches.toggle('no-large-media', '*', 1) stores the temporary state for the current hostname.
2. Persistence: If the change should persist across browser restarts, permanentSwitches.toggle() writes to µb.hostnamesSwitches, followed by µb.saveHostnameSwitches() to commit to browser storage.

You can read the current effective state using:

us.noLargeMedia = sessionSwitches.evaluate('no-large-media', '*') === 1;

This evaluation appears at src/js/ublock.js:310-311 and determines whether the switch is active for the current context.

Size-Based Filtering in the Page Store

The actual blocking mechanism executes in src/js/pagestore.js during media element processing. For each candidate element, uBlock Origin compares the decoded size against your threshold:

if ( (size >>> 10) < µb.userSettings.largeMediaSize ) { return 0; }

Found at lines 1082-1083, this logic uses an unsigned right shift (>>> 10) to convert bytes to kilobytes. If the element's size in KB is less than largeMediaSize, the function returns 0 to allow the element; otherwise, the element is hidden from the page.

Configuring the Large Media Threshold

The default threshold of approximately 50 KB can be adjusted in the Settings interface. The configuration UI is defined in src/settings.html (lines 59-60), providing both a checkbox to enable the switch globally and a numeric input to set largeMediaSize in kilobytes.

To modify the threshold programmatically:

// Set limit to 100 KB
µb.changeUserSettings('largeMediaSize', 100);

Programmatic Control Examples

Developers and advanced users can manipulate the no-large-media switch through the internal API:

Toggle for current site:

// Enable blocking
µb.changeUserSettings('noLargeMedia', true);

// Check current state
if ( µb.userSettings.noLargeMedia ) {
    console.log('Large-media blocking active for this hostname');
}

Simulate popup button behavior:

document.getElementById('no-large-media').addEventListener('click', ev => {
    const enabled = ev.currentTarget.classList.toggle('on');
    µb.changeUserSettings('noLargeMedia', enabled);
});

Summary

• The no-large-media switch is a hostname-specific control that blocks media exceeding a size threshold defined in µb.userSettings.largeMediaSize.
• Implementation spans src/js/ublock.js (state management), src/js/pagestore.js (filtering logic), and popup UI files.
• Default threshold is ~50 KB, configurable via the Settings page or changeUserSettings().
• The size check at pagestore.js:1082 uses bitwise operations (size >>> 10) to compare bytes against the KB threshold.
• Changes persist through permanentSwitches and saveHostnameSwitches() in the uBlock core.

Frequently Asked Questions

How do I enable no-large-media for only one website?

Click the uBlock Origin icon in your browser toolbar, then click the No large media button in the popup. This activates the switch exclusively for the current hostname using sessionSwitches.evaluate('no-large-media', '*') logic, leaving other sites unaffected.

Why are some small images still blocked when I enable no-large-media?

The switch checks the decoded (uncompressed) size of media elements, not the file size. A highly compressed JPEG might have a small file size but large decoded dimensions, triggering the block if the decoded bitmap exceeds your largeMediaSize threshold (default ~50 KB).

Where is the no-large-media setting stored?

The setting is stored in two places: temporarily in the session switches via sessionSwitches.toggle(), and permanently in µb.hostnamesSwitches which serializes to browser storage through saveHostnameSwitches() when you choose to persist the change for a site.

Can I change the default 50 KB threshold?

Yes. Navigate to uBlock Origin Settings, locate the Large media size input field (defined in src/settings.html), and enter your preferred limit in kilobytes. Programmatically, call µb.changeUserSettings('largeMediaSize', yourValueInKB) to update the limit immediately.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}