What custom scripts do in uBlock Origin

uBlock Origin lets you add your own code — called scripts — that run on websites you choose. These scripts can hide elements, change how a page looks, block specific content, or automate repetitive tasks. Unlike uBlock's built-in filters, custom scripts let you write exact instructions for what happens on each site.

The scripts you add run only in your browser, only on the sites you specify, and only when you visit them. They do not affect anyone else's browsing or change the actual website for other users.

Key Takeaways

  • uBlock Origin's script feature is called the Dashboard, and you reach it by clicking the uBlock icon and selecting the gear icon in the popup.
  • Scripts go into the "My filters" tab, where you write rules using uBlock's filter syntax or JavaScript in a special format.
  • Each script needs a target — the website or websites where it should run — written as a URL pattern at the top.
  • After you paste or write a script, click "Apply changes" at the bottom of the Dashboard to save it.
  • If a script breaks a website or does not work, you can disable it by commenting it out with # or delete it entirely.

Opening the uBlock Origin Dashboard

Start by clicking the uBlock Origin icon in your browser's toolbar. It looks like a red and white shield. A small popup menu appears with several options.

In that popup, look for the gear icon in the bottom right corner and click it. This opens the Dashboard — the control panel where you manage all of uBlock's settings, including custom scripts.

The Dashboard opens in a new tab. You will see several tabs across the top: "Settings", "Filter lists", "My filters", and others. Click on the "My filters" tab. This is where you write and store your custom scripts.

Writing your first script with a target

Every script needs a target — a line that tells uBlock which website or websites the script should run on. The target goes at the very top and uses this format:

example.com

Replace "example.com" with the actual domain where you want the script to run. If you want it to run on all pages of that site, just use the domain name. If you want it to run only on a specific page, use the full URL path: example.com/specific-page.

After the target line, press Enter and write your script on the next line. For simple tasks like hiding an element, you can use a filter rule. For more complex tasks, you write JavaScript code wrapped in a special format that uBlock understands.

Using filter rules for common tasks

If you want to hide a specific element on a page — like an ad, a sidebar, or a banner — you do not need to write JavaScript. uBlock's filter syntax is simpler. The format looks like this:

example.com##.classname

This hides any element with the class "classname" on example.com. To find the class name of something you want to hide, right-click the element in your browser, select "Inspect" or "Inspect Element", and look for the class= attribute in the code that appears.

If the element uses an ID instead of a class, use a hash symbol: example.com##id-name. You can hide multiple elements by stacking rules — put each one on its own line with the same target at the top.

Writing JavaScript scripts for advanced tasks

For tasks that filter rules cannot handle — like changing text, moving elements around, or running code on a timer — you write JavaScript. The format wraps your code in a special container that uBlock recognizes:

example.com##+js(noeval)

This example uses one of uBlock's built-in JavaScript functions. For your own custom code, the format is more involved. You write your JavaScript inside a function, and uBlock runs it when the page loads.

If you are new to JavaScript, start with simple tasks: hiding elements with filter rules, or using uBlock's pre-built functions. Writing custom JavaScript requires understanding how the browser's DOM (Document Object Model) works, and mistakes can break a website's functionality.

Saving and testing your script

After you paste or write your script in the "My filters" tab, scroll to the bottom of the page and click the blue "Apply changes" button. This saves your script and tells uBlock to start using it.

Now visit the website where your script should run. If it is a filter rule that hides something, check that the element is gone. If it is JavaScript that does something else, test that behavior. Open your browser's developer tools (press F12 or right-click and select "Inspect") and check the Console tab for any error messages.

If something went wrong — the page looks broken, or your script did not work — go back to the Dashboard, find your script in "My filters", and either fix it or delete it. You can comment out a line by putting # at the start, which disables it without removing it.

Finding and using scripts others have written

You do not have to write scripts from scratch. Many people share scripts online in forums, GitHub repositories, and uBlock communities. When you find a script someone else wrote, copy the entire code block and paste it into the "My filters" tab, making sure the target line is at the top.

Always check that the target matches the website you want to use it on. A script written for one site may not work on another, even if they look similar. If you copy a script and it does not work, check the browser console for errors, and consider asking the person who wrote it for help.

Be cautious with scripts from sources you do not trust. A malicious script could theoretically steal information or cause harm. Stick to scripts from established communities, well-known developers, or sites with active moderation.

Frequently Asked Questions

Can I use the same script on multiple websites?

Yes. Instead of listing one domain in the target, use a pattern that matches multiple sites. For example, *example.com runs the script on example.com and any subdomain like mail.example.com or help.example.com. You can also list multiple targets by separating them with commas: site1.com, site2.com.

What happens if my script breaks a website?

The website still works — your script runs in your browser only and does not change the actual site. If your script causes problems, go back to the Dashboard, find it in "My filters", and delete it or comment it out by adding # at the start of each line. Refresh the website and it should work normally again.

Do I need to know JavaScript to add scripts?

Not for simple tasks. If you want to hide elements, use filter rules instead — they are much easier and do not require coding. For anything more complex, you will need to learn JavaScript basics or find a pre-written script that does what you want.

Will my scripts sync across devices?

No. Scripts you add in uBlock Origin are stored locally in your browser on that device. If you use the same browser on another computer, you will need to add the scripts again. Some browsers offer sync features for extensions, but script syncing is not may provide.

Can I undo a change if I mess something up?

uBlock does not have an undo button in the Dashboard. If you delete a script by accident, you will need to rewrite it or find it again. To be safe, copy important scripts to a text file on your computer before making big changes.