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

> Learn about uBlock Origin's no-large-media switch. Block large media per site to save bandwidth and reduce heavyweight content globally or on specific pages.

- Repository: [Raymond Hill/uBlock](https://github.com/gorhill/uBlock)
- Tags: deep-dive
- Published: 2026-03-05

---

**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`](https://github.com/gorhill/uBlock/blob/main/src/popup-fenix.html) and controlled by [`src/js/popup-fenix.js`](https://github.com/gorhill/uBlock/blob/main/src/js/popup-fenix.js). The button element carries the ID `#no-large-media`, and its active state is synchronized via:

```javascript
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`](https://github.com/gorhill/uBlock/blob/main/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:

```javascript
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`](https://github.com/gorhill/uBlock/blob/main/src/js/pagestore.js) during media element processing. For each candidate element, uBlock Origin compares the decoded size against your threshold:

```javascript
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`](https://github.com/gorhill/uBlock/blob/main/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:

```javascript
// 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:**

```javascript
// 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:**

```javascript
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`](https://github.com/gorhill/uBlock/blob/main/src/js/ublock.js) (state management), [`src/js/pagestore.js`](https://github.com/gorhill/uBlock/blob/main/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`](https://github.com/gorhill/uBlock/blob/main/src/settings.html)), and enter your preferred limit in kilobytes. Programmatically, call `µb.changeUserSettings('largeMediaSize', yourValueInKB)` to update the limit immediately.