The Dashboard is uBlock Origin's primary configuration interface, providing access to all filtering and behavior customization options. It consists of eight distinct tabs, each implemented as a separate HTML page with corresponding JavaScript modules. The Dashboard is opened via the browser action button menu or keyboard shortcuts, and communicates with the background process through the vAPI.messaging system.
The Dashboard is a single HTML page (dashboard.html) with a sticky navigation bar (#dashboard-nav) and a full-page <iframe id="iframe"> that fills the content area. Tab navigation does not open new browser pages. Instead, dashboard.js calls loadDashboardPanel(pane, first), which executes iframe.contentWindow.location.replace(pane) to load the chosen pane HTML document into the shared iframe.
Before switching panes, discardUnsavedData() reads paneWindow.hasUnsavedData() from the iframe's contentWindow. If that returns true, the #unsavedWarning modal overlay is shown, letting the user stay or discard. The last visited pane is persisted to vAPI.localStorage under the key dashboardLastVisitedPane.
On each iframe load event, dashboard.js reads iframe.contentWindow.wikilink and sets the href on the .wikilink anchor in the nav bar. This means each pane JS module must assign self.wikilink to the relevant wiki URL and must expose self.hasUnsavedData().
Common CSS and JS utilities are shared via src/css/dashboard-common.css and src/js/dashboard-common.js
dashboard.html — iframe-based pane loading
Sources: src/dashboard.html17-40 src/js/dashboard.js26-96 src/js/settings.js303-307
| Pane file | data-i18n key | Display name |
|---|---|---|
settings.html | settingsPageName | Settings |
3p-filters.html | 3pPageName | Filter lists |
1p-filters.html | 1pPageName | My filters |
dyna-rules.html | rulesPageName | My rules |
whitelist.html | whitelistPageName | Trusted sites |
support.html | supportPageName | Support |
about.html | aboutPageName | About |
Sources: src/_locales/en/messages.json26-61 src/dashboard.html20-27
Each pane communicates with the background script via vAPI.messaging.send(channel, message). All dashboard panes use the channel name 'dashboard'. Messages are routed by the what field.
Common vAPI.messaging.send calls across dashboard panes:
| Sender | what value | Purpose |
|---|---|---|
settings.js | userSettings | Read or write a named user setting |
settings.js | backupUserData | Export settings to file |
settings.js | restoreUserData | Import settings from file |
settings.js | resetUserData | Reset all settings |
settings.js | getLocalData | Get storage usage and backup info |
3p-filters.js | getLists | Fetch all filter list data |
3p-filters.js | applyFilterListSelection | Commit list enable/disable changes |
3p-filters.js | reloadAllFilters | Recompile filtering engines |
3p-filters.js | updateNow | Force a filter list update pass |
3p-filters.js | listsUpdateNow | Update specific asset keys |
about.js | getAppData | Fetch extension name and version |
dashboard.js | readyToFilter | Wait for background initialization |
dashboard.js | dashboardConfig | Check if dashboard is restricted |
Sources: src/js/settings.js81-316 src/js/3p-filters.js298-649 src/js/about.js27-31 src/js/dashboard.js108-132
The Settings tab (settings.html) provides controls for general extension behavior, privacy features, appearance customization, and per-site default behaviors. Settings are organized into collapsible sections and persisted via browser.storage.local.
The settings.html pane is organized into fieldsets. Each UI control declares its backing setting via data-setting-name and data-setting-type HTML attributes. onUserSettingsReceived() in settings.js iterates all elements with data-setting-type="bool" or data-setting-type="value" to populate them and attach change handlers.
| Section | data-setting-name values | Fieldset label key |
|---|---|---|
| General | collapseBlocked, showIconBadge, contextMenuEnabled, cloudStorageEnabled | (top level) |
| Privacy | prefetchingDisabled, hyperlinkAuditingDisabled, webrtcIPAddressHidden, noCSPReports, cnameUncloakEnabled | 3pGroupPrivacy |
| Appearance | uiTheme (select), uiAccentCustom, uiAccentCustom0 (color), colorBlindFriendly, tooltipsDisabled | settingsAppearance |
| Default behavior | noCosmeticFiltering, noLargeMedia, largeMediaSize (number), noRemoteFonts, noScripting | settingPerSiteSwitchGroup |
| Advanced | advancedUserEnabled | settingsAdvanced |
Every change in a checkbox or input triggers changeUserSettings(name, value), which immediately sends vAPI.messaging.send('dashboard', { what: 'userSettings', name, value }). Settings are saved without a separate "Apply" button, so self.hasUnsavedData() always returns false for this pane.
The uiTheme and uiAccentCustom* settings are also reflected immediately in the current pane by calling setTheme() and setAccentColor() from theme.js.
Settings initialization and change flow:
Sources: src/settings.html15-99 src/js/settings.js203-317 src/_locales/en/messages.json318-413
The Filter Lists tab (3p-filters.html) manages third-party filter list subscriptions. It displays approximately 80+ available lists organized into groups (Built-in, Ads, Privacy, Malware, Social, Cookies, Annoyances, Multipurpose, Regions, Custom). Users can enable/disable lists, trigger updates, and import custom list URLs.
Filter lists are categorized into groups, each with a localized display name:
| Group ID | Message Key | Example Lists |
|---|---|---|
default | 3pGroupDefault | uBlock filters, Badware risks |
ads | 3pGroupAds | EasyList, EasyPrivacy |
privacy | 3pGroupPrivacy | Privacy tracking lists |
malware | 3pGroupMalware | Malware domains |
social | 3pGroupSocial | Social widget filters |
cookies | 3pGroupCookies | Cookie notice blockers |
annoyances | 3pGroupAnnoyances | Anti-adblock warnings |
multipurpose | 3pGroupMultipurpose | Multi-purpose lists |
regions | 3pGroupRegions | Region-specific lists |
custom | 3pGroupCustom | User-imported URLs |
Filter List Rendering Process:
Each list entry displays:
{{used}} used out of {{total}}Sources: src/3p-filters.html src/js/3p-filters.js src/_locales/en/messages.json422-537
Clicking "Update now" triggers buttonUpdateHandler() in 3p-filters.js, which first commits the current selection state (selectFilterLists()), then sends { what: 'updateNow' } to the background. The pane listens for background broadcast events via onBroadcast (imported from broadcast.js) to update the UI in real time.
Update button flow:
Sources: src/js/3p-filters.js37-52 src/js/3p-filters.js644-652 src/js/3p-filters.js320-337
The My Filters tab (1p-filters.html) provides a text editor for custom static filters. These filters use the same syntax as third-party filter lists but are stored locally in browser.storage.local under the key userFilters.
Key Features:
1pEnableMyFiltersLabel)1pTrustMyFiltersLabel)what: 'writeUserFilters' messageThe editor validates filter syntax on blur and displays parse errors. Filters are compiled by the Static Filtering Parser and added to the filtering engine when "Apply changes" is clicked.
Sources: src/1p-filters.html src/js/1p-filters.js src/_locales/en/messages.json538-565
The My Rules tab (dyna-rules.html) manages dynamic filtering rules created via the popup panel's point-and-click firewall. It displays both permanent and temporary rules in a split-pane view.
Rule Management Interface:
Rule Syntax: source destination type action
* example.com * block — block all requests to example.comexample.com * 3p noop — allow all 3rd-party requests from example.comThe rules editor uses CodeMirror with a custom mode. Rules are stored in browser.storage.local under dynamicFilteringString.
Sources: src/dashboard.html23 src/_locales/en/messages.json566-629
The Trusted Sites tab (whitelist.html) manages the "trusted sites" directive list, which specifies hostnames or URL patterns where uBlock Origin should be completely disabled. This is distinct from dynamic filtering rules.
Trusted Site Directives:
example.com, *.example.comhttps://example.com/*#The textarea content is stored in browser.storage.local as netWhitelist. When "Apply changes" is clicked, the background script:
Sources: src/whitelist.html src/js/whitelist.js src/_locales/en/messages.json630-649
The Shortcuts tab (shortcuts.html) provides an interface to view and modify keyboard shortcuts for common actions. It uses the browser's commands API to register and update shortcuts.
Available Shortcuts:
The UI displays the current key combination for each command and allows users to click an input field to capture a new key combination. Changes are saved via browser.commands.update().
Sources: src/shortcuts.html src/js/shortcuts.js src/_locales/en/messages.json1255-1283
The About tab (about.html) displays extension metadata, credits, and dependencies. It retrieves the extension name and version via a message to the background script (what: 'getAppData') and displays:
The JavaScript implementation in src/js/about.js is minimal, only fetching and displaying the version string.
Sources: src/about.html1-65 src/js/about.js1-33 src/_locales/en/messages.json1019-1058
The Support tab (support.html) provides help resources and troubleshooting tools. It is divided into several sections:
| Section | Purpose | Message Key |
|---|---|---|
| Documentation | Links to GitHub wiki | supportS1H, supportS1P1 |
| Questions and support | Reddit community link | supportS2H, supportS2P1 |
| Filter issues | Report website breakage to uAssets | supportS3H, supportS3P* |
| Bug report | Report extension bugs to uBlock-issues | supportS4H, supportS4P1 |
| Troubleshooting Information | Technical details for support | supportS5H, supportS5P1 |
| Report a filter issue | Wizard for creating filter issue reports | supportS6H, supportS6P* |
The "Troubleshooting Information" section displays:
This data can be copied to clipboard for pasting into support requests.
Sources: src/support.html src/js/support.js src/_locales/en/messages.json899-1018
Before rendering, dashboard.js polls the background with { what: 'readyToFilter' } every 250 ms until the response is truthy, ensuring filter engines are initialized before any pane is shown. The body's notReady CSS class is removed once the background is ready, making the dashboard visible.
The 3p-filters.js pane registers a listener via onBroadcast (imported from broadcast.js) to receive background-initiated events and update the list UI without requiring a full re-render:
Broadcast what | Handler action |
|---|---|
assetUpdated | updateAssetStatus(msg) — update cache/obsolete icons for one list entry |
assetsUpdated | Remove 'updating' body class, call renderWidgets() |
staticFilteringDataChanged | Call renderFilterLists() to rebuild the entire list tree |
Sources: src/js/dashboard.js106-127 src/js/3p-filters.js37-52
The Dashboard uses a consistent visual style defined in the common CSS files. Key styling features include:
Sources: src/css/common.css32-41 src/css/common.css42-382 src/css/3p-filters.css1-237 src/settings.html33-50
Filter lists display their status through various indicators:
These statuses are visually indicated with icons and color coding in the UI.
Sources: src/js/3p-filters.js320-337 src/css/3p-filters.css180-211
When changes are applied in the Dashboard, they are sent to the background script which then updates the Static Network Filtering Engine. The main interaction points are:
The actual filtering logic is handled by the Static Network Filtering Engine, which is a separate component of uBlock Origin. The Dashboard merely configures which filters are active.
Sources: src/js/3p-filters.js551-650
The Dashboard includes integration with cloud storage services to synchronize settings across devices. This is implemented through:
Sources: src/js/3p-filters.js827-883 src/js/settings.js28-120
The Dashboard is a central component of uBlock Origin that provides a user interface for configuring the extension's behavior. Its main responsibilities are:
Through its various pages, the Dashboard enables users to customize uBlock Origin's functionality while abstracting the complexity of the underlying filtering mechanisms.
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.