Using custom scriptlets to make the Web work the way you want

This is the 32nd post in an ongoing series describing new privacy features in Brave. This post describes work done by Pavel Beloborodov (Senior Software Engineer), and was written by Shivan Kaul Sahib (Lead for Privacy Engineering).

Starting with desktop version 1.75, advanced Brave users will be able to write and inject their own scriptlets into a page, allowing for better control over their browsing experience.

Customize a website’s appearance with custom scriptlets

Brave already offers the cleanest and safest out-of-the-box browsing experience of any Web browser. Users get best-in-class 3rd-party ad and tracker blocking, privacy protections, cookie notice blocking, and many other enhancements (read more on our privacy updates blog series). Most importantly, these features are enabled by default, so users get the best possible experience the moment they install Brave. There’s no need to manually install Web extensions (and take on the risk of malware) or worry about Google’s Manifest V3 changes. With Brave, things just work.

However, some users want the freedom to customize how ads and trackers are blocked in their browser. In addition to offering the ability to write custom filters and subscribe to community-maintained ones, we now support custom scriptlets that enable advanced users to write JavaScript and inject it into any website.

With great power comes great responsibility

Adblockers like Brave Shields, uBlock Origin, and Adguard already use scriptlets internally for extended blocking capabilities. For instance, they can load a harmless version of a tracking script instead of the real one, maximizing privacy while minimizing breakage. Custom scriptlets bring this same power to Brave users. However, this power requires extreme caution. Only scripts that are confirmed safe should be injected, and for this reason the feature is “gated” behind a Developer mode flag in Shields > Content filtering. 

Custom scriptlets are stored locally in your browser, and never leave the device.

How to use custom scriptlets

1. On desktop, open the Settings menu.
2. Navigate to the Shields section, then to Content filtering. (Or you can go directly to brave://settings/shields/filters.)
3. Scroll down and enable Developer mode.

4. Under Custom scriptlets, click Add new scriptlet and write your JavaScript. Give it a name (note that the custom scriptlet always gets saved with a user- prefix). Then click Save. 

5. Finally, insert the rule by adding a custom rule for the website you want to modify, and press Save changes. Note that you must use filter rule syntax, which looks something like “example.com##+js(name-of-your-scriptlet.js)”. For more information, see the custom scriptlet technical documentation.

Once the scriptlet is done, you can visit the website you just modified to see the difference:

Before: stackoverflow.com without the custom scriptlet

After: cleaned up stackoverflow.com with the custom scriptlet which removed the sidebars

Editing or deleting a custom scriptlet

You can easily edit or delete your custom scriptlet using the buttons on the right.

Another way Brave makes the Web user-first

By default, Brave prevents fingerprinting while ensuring functionality on websites by randomizing the output of many Web APIs. But with custom scriptlets, you could completely disable a Web API on a website you don’t trust. You could also inject a scriptlet to prevent websites from disabling right-click. The possibilities are endless.

Brave prioritizes the user first, in line with the W3C’s priority of constituencies. Our bet on best-in-class 3rd-party ad and tracker blocking reflects this user-first approach. We initially built custom scriptlets to help us with our own adblock-related debugging, but decided to release it as a feature because it proved so useful. Please give it a try, and tell us what you think on community.brave.com, GitHub or social media.